389 lines
9.5 KiB
Markdown
389 lines
9.5 KiB
Markdown
# VoxBlog Production Deployment - Complete Setup
|
||
|
||
## 🎉 What's Been Created
|
||
|
||
Your VoxBlog project is now **production-ready** with a complete CI/CD pipeline!
|
||
|
||
### Files Created
|
||
|
||
```
|
||
voxblog/
|
||
├── docker/
|
||
│ ├── api.Dockerfile ✅ Backend Docker image
|
||
│ ├── admin.Dockerfile ✅ Frontend Docker image
|
||
│ └── nginx.conf ✅ Nginx config for frontend
|
||
├── .gitea/
|
||
│ └── workflows/
|
||
│ └── deploy.yml ✅ Gitea Actions CI/CD workflow
|
||
├── docker-compose.yml ✅ Multi-container orchestration
|
||
├── deploy.sh ✅ Deployment script (executable)
|
||
├── .dockerignore ✅ Docker build optimization
|
||
├── .env.example ✅ Updated with all variables
|
||
├── DEPLOYMENT_GUIDE.md ✅ Complete deployment documentation
|
||
└── QUICK_START.md ✅ 5-minute setup guide
|
||
```
|
||
|
||
## 🏗️ Architecture
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ Your VPS Server │
|
||
│ │
|
||
│ ┌────────────┐ ┌──────────────┐ ┌─────────────┐ │
|
||
│ │ Gitea │→ │ Gitea Runner │→ │ Docker │ │
|
||
│ │ Repository │ │ (CI/CD) │ │ Containers │ │
|
||
│ └────────────┘ └──────────────┘ └─────────────┘ │
|
||
│ ↓ │
|
||
│ ┌────────────────────────┐ │
|
||
│ │ voxblog-api:3301 │ │
|
||
│ │ voxblog-admin:3300 │ │
|
||
│ │ mysql:3306 │ │
|
||
│ └────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 🚀 Deployment Options
|
||
|
||
### Option 1: Gitea Actions (Recommended)
|
||
|
||
**Pros:**
|
||
- ✅ Fully automated
|
||
- ✅ Built-in to Gitea
|
||
- ✅ GitHub Actions compatible
|
||
- ✅ Detailed logs and status
|
||
- ✅ Secrets management
|
||
|
||
**Setup:**
|
||
1. Install Gitea Runner on VPS
|
||
2. Add secrets to Gitea repository
|
||
3. Push to main → auto-deploy!
|
||
|
||
### Option 2: Webhook + Script
|
||
|
||
**Pros:**
|
||
- ✅ Simple and lightweight
|
||
- ✅ No additional services needed
|
||
- ✅ Direct script execution
|
||
- ✅ Easy to debug
|
||
|
||
**Setup:**
|
||
1. Install webhook listener
|
||
2. Configure Gitea webhook
|
||
3. Push to main → webhook triggers deploy.sh
|
||
|
||
### Option 3: Manual Deployment
|
||
|
||
**Pros:**
|
||
- ✅ Full control
|
||
- ✅ No setup required
|
||
- ✅ Good for testing
|
||
|
||
**Usage:**
|
||
```bash
|
||
ssh user@vps
|
||
cd /path/to/voxblog
|
||
./deploy.sh
|
||
```
|
||
|
||
## 📋 Deployment Workflow
|
||
|
||
```
|
||
Developer commits code
|
||
↓
|
||
Push to main branch
|
||
↓
|
||
Gitea detects push
|
||
↓
|
||
┌─────────────────────────────┐
|
||
│ Gitea Actions / Webhook │
|
||
│ triggers deployment │
|
||
└─────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────┐
|
||
│ deploy.sh executes: │
|
||
│ 1. Pull latest code │
|
||
│ 2. Build Docker images │
|
||
│ 3. Stop old containers │
|
||
│ 4. Start new containers │
|
||
│ 5. Run DB migrations │
|
||
│ 6. Health checks │
|
||
│ 7. Clean up old images │
|
||
└─────────────────────────────┘
|
||
↓
|
||
✅ Deployment Complete!
|
||
```
|
||
|
||
## 🎯 Quick Start (5 Minutes)
|
||
|
||
### 1. On Your VPS
|
||
|
||
```bash
|
||
# Clone repository
|
||
git clone https://your-gitea-url/username/voxblog.git
|
||
cd voxblog
|
||
|
||
# Load Infisical token (preferred)
|
||
export INFISICAL_TOKEN=st.your_service_token
|
||
export INFISICAL_SITE_URL=https://secrets.pusula.blog
|
||
|
||
# Deploy!
|
||
./deploy.sh
|
||
|
||
# For local testing only
|
||
# cp .env.example .env && nano .env
|
||
```
|
||
|
||
### 2. Set Up CI/CD
|
||
|
||
**For Gitea Actions:**
|
||
```bash
|
||
# Install 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 and start
|
||
act_runner register --instance https://your-gitea --token YOUR_TOKEN
|
||
# Then set up as systemd service (see QUICK_START.md)
|
||
```
|
||
|
||
**For Webhook:**
|
||
```bash
|
||
sudo apt-get install webhook
|
||
# Configure webhook (see QUICK_START.md)
|
||
```
|
||
|
||
### 3. Configure Secrets (Gitea Actions only)
|
||
|
||
Repository → Settings → Secrets:
|
||
- `INFISICAL_TOKEN` – service token scoped to the production workspace/path.
|
||
- `INFISICAL_SITE_URL` – `https://secrets.pusula.blog` (already running on your VPS).
|
||
|
||
All application variables now live inside Infisical instead of `.env`.
|
||
|
||
### 4. Push to Main
|
||
|
||
```bash
|
||
git add .
|
||
git commit -m "Add deployment configuration"
|
||
git push origin main
|
||
```
|
||
|
||
🎉 **Auto-deployment triggered!**
|
||
|
||
## 🔧 Secrets Inventory
|
||
|
||
Store these keys inside Infisical (`production` environment):
|
||
|
||
```bash
|
||
# Database (all use DB_* prefix)
|
||
DB_ROOT_PASSWORD=strong_password
|
||
DB_PASSWORD=voxblog_password
|
||
DB_USER=voxblog
|
||
DB_NAME=voxblog
|
||
DB_HOST=mysql
|
||
DB_PORT=3306
|
||
|
||
# Application
|
||
ADMIN_PASSWORD=admin_password
|
||
OPENAI_API_KEY=sk-...
|
||
GHOST_ADMIN_API_KEY=...
|
||
GHOST_ADMIN_API_URL=https://ghost.yourdomain.com
|
||
|
||
# S3 Storage
|
||
S3_BUCKET=your-bucket
|
||
S3_REGION=us-east-1
|
||
S3_ACCESS_KEY=...
|
||
S3_SECRET_KEY=...
|
||
S3_ENDPOINT=https://s3.amazonaws.com
|
||
|
||
# Frontend
|
||
VITE_API_URL=https://api.yourdomain.com
|
||
```
|
||
|
||
## 🌐 Production Setup
|
||
|
||
### With Domain Name
|
||
|
||
1. **Point DNS to VPS**
|
||
```
|
||
A Record: @ → your-vps-ip
|
||
A Record: api → your-vps-ip
|
||
```
|
||
|
||
2. **Install Nginx**
|
||
```bash
|
||
sudo apt-get install nginx
|
||
# Configure (see QUICK_START.md)
|
||
```
|
||
|
||
3. **Add SSL**
|
||
```bash
|
||
sudo certbot --nginx -d yourdomain.com
|
||
```
|
||
|
||
### Without Domain (IP Only)
|
||
|
||
Access directly:
|
||
- Admin: `http://your-vps-ip:3300`
|
||
- API: `http://your-vps-ip:3301`
|
||
|
||
## 📊 Monitoring & Maintenance
|
||
|
||
### View Logs
|
||
```bash
|
||
docker-compose logs -f
|
||
docker-compose logs -f api
|
||
docker-compose logs -f admin
|
||
```
|
||
|
||
### Check Status
|
||
```bash
|
||
docker-compose ps
|
||
docker ps
|
||
```
|
||
|
||
### Restart Services
|
||
```bash
|
||
docker-compose restart
|
||
docker-compose restart api
|
||
```
|
||
|
||
### Backup Database
|
||
```bash
|
||
docker-compose exec mysql mysqldump -u voxblog -p voxblog > backup.sql
|
||
```
|
||
|
||
### Clean Up
|
||
```bash
|
||
docker system prune -a
|
||
docker volume prune
|
||
```
|
||
|
||
## 🔐 Security Best Practices
|
||
|
||
- ✅ Store strong secrets in Infisical and rotate them regularly
|
||
- ✅ Remove stray `.env` files from servers and keep them out of git (already ignored)
|
||
- ✅ Enable firewall: `sudo ufw enable`
|
||
- ✅ Use SSL/TLS (HTTPS)
|
||
- ✅ Keep Docker updated
|
||
- ✅ Regular backups
|
||
- ✅ Monitor logs for suspicious activity
|
||
- ✅ Use SSH keys instead of passwords
|
||
|
||
## 🐛 Troubleshooting
|
||
|
||
### Deployment Failed
|
||
|
||
```bash
|
||
# Check logs
|
||
docker-compose logs
|
||
|
||
# Check specific service
|
||
docker-compose logs api
|
||
|
||
# Restart
|
||
docker-compose restart
|
||
```
|
||
|
||
### Port Already in Use
|
||
|
||
```bash
|
||
# Find process
|
||
sudo lsof -i :3301
|
||
sudo lsof -i :3300
|
||
|
||
# Kill process
|
||
sudo kill -9 <PID>
|
||
```
|
||
|
||
### Out of Disk Space
|
||
|
||
```bash
|
||
# Check usage
|
||
docker system df
|
||
|
||
# Clean up
|
||
docker system prune -a
|
||
docker volume prune
|
||
```
|
||
|
||
### Database Connection Failed
|
||
|
||
```bash
|
||
# Check MySQL
|
||
docker-compose exec mysql mysql -u voxblog -p
|
||
|
||
# Check environment variables
|
||
docker-compose exec api env | grep DATABASE
|
||
```
|
||
|
||
## 📚 Documentation
|
||
|
||
- **[DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md)** - Complete deployment guide
|
||
- **[QUICK_START.md](QUICK_START.md)** - 5-minute setup
|
||
- **[REFACTORING_SUMMARY.md](apps/api/REFACTORING_SUMMARY.md)** - API refactoring details
|
||
- **[STREAMING_GUIDE.md](apps/api/STREAMING_GUIDE.md)** - AI streaming implementation
|
||
|
||
## 🎯 Next Steps
|
||
|
||
1. **Test Locally First**
|
||
```bash
|
||
docker-compose up --build
|
||
```
|
||
|
||
2. **Deploy to VPS**
|
||
```bash
|
||
./deploy.sh
|
||
```
|
||
|
||
3. **Set Up CI/CD**
|
||
- Choose Gitea Actions or Webhook
|
||
- Configure secrets
|
||
- Test auto-deployment
|
||
|
||
4. **Configure Domain & SSL**
|
||
- Point DNS
|
||
- Install Nginx
|
||
- Get SSL certificate
|
||
|
||
5. **Set Up Monitoring**
|
||
- Configure log rotation
|
||
- Set up uptime monitoring
|
||
- Configure backups
|
||
|
||
6. **Go Live!** 🚀
|
||
|
||
## ✅ Production Readiness Checklist
|
||
|
||
- [ ] Docker files created
|
||
- [ ] docker-compose.yml configured
|
||
- [ ] Infisical production workspace populated with VoxBlog secrets
|
||
- [ ] deploy.sh tested locally
|
||
- [ ] CI/CD pipeline chosen and configured
|
||
- [ ] INFISICAL_TOKEN (+ optional INFISICAL_SITE_URL) added to Gitea secrets
|
||
- [ ] Domain DNS configured (optional)
|
||
- [ ] Nginx reverse proxy set up (optional)
|
||
- [ ] SSL certificate installed (optional)
|
||
- [ ] Firewall configured
|
||
- [ ] Backup strategy in place
|
||
- [ ] Test deployment successful
|
||
- [ ] Health checks passing
|
||
- [ ] Logs accessible and monitored
|
||
|
||
## 🎉 You're Ready!
|
||
|
||
Your VoxBlog project is now production-ready with:
|
||
- ✅ Dockerized backend and frontend
|
||
- ✅ Automated CI/CD pipeline
|
||
- ✅ Database with migrations
|
||
- ✅ Health checks
|
||
- ✅ Easy rollback
|
||
- ✅ Comprehensive documentation
|
||
|
||
**Push to main and watch it deploy automatically!** 🚀
|
||
|
||
---
|
||
|
||
**Questions?** Check the documentation or review the logs: `docker-compose logs -f`
|