Skip to content

config.md

Latest commit

 

History

History
481 lines (407 loc) · 9.98 KB

config.md

File metadata and controls

481 lines (407 loc) · 9.98 KB

Configuration Guide

ShellUI uses YAML configuration files to define commands, themes, security settings, and application behavior.

Configuration File Location

  • Development: config.yaml in project root
  • Production: /etc/shellui/config.yaml
  • Docker: Mounted volume /app/config/config.yaml

Basic Configuration Structure

# Application metadata
title: "ShellUI - My Server"
version: "1.0.0"
description: "Web interface for server management"

# Theme configuration
theme: "dark"  # light, dark, system, custom
theme_config:
  default_preset: "default"
  custom_theme:
    name: "Custom Theme"
    mode: "dark"
    colors:
      primary: "#3b82f6"
      accent: "#8b5cf6"
      background: "#0f172a"
      foreground: "#f8fafc"

# Features
features:
  auto_help: true
  show_command_help: true
  visual_param_builder: true
  real_time_output: true
  command_history: true

# Authentication
auth:
  enabled: true
  method: "local"  # local, jwt, oauth2
  users:
    - username: "admin"
      password: "secure_password"
      roles: ["admin"]
    - username: "user"
      password: "user_password"
      roles: ["user"]

# Commands
commands:
  - id: "system-info"
    title: "System Information"
    description: "Display system information"
    icon: "Terminal"
    category: "System"
    shell: "/bin/bash"
    command: "uname -a && df -h && free -h"
    timeout: 30000
    confirm: false
    hasHelp: true
    help_command: "man uname"

Theme Configuration

Built-in Themes

theme: "dark"  # Options: light, dark, system

Custom Theme

theme: "custom"
theme_config:
  custom_theme:
    name: "My Custom Theme"
    mode: "dark"
    colors:
      primary: "#3b82f6"
      accent: "#8b5cf6"
      background: "#0f172a"
      foreground: "#f8fafc"
      commandSuccess: "#10b981"
      commandError: "#ef4444"
      commandWarning: "#f59e0b"
      commandInfo: "#3b82f6"
    fontFamily: "Inter, system-ui, sans-serif"
    borderRadius: "0.5rem"
    animation:
      duration: "0.2s"
      easing: "ease-in-out"
    effects:
      blur: "8px"
      shadow: "0 4px 6px -1px rgba(0, 0, 0, 0.1)"
      glow: "0 0 20px rgba(59, 130, 246, 0.5)"

Command-specific Themes

theme_config:
  command_themes:
    - id: "dangerous-commands"
      theme:
        colors:
          primary: "#ef4444"
          commandError: "#dc2626"
      conditions:
        category: "Dangerous"
        tags: ["system", "critical"]

Authentication Configuration

Local Authentication

auth:
  enabled: true
  method: "local"
  users:
    - username: "admin"
      password: "admin_password"
      roles: ["admin"]
      permissions:
        - "execute:*"
        - "configure:*"
        - "view:*"
    - username: "user"
      password: "user_password"
      roles: ["user"]
      permissions:
        - "execute:system"
        - "view:history"

JWT Authentication

auth:
  enabled: true
  method: "jwt"
  jwt:
    secret: "your-secret-key"
    expiresIn: "24h"
    issuer: "shellui"
  users:
    - username: "admin"
      password: "admin_password"
      roles: ["admin"]

OAuth2 Authentication

auth:
  enabled: true
  method: "oauth2"
  oauth2:
    provider: "google"
    clientId: "your-client-id"
    clientSecret: "your-client-secret"
    redirectUri: "http://localhost:3000/auth/callback"
    scopes: ["openid", "email", "profile"]

Command Configuration

Basic Command

commands:
  - id: "hello-world"
    title: "Hello World"
    description: "Simple test command"
    icon: "Terminal"
    category: "Testing"
    shell: "/bin/bash"
    command: "echo 'Hello, World!'"

Command with Arguments

commands:
  - id: "ping-host"
    title: "Ping Host"
    description: "Ping a specific host"
    icon: "Wifi"
    category: "Network"
    shell: "/bin/bash"
    command: "ping -c {{ count }} {{ host }}"
    args:
      - name: "host"
        type: "text"
        label: "Host"
        placeholder: "Enter hostname or IP"
        required: true
        pattern: "^[a-zA-Z0-9.-]+$"
      - name: "count"
        type: "number"
        label: "Count"
        default: 4
        min: 1
        max: 10
        required: false

Command with Confirmation

commands:
  - id: "restart-service"
    title: "Restart Service"
    description: "Restart a system service"
    icon: "RefreshCw"
    category: "System"
    shell: "/bin/bash"
    command: "systemctl restart {{ service }}"
    confirm: true
    confirmMessage: "Are you sure you want to restart {{ service }}?"
    args:
      - name: "service"
        type: "select"
        label: "Service"
        options:
          - value: "nginx"
            label: "Nginx"
          - value: "apache2"
            label: "Apache"
          - value: "mysql"
            label: "MySQL"
        required: true

Command with Help

