gui.do
Barazo Docker Compose templates for self-hosting
barazo.forum
1# Production Deployment Checklist
2
3Step-by-step checklist for deploying Barazo to production on a Hetzner VPS.
4
5This checklist covers the first production deployment of `barazo.forum`. For self-hosted installations, see [Installation Guide](installation.md).
6
7## Pre-Deployment
8
9### Server Provisioning
10
11- [ ] Provision Hetzner CX32 VPS (4 vCPU, 8 GB RAM, 80 GB SSD)
12 - Location: Falkenstein or Helsinki (EU)
13 - OS: Ubuntu 24.04 LTS
14- [ ] Note the server's IPv4 and IPv6 addresses
15- [ ] SSH into the server and verify access: `ssh root@<IP>`
16
17### DNS Configuration
18
19- [ ] Create A record: `barazo.forum` -> server IPv4
20- [ ] Create AAAA record: `barazo.forum` -> server IPv6
21- [ ] Verify DNS propagation: `dig +short barazo.forum`
22- [ ] Verify reverse DNS (optional but recommended for email deliverability): set PTR record in Hetzner Cloud console
23
24### Server Setup
25
26- [ ] Update system packages:
27 ```bash
28 apt update && apt upgrade -y
29 ```
30- [ ] Create non-root deploy user:
31 ```bash
32 adduser barazo
33 usermod -aG sudo barazo
34 ```
35- [ ] Copy SSH key for deploy user:
36 ```bash
37 su - barazo
38 mkdir -p ~/.ssh
39 # Add your public key to ~/.ssh/authorized_keys
40 chmod 700 ~/.ssh && chmod 600 ~/.ssh/authorized_keys
41 ```
42- [ ] Disable root SSH login (see [Security Hardening Guide](security-hardening.md))
43- [ ] Install Docker:
44 ```bash
45 curl -fsSL https://get.docker.com | sh
46 sudo usermod -aG docker barazo
47 # Log out and back in
48 ```
49- [ ] Verify Docker:
50 ```bash
51 docker --version # v24+
52 docker compose version # v2+
53 ```
54
55## Deployment
56
57### Application Setup
58
59- [ ] Clone deploy repo:
60 ```bash
61 git clone https://github.com/singi-labs/barazo-deploy.git
62 cd barazo-deploy
63 ```
64- [ ] Create `.env` from template:
65 ```bash
66 cp .env.example .env
67 ```
68- [ ] Generate secrets (run each one and paste into `.env`):
69 ```bash
70 # POSTGRES_PASSWORD
71 openssl rand -base64 24
72 # VALKEY_PASSWORD
73 openssl rand -base64 24
74 # TAP_ADMIN_PASSWORD
75 openssl rand -base64 24
76 # SESSION_SECRET
77 openssl rand -base64 32
78 # AI_ENCRYPTION_KEY (required for BYOK features)
79 openssl rand -base64 32
80 ```
81- [ ] Configure `.env` with production values:
82
83 | Variable | Value |
84 |----------|-------|
85 | `COMMUNITY_NAME` | `Barazo` |
86 | `COMMUNITY_DOMAIN` | `barazo.forum` |
87 | `COMMUNITY_MODE` | `global` |
88 | `POSTGRES_PASSWORD` | (generated above) |
89 | `VALKEY_PASSWORD` | (generated above) |
90 | `DATABASE_URL` | `postgresql://barazo_app:<POSTGRES_PASSWORD>@postgres:5432/barazo` |
91 | ~~`MIGRATION_DATABASE_URL`~~ | Not used in alpha. Reserved for beta when migrations are needed. |
92 | `TAP_ADMIN_PASSWORD` | (generated above) |
93 | `SESSION_SECRET` | (generated above) |
94 | `OAUTH_CLIENT_ID` | `https://barazo.forum` |
95 | `OAUTH_REDIRECT_URI` | `https://barazo.forum/api/auth/callback` |
96 | `NEXT_PUBLIC_SITE_URL` | `https://barazo.forum` |
97 | `GLITCHTIP_DSN` | (production GlitchTip DSN) |
98 | `AI_ENCRYPTION_KEY` | (generated above) |
99
100- [ ] Pin Docker image versions in `docker-compose.yml`:
101 ```yaml
102 barazo-api:
103 image: ghcr.io/singi-labs/barazo-api:X.Y.Z
104 barazo-web:
105 image: ghcr.io/singi-labs/barazo-web:X.Y.Z
106 ```
107- [ ] Verify no `CHANGE_ME` values remain:
108 ```bash
109 grep -n "CHANGE_ME" .env
110 ```
111
112### Start Services
113
114- [ ] Pull images:
115 ```bash
116 docker compose pull
117 ```
118- [ ] Start the stack:
119 ```bash
120 docker compose up -d
121 ```
122- [ ] Watch startup logs:
123 ```bash
124 docker compose logs -f
125 ```
126
127## Post-Deployment Verification
128
129### Health Checks
130
131- [ ] All containers healthy:
132 ```bash
133 docker compose ps
134 # All services should show "healthy"
135 ```
136- [ ] API health check:
137 ```bash
138 curl -s https://barazo.forum/api/health | jq .
139 ```
140- [ ] Run smoke test:
141 ```bash
142 ./scripts/smoke-test.sh https://barazo.forum
143 ```
144
145### SSL Verification
146
147- [ ] HTTPS works: visit `https://barazo.forum` in browser
148- [ ] HTTP redirects to HTTPS: `curl -I http://barazo.forum`
149- [ ] Certificate is valid:
150 ```bash
151 echo | openssl s_client -connect barazo.forum:443 -servername barazo.forum 2>/dev/null | openssl x509 -noout -dates
152 ```
153- [ ] HSTS header present:
154 ```bash
155 curl -sI https://barazo.forum | grep -i strict-transport
156 ```
157
158### Functional Verification
159
160- [ ] Homepage renders in browser
161- [ ] OAuth login redirects to Bluesky correctly
162- [ ] API documentation accessible at `https://barazo.forum/docs`
163- [ ] `/api/health/ready` blocked externally (returns 403):
164 ```bash
165 curl -s -o /dev/null -w "%{http_code}" https://barazo.forum/api/health/ready
166 ```
167
168### Backup Setup
169
170- [ ] Generate backup encryption keypair:
171 ```bash
172 sudo apt install age
173 age-keygen -o barazo-backup-key.txt
174 # Add public key to .env as BACKUP_PUBLIC_KEY
175 # Store private key OFF-SERVER (e.g., password manager)
176 ```
177- [ ] Test backup:
178 ```bash
179 ./scripts/backup.sh --encrypt
180 ls -lh backups/
181 ```
182- [ ] Set up automated daily backups:
183 ```bash
184 crontab -e
185 ```
186 ```
187 0 2 * * * cd /home/barazo/barazo-deploy && ./scripts/backup.sh --encrypt >> /var/log/barazo-backup.log 2>&1
188 ```
189- [ ] Verify backup cron runs (check next day):
190 ```bash
191 ls -lh backups/
192 tail /var/log/barazo-backup.log
193 ```
194
195### Monitoring
196
197- [ ] GlitchTip DSN configured and receiving events
198- [ ] Test error reporting:
199 ```bash
200 # Trigger a test error via the API (if endpoint exists)
201 # Or check GlitchTip dashboard for startup events
202 ```
203- [ ] Log output visible:
204 ```bash
205 docker compose logs --tail=20 barazo-api
206 ```
207
208### Security Hardening
209
210- [ ] Complete the [Security Hardening Guide](security-hardening.md) checklist
211- [ ] Firewall configured (only 22, 80, 443 open)
212- [ ] SSH root login disabled
213- [ ] Unattended upgrades enabled
214
215## Ongoing Operations
216
217### Upgrades
218
219See [Upgrade Guide](upgrading.md) for the standard upgrade process:
220
221```bash
222# Update image tags in docker-compose.yml, then:
223docker compose pull
224docker compose up -d
225```
226
227### Rollback
228
229If an upgrade causes issues:
230
231```bash
232# Revert image tags in docker-compose.yml to previous versions, then:
233docker compose pull
234docker compose up -d
235```
236
237During alpha, the database schema is rebuilt on deploy. If a schema change causes issues, restore from backup (see [Backup & Restore](backups.md)).
238
239### Daily Checks
240
241- [ ] `docker compose ps` -- all services healthy
242- [ ] Check GlitchTip for new errors
243- [ ] Verify backup ran (check `/var/log/barazo-backup.log`)