voxblog/QUICK_START.md

VoxBlog Quick Start Guide

🚀 Deploy to Production in 5 Minutes

Prerequisites

• VPS with Docker and Docker Compose installed
• Gitea repository set up
• Domain name (optional, for SSL)

Step 1: Clone Repository on VPS

ssh user@your-vps

# Navigate to your deployment directory
cd /var/www  # or /home/user/apps

# Clone from Gitea
git clone https://your-gitea-url/username/voxblog.git
cd voxblog

Step 2: Configure Environment

# Copy example env file
cp .env.example .env

# Edit with your values
nano .env

Fill in all values:

• MYSQL_ROOT_PASSWORD - Strong password for MySQL root
• MYSQL_PASSWORD - Password for voxblog database user
• ADMIN_PASSWORD - Password for admin login
• OPENAI_API_KEY - Your OpenAI API key
• GHOST_ADMIN_API_KEY - Your Ghost CMS API key
• S3_* - Your S3 credentials
• VITE_API_URL - Your API URL (e.g., https://api.yourdomain.com)

Step 3: Deploy

# Make deploy script executable
chmod +x deploy.sh

# Run deployment
./deploy.sh

That's it! Your application is now running:

• API: http://your-vps:3301
• Admin: http://your-vps:3300

Step 4: Set Up CI/CD (Choose One)

Option A: Gitea Actions (Recommended)

1. Install Gitea Runner on VPS:

# Download runner
wget https://dl.gitea.com/act_runner/latest/act_runner-latest-linux-amd64
chmod +x act_runner-latest-linux-amd64
sudo mv act_runner-latest-linux-amd64 /usr/local/bin/act_runner

# Register (get token from Gitea: Settings → Actions → Runners)
act_runner register \
  --instance https://your-gitea-url \
  --token YOUR_RUNNER_TOKEN \
  --name voxblog-runner

# Create systemd service
sudo tee /etc/systemd/system/gitea-runner.service > /dev/null <<EOF
[Unit]
Description=Gitea Actions Runner
After=network.target

[Service]
Type=simple
User=$USER
WorkingDirectory=$HOME
ExecStart=/usr/local/bin/act_runner daemon
Restart=always

[Install]
WantedBy=multi-user.target
EOF

# Start service
sudo systemctl daemon-reload
sudo systemctl enable gitea-runner
sudo systemctl start gitea-runner
sudo systemctl status gitea-runner

2. Add Secrets in Gitea:

Go to: Repository → Settings → Secrets → Actions

Add all variables from .env:

• MYSQL_ROOT_PASSWORD
• MYSQL_PASSWORD
• ADMIN_PASSWORD
• OPENAI_API_KEY
• GHOST_ADMIN_API_KEY
• S3_BUCKET
• S3_REGION
• S3_ACCESS_KEY
• S3_SECRET_KEY
• S3_ENDPOINT
• VITE_API_URL

3. Push to main branch - Deployment will trigger automatically!

Option B: Webhook (Alternative)

1. Install webhook listener:

sudo apt-get install webhook

# Create webhook config
sudo tee /etc/webhook.conf > /dev/null <<EOF
[
  {
    "id": "voxblog-deploy",
    "execute-command": "$(pwd)/deploy.sh",
    "command-working-directory": "$(pwd)",
    "response-message": "Deployment started"
  }
]
EOF

# Create systemd service
sudo tee /etc/systemd/system/webhook.service > /dev/null <<EOF
[Unit]
Description=Webhook Service
After=network.target

[Service]
Type=simple
ExecStart=/usr/bin/webhook -hooks /etc/webhook.conf -verbose -port 9000
Restart=always

[Install]
WantedBy=multi-user.target
EOF

# Start service
sudo systemctl daemon-reload
sudo systemctl enable webhook
sudo systemctl start webhook

2. Configure Gitea Webhook:

Repository → Settings → Webhooks → Add Webhook

• URL: http://your-vps:9000/hooks/voxblog-deploy
• Trigger: Push events on main branch

Step 5: Set Up Reverse Proxy (Optional but Recommended)

# Install nginx
sudo apt-get install nginx

# Create site config
sudo nano /etc/nginx/sites-available/voxblog

Paste this configuration:

server {
    listen 80;
    server_name yourdomain.com;

    # Admin frontend
    location / {
        proxy_pass http://localhost:3300;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    # API backend
    location /api {
        proxy_pass http://localhost:3301;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        
        # Long timeout for AI streaming
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
}

Enable site:

sudo ln -s /etc/nginx/sites-available/voxblog /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Step 6: Add SSL (Recommended)

# Install certbot
sudo apt-get install certbot python3-certbot-nginx

# Get certificate
sudo certbot --nginx -d yourdomain.com

# Auto-renewal is configured automatically

📊 Monitoring

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f api
docker-compose logs -f admin
docker-compose logs -f mysql

Check Status

docker-compose ps

Restart Services

# Restart all
docker-compose restart

# Restart specific service
docker-compose restart api

🔄 Updates

Every time you push to main branch:

1. Gitea Actions/Webhook triggers
2. Code is pulled
3. Docker images are rebuilt
4. Containers are restarted
5. Migrations run automatically
6. Health checks verify deployment

🛠️ Troubleshooting

Containers won't start

docker-compose logs api
docker-compose logs admin

Database issues

docker-compose exec mysql mysql -u voxblog -p
# Enter MYSQL_PASSWORD when prompted
SHOW DATABASES;

Port conflicts

sudo lsof -i :3301
sudo lsof -i :3300

Disk space

docker system df
docker system prune -a

Reset everything

docker-compose down -v  # WARNING: Deletes database!
./deploy.sh

📦 Backup

Database Backup

# Create backup
docker-compose exec mysql mysqldump -u voxblog -p voxblog > backup-$(date +%Y%m%d).sql

# Restore backup
docker-compose exec -T mysql mysql -u voxblog -p voxblog < backup-20241025.sql

Full Backup

# Backup data directory
tar -czf voxblog-data-$(date +%Y%m%d).tar.gz data/

# Backup database
docker-compose exec mysql mysqldump -u voxblog -p voxblog > db-backup-$(date +%Y%m%d).sql

🔐 Security Checklist

• Strong passwords in .env
• Firewall enabled (ufw)
• SSH key-based authentication
• SSL/TLS enabled (HTTPS)
• Regular backups configured
• Docker updated regularly
• Monitor logs for suspicious activity

🎯 Production Checklist

• .env file configured with production values
• Domain name pointed to VPS
• SSL certificate installed
• Nginx reverse proxy configured
• Gitea Actions/Webhook set up
• Secrets added to Gitea
• Backup strategy in place
• Monitoring set up
• Firewall configured
• Test deployment successful

📚 Additional Resources

• Full Deployment Guide
• Docker Compose Docs
• Gitea Actions Docs
• Nginx Docs

---

Need help? Check the logs first: docker-compose logs -f