5.6 KiB

Raw Permalink Blame History

CmdForge Deployment Guide

This guide covers deploying the CmdForge Registry web application.

Quick Start (Development)

# 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

# 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:

# 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

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:

[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:

# 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:

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:

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

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

# 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

# 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

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

Troubleshooting

Service won't start

# 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

# 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

# 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.

5.6 KiB Raw Permalink Blame History