basil/docs/DEPLOYMENT-QUICK-START.md

Basil Deployment Quick Start

Quick reference for deploying Basil with CI/CD.

Initial Setup (One-time)

1. Gitea Secrets Configuration

Add these secrets in Gitea → Settings → Secrets → Actions:

DOCKER_USERNAME=your-dockerhub-username
DOCKER_PASSWORD=dckr_pat_xxxxxxxxxxxxx
DEPLOY_WEBHOOK_URL=http://your-server.com:9000/hooks/basil-deploy

2. Server Setup

# 1. Clone repository
cd /srv/docker-compose
git clone https://your-gitea.com/user/basil.git
cd basil

# 2. Create deployment configuration
cp .env.deploy.example .env.deploy
nano .env.deploy  # Edit with your values

# 3. Install webhook (Ubuntu/Debian)
sudo apt-get install webhook

# 4. Install systemd service
sudo cp scripts/basil-webhook.service /etc/systemd/system/
sudo nano /etc/systemd/system/basil-webhook.service  # Edit paths and env vars
sudo systemctl enable basil-webhook
sudo systemctl start basil-webhook

# 5. Configure firewall
sudo ufw allow 9000/tcp

Daily Usage

Automatic Deployment (Recommended)

Just push to main branch:

git add .
git commit -m "feat: add new feature"
git push origin main

The CI/CD pipeline will:

1. ✓ Run all tests
2. ✓ Build Docker images
3. ✓ Push to registry
4. ✓ Trigger webhook
5. ✓ Deploy automatically

Manual Deployment

cd /srv/docker-compose/basil
./scripts/manual-deploy.sh

Quick Commands

# View deployment logs
tail -f deploy.log

# View container logs
docker-compose logs -f api
docker-compose logs -f web

# Check deployment status
docker-compose ps

# Restart services
docker-compose restart

# Pull latest code and rebuild (without registry)
git pull
docker-compose up -d --build

# Create manual backup
curl -X POST http://localhost:3001/api/backup -o backup.zip

# Check webhook status
sudo systemctl status basil-webhook

# Test webhook manually
curl -X POST http://localhost:9000/hooks/basil-deploy \
  -H "X-Webhook-Secret: your-secret" \
  -H "Content-Type: application/json" \
  -d '{"branch": "main"}'

Rollback

# Deploy specific version
DOCKER_USERNAME=myuser IMAGE_TAG=main-abc123 ./scripts/deploy.sh

# Or restore from backup
cd backups
ls -lt  # Find backup file
curl -X POST http://localhost:3001/api/backup/restore \
  -F "file=@pre-deploy-20250101-020000.zip"

Troubleshooting One-Liners

# Deployment failed? Check logs
tail -50 deploy.log

# Webhook not working? Check service
sudo journalctl -u basil-webhook -n 50

# Containers not starting? Check Docker logs
docker-compose logs --tail=50

# Out of disk space?
docker system prune -a
df -h

# Database issues?
docker-compose exec api npx prisma studio

# Pull images manually
docker pull docker.io/$DOCKER_USERNAME/basil-api:latest
docker pull docker.io/$DOCKER_USERNAME/basil-web:latest

Workflow Diagram

┌──────────────┐
│  Developer   │
│  git push    │
└──────┬───────┘
       │
       ▼
┌──────────────────────────────┐
│     Gitea Actions            │
│  1. Run tests (unit + E2E)   │
│  2. Build Docker images      │
│  3. Push to Docker Hub       │
│  4. Call webhook             │
└──────┬───────────────────────┘
       │
       ▼
┌──────────────────────────────┐
│  Production Server           │
│  1. Webhook receives call    │
│  2. Run deploy.sh script     │
│     - Create backup          │
│     - Pull new images        │
│     - Restart containers     │
│     - Health check           │
└──────────────────────────────┘

File Locations

/srv/docker-compose/basil/
├── .gitea/workflows/ci-cd.yml          # CI/CD workflow
├── scripts/
│   ├── deploy.sh                       # Main deployment script
│   ├── manual-deploy.sh                # Interactive deployment
│   ├── webhook-receiver.sh             # Webhook server
│   └── basil-webhook.service           # Systemd service file
├── .env.deploy                         # Deployment config (gitignored)
├── deploy.log                          # Deployment logs
├── webhook.log                         # Webhook logs
└── backups/                            # Automatic backups
    └── pre-deploy-*.zip

Environment Variables

Required:

• DOCKER_USERNAME - Your Docker Hub username

Optional:

• DOCKER_REGISTRY - Default: docker.io
• IMAGE_TAG - Default: latest
• WEBHOOK_PORT - Default: 9000
• WEBHOOK_SECRET - Default: changeme (change this!)

Support

For detailed documentation, see:

• Full CI/CD Setup Guide
• Project Documentation
• Gitea Issues