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

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

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

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

## Quick Commands

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

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

```bash
# 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](./CI-CD-SETUP.md)
- [Project Documentation](../CLAUDE.md)
- [Gitea Issues](https://your-gitea.com/user/basil/issues)