Move docs to project-docs symlink structure
- Docs now point to project-docs/docs/projects/cmdforge - Old docs preserved in olddocs/ - Updated .gitignore to ignore docs symlink 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
This commit is contained in:
Claude Opus 4.5
@@ -0,0 +1,264 @@
|
||||
# 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://[email protected]/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.
|
||||
Reference in New Issue
Block a user