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

```bash
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

```bash
# 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

```bash
# 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:**

```bash
# 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:**

```bash
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)

```bash
# Install nginx
sudo apt-get install nginx

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

Paste this configuration:

```nginx
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:

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

### Step 6: Add SSL (Recommended)

```bash
# 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

```bash
# 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

```bash
docker-compose ps
```

### Restart Services

```bash
# 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

```bash
docker-compose logs api
docker-compose logs admin
```

### Database issues

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

### Port conflicts

```bash
sudo lsof -i :3301
sudo lsof -i :3300
```

### Disk space

```bash
docker system df
docker system prune -a
```

### Reset everything

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

## 📦 Backup

### Database Backup

```bash
# 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

```bash
# 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](DEPLOYMENT_GUIDE.md)
- [Docker Compose Docs](https://docs.docker.com/compose/)
- [Gitea Actions Docs](https://docs.gitea.io/en-us/actions/)
- [Nginx Docs](https://nginx.org/en/docs/)

---

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