gui.do
Barazo Docker Compose templates for self-hosting
barazo.forum
1# Administration Guide
2
3Day-to-day administration of a running Barazo instance.
4
5## Monitoring
6
7### Service Status
8
9```bash
10# Check all services
11docker compose ps
12
13# Check specific service
14docker compose ps barazo-api
15```
16
17All services should show `healthy` status.
18
19### Logs
20
21```bash
22# All services
23docker compose logs -f
24
25# Specific service (last 100 lines, follow)
26docker compose logs -f --tail 100 barazo-api
27
28# Specific service without follow
29docker compose logs --tail 50 postgres
30```
31
32### Smoke Test
33
34Run the smoke test to verify everything is working:
35
36```bash
37./scripts/smoke-test.sh https://your-domain.com
38```
39
40### Resource Usage
41
42```bash
43docker stats --no-stream
44```
45
46## Backups
47
48### Automated Backups (Recommended)
49
50Set up a daily backup via cron:
51
52```bash
53crontab -e
54```
55
56Add this line (runs daily at 2 AM):
57
58```
590 2 * * * cd /path/to/barazo-deploy && ./scripts/backup.sh --encrypt >> /var/log/barazo-backup.log 2>&1
60```
61
62Requires `BACKUP_PUBLIC_KEY` in your `.env` file.
63
64### Manual Backup
65
66```bash
67./scripts/backup.sh # Unencrypted (local storage only)
68./scripts/backup.sh --encrypt # Encrypted (safe for off-server storage)
69```
70
71Backups are saved to `./backups/` with timestamps. Old backups are automatically cleaned up after 7 days (configurable via `BACKUP_RETAIN_DAYS`).
72
73### Restore
74
75```bash
76./scripts/restore.sh backups/barazo-backup-20260214-020000.sql.gz
77```
78
79See [Backup & Restore](backups.md) for full documentation.
80
81## Common Tasks
82
83### Restart a Service
84
85```bash
86docker compose restart barazo-api
87```
88
89### Stop Everything
90
91```bash
92docker compose down # Stops containers (preserves data)
93docker compose down -v # Stops containers AND deletes all data
94```
95
96### Connect to Database
97
98```bash
99docker compose exec postgres psql -U barazo
100```
101
102### View Caddy Access Logs
103
104```bash
105docker compose logs caddy
106```
107
108### Force SSL Certificate Renewal
109
110Caddy renews certificates automatically. If you need to force renewal:
111
112```bash
113docker compose restart caddy
114```
115
116### Update Images Without Restart
117
118```bash
119docker compose pull # Pull new images
120docker compose up -d # Restart only changed services
121```
122
123## Troubleshooting
124
125### Service Won't Start
126
127```bash
128# Check the logs
129docker compose logs <service-name>
130
131# Check if port is already in use
132sudo lsof -i :80
133sudo lsof -i :443
134```
135
136### Out of Disk Space
137
138```bash
139# Check disk usage
140df -h
141
142# Clean up Docker resources
143docker system prune -f # Remove stopped containers, unused images
144docker volume prune -f # Remove unused volumes (careful!)
145```
146
147### High Memory Usage
148
149Check which service is consuming memory:
150
151```bash
152docker stats --no-stream
153```
154
155Consider enabling resource limits in `docker-compose.yml` (uncomment the `mem_limit` lines).
156
157### Database Is Slow
158
159Connect to PostgreSQL and check for long-running queries:
160
161```bash
162docker compose exec postgres psql -U barazo -c "SELECT pid, now() - query_start AS duration, query FROM pg_stat_activity WHERE state = 'active' ORDER BY duration DESC LIMIT 5;"
163```