commands:
  - id: "docker-ps"
    title: "Docker Containers"
    description: "List Docker containers"
    icon: "Docker"
    category: "Containers"
    shell: "/bin/bash"
    command: "docker ps {{ format }}"
    hasHelp: true
    help_command: "docker ps --help"
    args:
      - name: "format"
        type: "select"
        label: "Format"
        options:
          - value: ""
            label: "Default"
          - value: "--format table"
            label: "Table"
          - value: "--format json"
            label: "JSON"

Advanced Command Features

Timeout Configuration

commands:
  - id: "long-running-task"
    title: "Long Running Task"
    description: "Task that might take a while"
    command: "sleep 60 && echo 'Done'"
    timeout: 120000  # 2 minutes in milliseconds

Environment Variables

commands:
  - id: "backup-database"
    title: "Backup Database"
    description: "Create database backup"
    command: "mysqldump -u $DB_USER -p$DB_PASS $DB_NAME > backup.sql"
    env:
      DB_USER: "root"
      DB_PASS: "password"
      DB_NAME: "myapp"

Working Directory

commands:
  - id: "git-status"
    title: "Git Status"
    description: "Check git repository status"
    command: "git status"
    workingDir: "/path/to/repository"

User and Group

commands:
  - id: "restart-nginx"
    title: "Restart Nginx"
    description: "Restart Nginx service"
    command: "systemctl restart nginx"
    user: "root"
    group: "root"

Security Configuration

Access Control Lists

security:
  acl:
    - name: "admin-commands"
      description: "Administrative commands"
      commands: ["restart-service", "system-update"]
      roles: ["admin"]
    - name: "user-commands"
      description: "User commands"
      commands: ["system-info", "ping-host"]
      roles: ["user", "admin"]

Rate Limiting

security:
  rateLimit:
    enabled: true
    windowMs: 900000  # 15 minutes
    maxRequests: 100  # limit each IP to 100 requests per windowMs
    message: "Too many requests from this IP"

Command Validation

security:
  validation:
    allowedCommands: ["echo", "ping", "systemctl", "docker"]
    blockedCommands: ["rm -rf /", "dd if=/dev/zero"]
    requireConfirmation: ["systemctl", "docker rm"]

Logging Configuration

logging:
  level: "info"  # debug, info, warn, error
  file: "/var/log/shellui/app.log"
  maxSize: "10m"
  maxFiles: 5
  audit:
    enabled: true
    file: "/var/log/shellui/audit.log"
    events: ["command_execute", "user_login", "config_change"]

API Configuration

api:
  enabled: true
  port: 3000
  cors:
    enabled: true
    origins: ["http://localhost:3000", "https://shellui.example.com"]
  rateLimit:
    enabled: true
    windowMs: 900000
    maxRequests: 1000

WebSocket Configuration

websocket:
  enabled: true
  port: 3001
  path: "/ws"
  pingInterval: 30000
  pingTimeout: 5000
  maxConnections: 100

Storage Configuration

storage:
  type: "json"  # json, sqlite, postgresql
  path: "/var/lib/shellui/data"
  retention:
    executions: "30d"  # Keep execution history for 30 days
    logs: "7d"         # Keep logs for 7 days
  backup:
    enabled: true
    interval: "24h"
    path: "/var/backups/shellui"

Environment Variables

You can override configuration values using environment variables:

# Application settings
export SHELLUI_TITLE="My ShellUI"
export SHELLUI_THEME="dark"
export SHELLUI_PORT=3000

# Authentication
export SHELLUI_AUTH_ENABLED=true
export SHELLUI_AUTH_SECRET="your-secret"

# Database
export SHELLUI_DB_HOST="localhost"
export SHELLUI_DB_PORT=5432
export SHELLUI_DB_NAME="shellui"
export SHELLUI_DB_USER="shellui"
export SHELLUI_DB_PASS="password"

# Logging
export SHELLUI_LOG_LEVEL="info"
export SHELLUI_LOG_FILE="/var/log/shellui/app.log"

Configuration Validation

ShellUI validates your configuration on startup. Common validation errors:

# ❌ Invalid - missing required fields
commands:
  - id: "test"
    title: "Test"
    # Missing: command, shell

# ✅ Valid
commands:
  - id: "test"
    title: "Test"
    command: "echo 'test'"
    shell: "/bin/bash"

Configuration Reload

ShellUI supports hot-reloading of configuration:

# Reload configuration
curl -X POST http://localhost:3000/api/config/reload

# Check configuration status
curl http://localhost:3000/api/config/status

Best Practices

  1. Use descriptive IDs: Use meaningful command IDs like restart-nginx instead of cmd1
  2. Group related commands: Use categories to organize commands logically
  3. Validate inputs: Always validate user inputs with patterns and constraints
  4. Set timeouts: Configure appropriate timeouts for long-running commands
  5. Use confirmation: Require confirmation for destructive commands
  6. Limit permissions: Follow the principle of least privilege
  7. Backup configuration: Regularly backup your configuration files
  8. Monitor logs: Set up log monitoring for security and debugging

Example Complete Configuration

See config.example.yaml for a complete example configuration file.