CmdForge/docs/DEPLOYMENT.md

# CmdForge Deployment Guide

This guide covers deploying the CmdForge Registry web application.

## Quick Start (Development)

```bash
# Clone and install
git clone https://gitea.brrd.tech/rob/CmdForge.git
cd CmdForge
pip install -e ".[dev]"

# Initialize database
cd src/cmdforge/web
python -c "from app import create_app; create_app()"

# Run development server
flask run --port 5050 --host 0.0.0.0
```

Access at `http://localhost:5050`

## Production Deployment

### Prerequisites

- Python 3.8+
- pip/pipx
- nginx (recommended for reverse proxy)
- systemd (for process management)

### 1. Install Application

```bash
# Create application directory
sudo mkdir -p /opt/cmdforge
sudo chown $USER:$USER /opt/cmdforge
cd /opt/cmdforge

# Clone repository
git clone https://gitea.brrd.tech/rob/CmdForge.git .

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -e ".[prod]"
pip install gunicorn
```

### 2. Configure Environment

Create `/opt/cmdforge/.env`:

```bash
# Required
FLASK_ENV=production
SECRET_KEY=your-secret-key-here  # Generate with: python -c "import secrets; print(secrets.token_hex(32))"

# Optional
SENTRY_DSN=https://xxx@sentry.io/xxx  # Error monitoring
SITE_URL=https://cmdforge.brrd.tech  # For sitemap/SEO
```

### 3. Initialize Database

```bash
cd /opt/cmdforge/src/cmdforge/web
python -c "from app import create_app; create_app()"
```

Database will be created at `data/cmdforge.db`.

### 4. systemd Service

Create `/etc/systemd/system/cmdforge-web.service`:

```ini
[Unit]
Description=CmdForge Registry Web Application
After=network.target

[Service]
Type=simple
User=www-data
Group=www-data
WorkingDirectory=/opt/cmdforge
Environment="PATH=/opt/cmdforge/venv/bin"
EnvironmentFile=/opt/cmdforge/.env
ExecStart=/opt/cmdforge/venv/bin/gunicorn \
    --workers 4 \
    --bind 127.0.0.1:5050 \
    --access-logfile /var/log/cmdforge/access.log \
    --error-logfile /var/log/cmdforge/error.log \
    'cmdforge.web.app:create_app()'
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

Enable and start:

```bash
# Create log directory
sudo mkdir -p /var/log/cmdforge
sudo chown www-data:www-data /var/log/cmdforge

# Enable service
sudo systemctl daemon-reload
sudo systemctl enable cmdforge-web
sudo systemctl start cmdforge-web

# Check status
sudo systemctl status cmdforge-web
```

### 5. nginx Configuration

Create `/etc/nginx/sites-available/cmdforge`:

```nginx
server {
    listen 80;
    server_name cmdforge.brrd.tech;

    # Redirect HTTP to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name cmdforge.brrd.tech;

    # SSL certificates (use certbot for Let's Encrypt)
    ssl_certificate /etc/letsencrypt/live/cmdforge.brrd.tech/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/cmdforge.brrd.tech/privkey.pem;

    # SSL settings
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;

    # Static files (optional - Flask can serve these)
    location /static/ {
        alias /opt/cmdforge/src/cmdforge/web/static/;
        expires 1d;
        add_header Cache-Control "public, immutable";
    }

    # Proxy to gunicorn
    location / {
        proxy_pass http://127.0.0.1:5050;
        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;
    }
}
```

Enable site:

```bash
sudo ln -s /etc/nginx/sites-available/cmdforge /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
```

### 6. SSL with Let's Encrypt

```bash
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d cmdforge.brrd.tech
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `FLASK_ENV` | Yes | `production` or `development` |
| `SECRET_KEY` | Yes | Secret key for sessions (32+ chars) |
| `SENTRY_DSN` | No | Sentry error monitoring DSN |
| `SITE_URL` | No | Public URL for sitemap generation |
| `DATABASE_PATH` | No | Override database path (default: `data/cmdforge.db`) |

## Database Backup

```bash
# Backup
cp /opt/cmdforge/data/cmdforge.db /backup/cmdforge-$(date +%Y%m%d).db

# Or use SQLite backup command for consistency
sqlite3 /opt/cmdforge/data/cmdforge.db ".backup '/backup/cmdforge.db'"
```

## Monitoring

### Logs

```bash
# Application logs
tail -f /var/log/cmdforge/error.log
tail -f /var/log/cmdforge/access.log

# systemd logs
journalctl -u cmdforge-web -f
```

### Sentry Integration

The application includes Sentry integration for error monitoring. Set `SENTRY_DSN` environment variable to enable.

### Health Check

```bash
curl http://localhost:5050/api/v1/tools
```

## Troubleshooting

### Service won't start

```bash
# Check logs
journalctl -u cmdforge-web -n 50

# Verify Python path
/opt/cmdforge/venv/bin/python -c "import cmdforge"

# Test gunicorn manually
cd /opt/cmdforge
source venv/bin/activate
gunicorn --bind 127.0.0.1:5050 'cmdforge.web.app:create_app()'
```

### Database errors

```bash
# Check database exists and is readable
ls -la /opt/cmdforge/data/cmdforge.db

# Verify permissions
chown www-data:www-data /opt/cmdforge/data/
chown www-data:www-data /opt/cmdforge/data/cmdforge.db
```

### Static files not loading

```bash
# Rebuild Tailwind CSS
cd /opt/cmdforge
npm install
npm run css:build

# Or use development CSS
# (static/css/output.css should exist)
```

## Architecture Diagram

See `docs/diagrams/deployment-architecture.svg` for visual representation.