Skip to content

README.md

Latest commit

 

History

History
271 lines (200 loc) · 5.62 KB

README.md

File metadata and controls

271 lines (200 loc) · 5.62 KB

Installation Guide

ShellUI can be installed on various platforms and environments. Choose the installation method that best fits your needs.

Prerequisites

  • Node.js 18+ or Bun 1.0+
  • Linux/Unix system with shell access
  • Modern web browser (Chrome, Firefox, Safari, Edge)

Installation Methods

1. Development Installation (Recommended for testing)

This is the easiest way to get started with ShellUI for development and testing.

# Clone the repository
git clone https://github.com/your-username/shellui.git
cd shellui

# Install dependencies
bun install

# Copy configuration template
cp config.example.yaml config.yaml

# Edit configuration
nano config.yaml

# Start development server
bun dev

The application will be available at http://localhost:3000

2. Production Installation

For production deployments, we recommend using Docker or a system service.

Using Docker

# Pull the image
docker pull shellui/shellui:latest

# Create configuration directory
mkdir -p /opt/shellui/config

# Copy configuration
cp config.yaml /opt/shellui/config/

# Run container
docker run -d \
  --name shellui \
  -p 3000:3000 \
  -v /opt/shellui/config:/app/config \
  -v /opt/shellui/data:/app/data \
  shellui/shellui:latest

Using System Service

  1. Install globally

    npm install -g shellui
# or
bun install -g shellui

  2. Create systemd service

    sudo nano /etc/systemd/system/shellui.service
    [Unit]
Description=ShellUI Web Interface
After=network.target

[Service]
Type=simple
User=shellui
WorkingDirectory=/opt/shellui
ExecStart=/usr/bin/bun run start
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

  3. Enable and start service

    sudo systemctl daemon-reload
sudo systemctl enable shellui
sudo systemctl start shellui

3. Package Manager Installation

Debian/Ubuntu

# Add repository (when available)
curl -fsSL https://packages.shellui.dev/gpg | sudo gpg --dearmor -o /usr/share/keyrings/shellui-archive-keyring.gpg
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/shellui-archive-keyring.gpg] https://packages.shellui.dev/deb stable main" | sudo tee /etc/apt/sources.list.d/shellui.list

# Install
sudo apt update
sudo apt install shellui

RPM-based (Fedora, CentOS, RHEL)

# Add repository (when available)
sudo dnf install https://packages.shellui.dev/rpm/shellui.repo
sudo dnf install shellui

Configuration

After installation, you need to configure ShellUI:

  1. Copy example configuration

    cp /etc/shellui/config.example.yaml /etc/shellui/config.yaml

  2. Edit configuration

    sudo nano /etc/shellui/config.yaml

  3. Set permissions

    sudo chown -R shellui:shellui /etc/shellui
sudo chmod 600 /etc/shellui/config.yaml

Initial Setup

  1. Access the web interface Open http://localhost:3000 in your browser

  2. Create admin user

    • Click "Setup" on first run
    • Create your admin account
    • Configure initial commands

  3. Test a command

    • Try the built-in "System Info" command
    • Verify real-time output works

Security Considerations

File Permissions

# Secure configuration directory
sudo chown -R shellui:shellui /etc/shellui
sudo chmod 755 /etc/shellui
sudo chmod 600 /etc/shellui/config.yaml

# Secure data directory
sudo chown -R shellui:shellui /var/lib/shellui
sudo chmod 755 /var/lib/shellui

Firewall Configuration

# Allow ShellUI port
sudo ufw allow 3000/tcp

# Or for specific IP ranges
sudo ufw allow from 192.168.1.0/24 to any port 3000

Reverse Proxy (Recommended)

For production, use a reverse proxy like Nginx:

server {
    listen 80;
    server_name shellui.yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

Troubleshooting

Common Issues

  1. Port already in use

    # Check what's using port 3000
sudo netstat -tlnp | grep :3000

# Kill process or change port in config
sudo kill -9 <PID>

  2. Permission denied

    # Fix ownership
sudo chown -R $USER:$USER /opt/shellui

  3. WebSocket connection failed

    • Check firewall settings
    • Verify reverse proxy configuration
    • Check browser console for errors

Logs

# View application logs
sudo journalctl -u shellui -f

# View Docker logs
docker logs shellui

# View development logs
bun dev 2>&1 | tee shellui.log

Health Check

# Check if service is running
curl http://localhost:3000/health

# Expected response
{
  "status": "ok",
  "timestamp": "2024-01-01T12:00:00.000Z",
  "uptime": 3600,
  "version": "1.0.0"
}

Next Steps

After successful installation:

  1. Read the Configuration Guide
  2. Explore Command Examples
  3. Set up Authentication
  4. Configure Reverse Proxy

Support

If you encounter issues during installation: