gui.do
Barazo Docker Compose templates for self-hosting
barazo.forum
1# Upgrade Guide
2
3How to upgrade your Barazo installation to a new version.
4
5## Standard Upgrade
6
7```bash
8cd barazo-deploy
9
10# Pull new images
11docker compose pull
12
13# Restart with new versions
14docker compose up -d
15
16# Verify
17docker compose ps
18./scripts/smoke-test.sh https://your-domain.com
19```
20
21Database migrations are applied automatically when the API container starts. The Drizzle migration runner checks for pending migrations and applies them before accepting requests. No manual schema step is needed.
22
23**Important:** Database migrations are forward-only. If you need to rollback, restore from the pre-upgrade backup.
24
25## Pinned Version Upgrade
26
27If you pin image versions in `.env` (recommended for production):
28
29```bash
30# Edit .env to update versions
31nano .env
32# Change BARAZO_API_VERSION=1.2.3 to BARAZO_API_VERSION=1.3.0
33# Change BARAZO_WEB_VERSION=1.2.3 to BARAZO_WEB_VERSION=1.3.0
34
35# Pull and restart
36docker compose pull
37docker compose up -d
38```
39
40## Pre-Upgrade Checklist
41
421. **Read the changelog** for the new version -- check for breaking changes
432. **Create a backup** before upgrading:
44 ```bash
45 ./scripts/backup.sh
46 ```
473. **Test on staging first** if you have a staging environment
48
49## Rollback
50
51If the upgrade causes issues:
52
53```bash
54# Stop services
55docker compose down
56
57# Edit .env to revert to previous version
58nano .env
59# Change versions back to previous values
60
61# Pull previous images
62docker compose pull
63
64# Restore database from pre-upgrade backup
65./scripts/restore.sh backups/barazo-backup-YYYYMMDD-HHMMSS.sql.gz
66
67# Start services
68docker compose up -d
69
70# Verify
71docker compose ps
72```
73
74## Breaking Changes
75
76Major version bumps (e.g., 1.x to 2.x) may include breaking changes that require manual steps. These are documented in the release notes and CHANGELOG.md.
77
78Common breaking changes to watch for:
79- **Environment variable renames** -- update your `.env` file
80- **Database schema changes** -- migrations run automatically on startup, but rollback requires restoring from the pre-upgrade backup
81- **Caddy configuration changes** -- check if Caddyfile needs updates