nitrokite/deployment

MemberSyncPro Deployment

Simple deployment workflow using Ansible + Gitea Actions + Blue-Green deployment.

Overview

┌──────────────┐
│ 1. Ansible   │  Run once to set up infrastructure
│   Setup      │  (Gitea, PostgreSQL, Runners, Scripts)
└──────┬───────┘
       │
┌──────▼───────┐
│ 2. Push Code │  Push to Gitea triggers automatic build
│   to Gitea   │  and staging
└──────┬───────┘
       │
┌──────▼───────┐
│ 3. Promote   │  Manual promotion to production
│   to Prod    │  (sudo promote.sh)
└──────────────┘

One-Time Setup

1. Prepare Ansible Inventory

cd deployment/ansible
cp hosts.ini.example hosts.ini

Edit hosts.ini:

[git]
your-vps-ip ansible_user=ubuntu ansible_ssh_private_key_file=~/.ssh/your-key.pem ansible_python_interpreter=/usr/bin/python3

2. Set Database Passwords

export POSTGRES_ADMIN_PASSWORD="your-strong-password"
export API_SERVER_DB_PASSWORD="your-api-db-password"

3. Run Ansible Playbook

cd deployment/ansible

# Test connection
ansible -i hosts.ini git -m ping

# Deploy everything
ansible-playbook -i hosts.ini site.yml

This sets up:

• Gitea server (accessible at http://your-vps-ip)
• PostgreSQL databases (gitea + apiserver)
• 5 Gitea Actions runners
• Nginx reverse proxy
• API server deployment infrastructure at /opt/api-artifacts/
• Systemd service for the API server

4. Create Gitea Repository

1. Visit http://your-vps-ip
2. Create admin account (first-time setup)
3. Create repository: membersyncpro

5. Add Git Remote

git remote add production http://your-vps-ip/your-username/membersyncpro.git

Daily Deployment Workflow

Deploy New Version

# 1. Push code
git push production main

# 2. Wait for build (check Gitea → Actions)
#    - Builds binary
#    - Runs tests
#    - Stages to inactive slot (blue/green)

# 3. SSH to VPS and promote
ssh ubuntu@your-vps-ip
sudo /opt/api-artifacts/scripts/promote.sh
# Type 'yes' to confirm

# 4. Verify
curl http://localhost:8080/hello
curl http://localhost:8080/version

Rollback

If something goes wrong after promotion:

ssh ubuntu@your-vps-ip
sudo /opt/api-artifacts/scripts/rollback.sh

Instantly reverts to the previous deployment.

VPS Directory Structure

/opt/api-artifacts/
├── builds/
│   ├── abc123.../              # Previous build
│   └── def456.../              # Current build
├── blue -> builds/abc123/      # Previous deployment
├── green -> builds/def456/     # Current deployment
├── current -> green            # Active (systemd uses this)
├── scripts/
│   ├── deploy.sh               # Auto-called by CI
│   ├── promote.sh              # Manual promotion
│   ├── rollback.sh             # Emergency rollback
│   ├── health-check.sh         # Health validation
│   └── migrate.sh              # Database migrations
└── config/
    └── .env.production         # Environment variables

Common Tasks

View Service Logs

# Follow logs
journalctl -u api-server -f

# Last 100 lines
journalctl -u api-server -n 100

Check Active Deployment

# See which slot is active
readlink /opt/api-artifacts/current

# Full build path
readlink -f /opt/api-artifacts/current

Check Runners

# All runners
systemctl status gitea-runner-{1..5}

# Individual runner logs
journalctl -u gitea-runner-1 -f

List All Builds

ls -lh /opt/api-artifacts/builds/

Clean Old Builds

# Keep only last 10 builds
cd /opt/api-artifacts/builds
ls -t | tail -n +11 | xargs -I {} sudo rm -rf {}

Configuration

Environment Variables (on VPS)

Edit /opt/api-artifacts/config/.env.production:

DATABASE_URL=postgresql://apiserver:PASSWORD@localhost:5432/apiserver?sslmode=disable
AUTO_MIGRATE=false
PORT=8080
GIN_MODE=release

Ansible Variables

Edit deployment/ansible/site.yml:

vars:
  create_separate_apiserver_db: true  # Separate vs shared DB
  runner_count: 5                     # Number of runners
  gitea_version: "1.23.3"            # Gitea version

Blue-Green Deployment Flow

1. Current state: current -> blue (active)
2. New push: Build creates builds/new456/
3. Staging: green -> builds/new456/ (inactive)
4. Migrations: Run on green slot
5. Promotion: current -> green (switch!)
6. Restart: Systemd loads from current
7. Rollback available: Blue slot still has previous build

Troubleshooting

Build Not Triggering

# Check runners
systemctl status gitea-runner-1

# Runner logs
journalctl -u gitea-runner-1 -f

Deployment Fails

# Check deploy script logs
journalctl -u api-server -n 50

# Verify permissions
ls -la /opt/api-artifacts/

# Check database connection
cat /opt/api-artifacts/config/.env.production

Service Won't Start

# Service logs
journalctl -u api-server -n 50

# Verify binary exists
ls -la /opt/api-artifacts/current/api-server

# Check symlinks
readlink /opt/api-artifacts/current
readlink /opt/api-artifacts/blue
readlink /opt/api-artifacts/green

Files Reference

• ansible/site.yml - Complete infrastructure setup playbook
• ansible/hosts.ini - Your VPS inventory
• scripts/ - Deployment scripts (copied to VPS by Ansible)
• systemd/api-server.service - Service configuration
• .gitea/workflows/build-deploy.yml - CI/CD workflow

Ansible Playbook Details

The site.yml playbook handles:

1. Package installation: Git, Nginx, PostgreSQL, Docker
2. Gitea setup: Binary download, database, systemd service
3. Database provisioning: Admin user, API server user, databases
4. Runner deployment: 5 self-hosted runners with auto-registration
5. API infrastructure: User, directories, scripts, systemd service
6. Nginx configuration: Reverse proxy for Gitea
7. Firewall: UFW with SSH, HTTP, PostgreSQL ports

Run it multiple times safely (idempotent).

Security Notes

• Change default passwords (use environment variables)
• Use SSH keys for VPS access
• Keep .env.production file permissions at 600
• Review UFW firewall rules
• Consider adding SSL/TLS with Let's Encrypt
• PostgreSQL is exposed on 0.0.0.0 - restrict if not needed externally

Next Steps

After basic deployment:

1. Add SSL/TLS certificates (Let's Encrypt)
2. Set up monitoring (Prometheus/Grafana)
3. Configure alerting for deployment failures
4. Automate PostgreSQL backups
5. Add cron job to clean old builds