gui.do
Barazo Docker Compose templates for self-hosting
barazo.forum
1# Installation Guide
2
3Step-by-step guide to deploying a Barazo forum on your own server.
4
5## Prerequisites
6
7- **VPS or dedicated server** with a public IP address
8 - Minimum: 2 vCPU, 4 GB RAM, 20 GB SSD (Hetzner CX22 recommended)
9 - Linux (Ubuntu 22.04+ or Debian 12+ recommended)
10- **Domain name** with a DNS A record pointing to your server's IP
11- **Docker** v24+ and **Docker Compose** v2
12- **SSH access** to your server
13
14## 1. Install Docker
15
16If Docker is not already installed:
17
18```bash
19# Install Docker (official script)
20curl -fsSL https://get.docker.com | sh
21
22# Add your user to the docker group (avoids sudo for docker commands)
23sudo usermod -aG docker $USER
24
25# Log out and back in for group change to take effect
26exit
27# SSH back in
28
29# Verify
30docker --version
31docker compose version
32```
33
34## 2. Clone the Repository
35
36```bash
37git clone https://github.com/singi-labs/barazo-deploy.git
38cd barazo-deploy
39```
40
41## 3. Configure Environment
42
43```bash
44cp .env.example .env
45nano .env # or your preferred editor
46```
47
48**Required variables to set:**
49
50| Variable | What to set |
51|----------|-------------|
52| `COMMUNITY_NAME` | Your forum's display name |
53| `COMMUNITY_DOMAIN` | Your domain (e.g., `forum.example.com`) |
54| `POSTGRES_PASSWORD` | Strong random password |
55| `VALKEY_PASSWORD` | Strong random password |
56| `TAP_ADMIN_PASSWORD` | Strong random password |
57| `DATABASE_URL` | Update the password to match `POSTGRES_PASSWORD` |
58| `OAUTH_CLIENT_ID` | `https://your-domain.com` |
59| `OAUTH_REDIRECT_URI` | `https://your-domain.com/api/auth/callback` |
60| `NEXT_PUBLIC_SITE_URL` | `https://your-domain.com` |
61
62Generate passwords with:
63
64```bash
65openssl rand -base64 24
66```
67
68## 4. Start Services
69
70```bash
71docker compose up -d
72```
73
74This starts all 6 services: PostgreSQL, Valkey, Tap, API, Web, and Caddy.
75
76First startup may pull several Docker images (allow a few minutes on slower connections).
77
78## 5. Verify Installation
79
80```bash
81# Check all services are running
82docker compose ps
83
84# Run smoke test
85./scripts/smoke-test.sh https://your-domain.com
86```
87
88All services should show `healthy` status. Caddy automatically obtains an SSL certificate from Let's Encrypt on first request.
89
90Visit `https://your-domain.com` in your browser. You should see the Barazo forum.
91
92## 6. First-Time Setup
93
94The first user to complete the setup wizard becomes the community administrator. Open your forum URL and follow the on-screen instructions to:
95
961. Sign in with your AT Protocol account (Bluesky)
972. Set community name and description
983. Create initial categories
994. Configure moderation settings
100
101## Troubleshooting
102
103**Caddy fails to obtain SSL certificate:**
104
105- Verify your DNS A record points to the server's IP: `dig +short your-domain.com`
106- Ensure ports 80 and 443 are open in your firewall
107- Check Caddy logs: `docker compose logs caddy`
108
109**Services fail to start:**
110
111- Check logs: `docker compose logs`
112- Verify `.env` has no syntax errors
113- Ensure all required variables are set (no `CHANGE_ME` remaining)
114
115**Database connection errors:**
116
117- Verify `DATABASE_URL` password matches `POSTGRES_PASSWORD`
118- Check PostgreSQL logs: `docker compose logs postgres`
119
120See also: [Troubleshooting](administration.md#troubleshooting) in the Administration Guide.
121
122## Staging Environment
123
124The staging environment runs at `staging.barazo.forum` and is used for integration testing, OAuth validation, and firehose testing before production deploys. It uses `:latest` Docker images that auto-update on new releases.
125
126### Setup
127
128```bash
129# Clone the repo on your staging VPS
130git clone https://github.com/singi-labs/barazo-deploy.git
131cd barazo-deploy
132
133# Copy the staging template and fill in secrets
134cp .env.staging .env
135nano .env # Replace all CHANGE_ME values with real secrets
136```
137
138Generate secrets:
139
140```bash
141openssl rand -base64 24 # For POSTGRES_PASSWORD, VALKEY_PASSWORD, TAP_ADMIN_PASSWORD
142openssl rand -base64 32 # For SESSION_SECRET
143```
144
145### Start Staging
146
147```bash
148docker compose -f docker-compose.yml -f docker-compose.staging.yml up -d
149```
150
151The staging overlay applies:
152- `:latest` image tags (auto-updates on new releases)
153- `NODE_ENV=staging` and `LOG_LEVEL=debug`
154- Relaxed rate limits for testing
155
156### Seed Test Data
157
158After the first deployment (or after a reset), populate the database with test data:
159
160```bash
161./scripts/seed-staging.sh
162```
163
164This creates 5 categories, 5 test users, 10 topics, and 18 replies. Use `--minimal` to seed only categories.
165
166### Reset Staging
167
168To wipe all staging data and start fresh:
169
170```bash
171./scripts/reset-staging.sh
172```
173
174This drops and recreates the database, flushes the cache, and restarts all services. The schema is applied automatically on startup. Run `seed-staging.sh` afterward to repopulate test data.
175
176### Smoke Test
177
178```bash
179./scripts/smoke-test.sh https://staging.barazo.forum
180```
181
182### Staging vs. Production Differences
183
184| Setting | Staging | Production |
185|---------|---------|------------|
186| Image tags | `:latest` | Pinned versions (`:2.5.3`) |
187| `NODE_ENV` | `staging` | `production` |
188| `LOG_LEVEL` | `debug` | `info` |
189| Rate limits | Relaxed (1000 req/min) | Standard |
190| Database | `barazo_staging` | `barazo` |
191| SSL | Automatic (Let's Encrypt staging) | Automatic (Let's Encrypt) |