gui.do
Barazo Docker Compose templates for self-hosting
barazo.forum
feat(dev): add dev Docker Compose with PostgreSQL, Valkey, and Tap (#3)
Formalizes the development infrastructure setup that was previously
at the workspace root. Includes .env.example with documented variables
and updated README with quick start guide, common commands, and
troubleshooting.
authored by
Guido X Jansen
and committed by
GitHub
c1e15d57
a2a743ca
+320
-105
+143
.env.example
+143
.env.example
···
1
+
# Barazo Environment Configuration
2
+
#
3
+
# Copy this file to .env (production) or .env.dev (development) and edit values.
4
+
# Lines starting with # are comments. Uncomment to override defaults.
5
+
#
6
+
# SECURITY: Never commit .env files containing real secrets.
7
+
8
+
# ==============================================================================
9
+
# Community Identity
10
+
# ==============================================================================
11
+
12
+
# Display name for your forum community
13
+
COMMUNITY_NAME="My Community"
14
+
15
+
# Domain where your forum is hosted (used by Caddy for SSL)
16
+
# COMMUNITY_DOMAIN="forum.example.com"
17
+
18
+
# AT Protocol DID for your community (created during setup)
19
+
# COMMUNITY_DID="did:plc:xxxx"
20
+
21
+
# Deployment mode: "single" for one community, "global" for aggregator
22
+
COMMUNITY_MODE="single"
23
+
24
+
# ==============================================================================
25
+
# Database (PostgreSQL 16 + pgvector)
26
+
# ==============================================================================
27
+
28
+
# PostgreSQL superuser credentials (used to create the database)
29
+
POSTGRES_USER="barazo"
30
+
POSTGRES_PASSWORD="CHANGE_ME"
31
+
POSTGRES_DB="barazo"
32
+
33
+
# Host port mapping (change if 5432 is already in use)
34
+
# POSTGRES_PORT="5432"
35
+
36
+
# Application database URL (used by barazo-api)
37
+
# Uses the application role with INSERT/UPDATE/DELETE/SELECT privileges
38
+
DATABASE_URL="postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}"
39
+
40
+
# Migration database URL (used only by migration scripts)
41
+
# Uses a migration role with DDL privileges
42
+
# MIGRATION_DATABASE_URL="postgresql://barazo_migrator:CHANGE_ME@postgres:5432/${POSTGRES_DB}"
43
+
44
+
# ==============================================================================
45
+
# Cache (Valkey -- Redis-compatible)
46
+
# ==============================================================================
47
+
48
+
# Valkey password (optional in dev, required in production)
49
+
# VALKEY_PASSWORD="CHANGE_ME"
50
+
51
+
# Host port mapping (change if 6379 is already in use)
52
+
# VALKEY_PORT="6379"
53
+
54
+
# Cache URL (used by barazo-api)
55
+
VALKEY_URL="redis://valkey:6379"
56
+
57
+
# ==============================================================================
58
+
# AT Protocol (Firehose via Tap)
59
+
# ==============================================================================
60
+
61
+
# Relay URL for the AT Protocol firehose
62
+
TAP_RELAY_URL="https://bsky.network"
63
+
64
+
# Host port mapping for Tap admin API (change if 2480 is already in use)
65
+
# TAP_PORT="2480"
66
+
67
+
# Tap admin password (for dev/debug access to Tap admin API)
68
+
TAP_ADMIN_PASSWORD="tap_dev_secret"
69
+
70
+
# ==============================================================================
71
+
# AT Protocol (OAuth)
72
+
# ==============================================================================
73
+
74
+
# OAuth client ID (your forum's public URL)
75
+
# OAUTH_CLIENT_ID="https://forum.example.com"
76
+
77
+
# OAuth callback URL
78
+
# OAUTH_REDIRECT_URI="https://forum.example.com/api/auth/callback"
79
+
80
+
# ==============================================================================
81
+
# Frontend (Next.js)
82
+
# ==============================================================================
83
+
84
+
# Public API URL (as seen by the browser)
85
+
# NEXT_PUBLIC_API_URL="https://forum.example.com/api"
86
+
87
+
# Public site URL
88
+
# NEXT_PUBLIC_SITE_URL="https://forum.example.com"
89
+
90
+
# ==============================================================================
91
+
# Search (Optional Semantic Search)
92
+
# ==============================================================================
93
+
94
+
# When set, enables hybrid semantic search alongside full-text search.
95
+
# Example: "http://ollama:11434/api/embeddings" for local Ollama
96
+
# EMBEDDING_URL=""
97
+
98
+
# Embedding vector dimensions (must match your model; default matches nomic-embed-text)
99
+
# AI_EMBEDDING_DIMENSIONS="768"
100
+
101
+
# ==============================================================================
102
+
# Encryption
103
+
# ==============================================================================
104
+
105
+
# AES-256-GCM master key for encrypting BYOK API keys at rest.
106
+
# Required if users will store their own AI provider keys.
107
+
# Generate with: openssl rand -base64 32
108
+
# AI_ENCRYPTION_KEY=""
109
+
110
+
# ==============================================================================
111
+
# Cross-Posting
112
+
# ==============================================================================
113
+
114
+
# Enable Frontpage cross-posting (Bluesky cross-posting is always available)
115
+
# FEATURE_CROSSPOST_FRONTPAGE="false"
116
+
117
+
# ==============================================================================
118
+
# Plugins
119
+
# ==============================================================================
120
+
121
+
# Set to "false" to disable all plugins
122
+
# PLUGINS_ENABLED="true"
123
+
124
+
# npm registry URL for plugin installation (default: public npm registry)
125
+
# PLUGIN_REGISTRY_URL="https://registry.npmjs.org"
126
+
127
+
# ==============================================================================
128
+
# Monitoring
129
+
# ==============================================================================
130
+
131
+
# GlitchTip/Sentry DSN for error reporting (optional)
132
+
# GLITCHTIP_DSN=""
133
+
134
+
# Log level: trace, debug, info, warn, error, fatal
135
+
LOG_LEVEL="info"
136
+
137
+
# ==============================================================================
138
+
# Backups (Production only)
139
+
# ==============================================================================
140
+
141
+
# Public key for encrypting backups with age (recommended over GPG)
142
+
# Generate a keypair with: age-keygen -o key.txt
143
+
# BACKUP_PUBLIC_KEY=""
+119
-105
README.md
+119
-105
README.md
···
8
8
9
9
# barazo-deploy
10
10
11
-
**Docker Compose templates for self-hosting Barazo**
11
+
**Docker Compose templates for deploying Barazo**
12
12
13
13
[](https://opensource.org/licenses/MIT)
14
14
···
16
16
17
17
---
18
18
19
-
## 🚧 Status: Pre-Alpha Development
20
-
21
-
Self-hosting deployment templates for Barazo forums.
22
-
23
-
**Current phase:** Planning complete, templates coming Q2 2026
24
-
25
-
---
26
-
27
19
## What is this?
28
20
29
-
The barazo-deploy repo provides everything you need to self-host a Barazo forum:
21
+
Docker Compose configurations and documentation for running Barazo -- a federated forum on the AT Protocol.
30
22
31
-
- **Docker Compose files** - Single-forum, global aggregator, staging configs
32
-
- **Environment templates** - `.env.example` with all variables documented
33
-
- **Setup scripts** - Database initialization, backups, migrations
34
-
- **Documentation** - Installation guide, upgrade guide, troubleshooting
23
+
**Available profiles:**
35
24
36
-
**Goal:** `docker compose up` gets a working forum in 5 minutes.
25
+
| Profile | Use Case | File | Status |
26
+
|---------|----------|------|--------|
27
+
| **Development** | Local dev (infrastructure only) | `docker-compose.dev.yml` | Available |
28
+
| **Single Forum** | One community, production | `docker-compose.yml` | Planned |
29
+
| **Global Aggregator** | Cross-community aggregator | `docker-compose.global.yml` | Planned |
37
30
38
31
---
39
32
40
-
## Deployment Profiles
33
+
## Development Setup
41
34
42
-
| Profile | Use Case | File |
43
-
|---------|----------|------|
44
-
| **Single Forum** | One community forum | `docker-compose.yml` |
45
-
| **Global Aggregator** | Cross-forum feed (barazo.forum) | `docker-compose.global.yml` |
46
-
| **Development** | Local development (DB only) | `docker-compose.dev.yml` |
47
-
| **Staging** | Integration testing | `docker-compose.staging.yml` |
35
+
The dev compose provides infrastructure services for local development of `barazo-api` and `barazo-web`. It does **not** include the API or web containers -- run those separately with `pnpm dev:api` / `pnpm dev:web`.
48
36
49
-
---
37
+
### Prerequisites
50
38
51
-
## Quick Start
39
+
- [Docker](https://docs.docker.com/get-docker/) (v24+) with Docker Compose v2
40
+
- [Node.js](https://nodejs.org/) 24 LTS and [pnpm](https://pnpm.io/) (for running API/web locally)
52
41
53
-
**Prerequisites:**
54
-
- Docker + Docker Compose
55
-
- Domain pointing to your server
56
-
- 4 GB RAM minimum
42
+
### Services
57
43
58
-
**Deploy:**
44
+
| Service | Image | Port | Purpose |
45
+
|---------|-------|------|---------|
46
+
| **postgres** | `pgvector/pgvector:pg16` | 5432 | PostgreSQL 16 with pgvector for full-text and semantic search |
47
+
| **valkey** | `valkey/valkey:8-alpine` | 6379 | Redis-compatible cache for sessions, rate limiting, queues |
48
+
| **tap** | `ghcr.io/bluesky-social/indigo/tap:latest` | 2480 | AT Protocol firehose consumer (filters `forum.barazo.*` records) |
49
+
50
+
### Quick Start
51
+
59
52
```bash
60
-
git clone https://github.com/barazo-forum/barazo-deploy.git
53
+
# Clone the deploy repo (or use from monorepo workspace)
61
54
cd barazo-deploy
62
55
63
-
# Configure
64
-
cp .env.example .env
65
-
nano .env # Edit forum name, domain, etc.
56
+
# Copy environment template
57
+
cp .env.example .env.dev
66
58
67
-
# Start
68
-
docker compose up -d
59
+
# Start infrastructure
60
+
docker compose -f docker-compose.dev.yml up -d
69
61
70
-
# Verify
71
-
docker compose logs -f
62
+
# Verify all services are healthy
63
+
docker compose -f docker-compose.dev.yml ps
72
64
```
73
65
74
-
Your forum will be available at `https://your-domain.com`
66
+
All three services should show `healthy` status within 30 seconds.
75
67
76
-
SSL certificates are automatic via Caddy.
68
+
### From the Monorepo Workspace
77
69
78
-
---
70
+
If using the pnpm workspace at `~/Documents/Git/barazo-forum/`:
79
71
80
-
## What's Included
72
+
```bash
73
+
# Start infrastructure (references barazo-deploy/docker-compose.dev.yml)
74
+
pnpm dev:infra
81
75
82
-
**Services:**
83
-
- `barazo-api` - Backend AppView
84
-
- `barazo-web` - Frontend
85
-
- `postgres` - PostgreSQL 16 + pgvector
86
-
- `valkey` - Cache
87
-
- `caddy` - Reverse proxy + automatic SSL
76
+
# Stop infrastructure
77
+
pnpm dev:infra:down
88
78
89
-
**Volumes (persistent data):**
90
-
- PostgreSQL data
91
-
- Caddy SSL certificates
92
-
- Valkey cache (optional persistence)
79
+
# View logs
80
+
pnpm dev:infra:logs
81
+
```
93
82
94
-
**Networking:**
95
-
- Only Caddy exposed externally (ports 80, 443)
96
-
- Internal network for all other services
83
+
### Common Commands
97
84
98
-
---
85
+
```bash
86
+
# Start all services
87
+
docker compose -f docker-compose.dev.yml up -d
99
88
100
-
## Minimum Requirements
89
+
# Stop all services (preserves data)
90
+
docker compose -f docker-compose.dev.yml down
101
91
102
-
| Deployment | CPU | RAM | Storage | Bandwidth |
103
-
|------------|-----|-----|---------|-----------|
104
-
| **Single Forum** | 2 vCPU | 4 GB | 20 GB SSD | 1 TB/month |
105
-
| **Global Aggregator** | 4 vCPU | 8 GB | 100 GB SSD | 5 TB/month |
92
+
# Stop and remove all data volumes
93
+
docker compose -f docker-compose.dev.yml down -v
106
94
107
-
**Recommended VPS:** Hetzner CX22 (€5.83/month) or higher
95
+
# View logs (all services)
96
+
docker compose -f docker-compose.dev.yml logs -f
108
97
109
-
---
98
+
# View logs (single service)
99
+
docker compose -f docker-compose.dev.yml logs -f postgres
110
100
111
-
## Upgrading
101
+
# Restart a single service
102
+
docker compose -f docker-compose.dev.yml restart valkey
112
103
113
-
```bash
114
-
# Pull latest images
115
-
docker compose pull
104
+
# Connect to PostgreSQL
105
+
docker compose -f docker-compose.dev.yml exec postgres psql -U barazo
106
+
```
116
107
117
-
# Restart with new versions
118
-
docker compose up -d
108
+
### Environment Variables
119
109
120
-
# Verify
121
-
docker compose ps
122
-
```
110
+
All variables have sensible defaults for development. Override them in `.env.dev`:
123
111
124
-
Database migrations run automatically on API startup.
112
+
| Variable | Default | Description |
113
+
|----------|---------|-------------|
114
+
| `POSTGRES_USER` | `barazo` | PostgreSQL superuser name |
115
+
| `POSTGRES_PASSWORD` | `barazo_dev` | PostgreSQL superuser password |
116
+
| `POSTGRES_DB` | `barazo` | Database name |
117
+
| `POSTGRES_PORT` | `5432` | Host port for PostgreSQL |
118
+
| `VALKEY_PORT` | `6379` | Host port for Valkey |
119
+
| `TAP_RELAY_URL` | `https://bsky.network` | AT Protocol relay URL |
120
+
| `TAP_PORT` | `2480` | Host port for Tap admin API |
121
+
| `TAP_ADMIN_PASSWORD` | `tap_dev_secret` | Tap admin API password |
125
122
126
-
---
123
+
See [`.env.example`](.env.example) for the full list including production variables.
127
124
128
-
## Backups
125
+
### Troubleshooting
129
126
130
-
**Automated daily backups:**
127
+
**Port already in use:**
128
+
129
+
If port 5432, 6379, or 2480 is occupied, change the host port mapping in `.env.dev`:
130
+
131
131
```bash
132
-
# Included in deployment
133
-
./scripts/backup.sh
132
+
POSTGRES_PORT=5433
133
+
VALKEY_PORT=6380
134
+
TAP_PORT=2481
134
135
```
135
136
136
-
Backs up PostgreSQL to `backups/` directory. Configure cron:
137
+
**PostgreSQL won't start:**
138
+
139
+
Check if an existing volume has incompatible data:
140
+
137
141
```bash
138
-
0 2 * * * /path/to/barazo-deploy/scripts/backup.sh
142
+
docker compose -f docker-compose.dev.yml down -v
143
+
docker compose -f docker-compose.dev.yml up -d
139
144
```
140
145
141
-
---
146
+
Warning: `-v` deletes all data. Back up first if needed.
142
147
143
-
## Documentation
148
+
**Tap fails on Apple Silicon:**
144
149
145
-
- **Installation Guide:** [docs/installation.md](docs/installation.md)
146
-
- **Configuration Reference:** [docs/configuration.md](docs/configuration.md)
147
-
- **Upgrade Guide:** [docs/upgrading.md](docs/upgrading.md)
148
-
- **Troubleshooting:** [docs/troubleshooting.md](docs/troubleshooting.md)
149
-
- **Backups:** [docs/backups.md](docs/backups.md)
150
+
Tap uses `platform: linux/amd64`. Docker Desktop on Apple Silicon runs it via Rosetta emulation. If it crashes:
150
151
151
-
---
152
+
1. Verify Docker Desktop has Rosetta enabled (Settings > General > "Use Rosetta")
153
+
2. Restart Docker Desktop
154
+
3. Try again: `docker compose -f docker-compose.dev.yml up -d tap`
152
155
153
-
## Managed Hosting Alternative
156
+
**Containers start but API can't connect:**
154
157
155
-
Don't want to self-host? Managed hosting available (Phase 3):
158
+
Verify the services are healthy:
156
159
157
-
- Automatic updates
158
-
- Backups included
159
-
- Custom domain support
160
-
- EU hosting (GDPR-compliant)
160
+
```bash
161
+
docker compose -f docker-compose.dev.yml ps
162
+
```
161
163
162
-
See [barazo.forum/pricing](https://barazo.forum/pricing) (coming soon)
164
+
If a service shows `starting` or `unhealthy`, check its logs:
165
+
166
+
```bash
167
+
docker compose -f docker-compose.dev.yml logs postgres
168
+
```
163
169
164
170
---
165
171
166
-
## License
172
+
## Production Deployment
167
173
168
-
**MIT** - Self-hosting templates should be freely usable.
174
+
Production Docker Compose with Caddy SSL, two-network segmentation, and health checks will be added in a future release.
175
+
176
+
### Minimum Requirements
177
+
178
+
| Deployment | CPU | RAM | Storage | Bandwidth |
179
+
|------------|-----|-----|---------|-----------|
180
+
| **Single Forum** | 2 vCPU | 4 GB | 20 GB SSD | 1 TB/month |
181
+
| **Global Aggregator** | 4 vCPU | 8 GB | 100 GB SSD | 5 TB/month |
182
+
183
+
**Recommended VPS:** Hetzner CX22 or higher.
169
184
170
185
---
171
186
172
-
## Related Repositories
187
+
## License
173
188
174
-
- **[barazo-api](https://github.com/barazo-forum/barazo-api)** - Backend (AGPL-3.0)
175
-
- **[barazo-web](https://github.com/barazo-forum/barazo-web)** - Frontend (MIT)
176
-
- **[Organization](https://github.com/barazo-forum)** - All repos
189
+
**MIT** -- Self-hosting templates should be freely usable.
177
190
178
191
---
179
192
180
-
## Community
193
+
## Related Repositories
181
194
182
-
- 🌐 **Website:** [barazo.forum](https://barazo.forum) (coming soon)
183
-
- 💬 **Discussions:** [GitHub Discussions](https://github.com/orgs/barazo-forum/discussions)
184
-
- 🐛 **Issues:** [Report bugs](https://github.com/barazo-forum/barazo-deploy/issues)
195
+
- **[barazo-api](https://github.com/barazo-forum/barazo-api)** -- Backend (AGPL-3.0)
196
+
- **[barazo-web](https://github.com/barazo-forum/barazo-web)** -- Frontend (MIT)
197
+
- **[barazo-lexicons](https://github.com/barazo-forum/barazo-lexicons)** -- AT Protocol lexicon schemas (MIT)
198
+
- **[Organization](https://github.com/barazo-forum)** -- All repos
185
199
186
200
---
187
201
188
-
© 2026 Barazo. Licensed under MIT.
202
+
(c) 2026 Barazo. Licensed under MIT.
+58
docker-compose.dev.yml
+58
docker-compose.dev.yml
···
1
+
# Barazo Development Docker Compose
2
+
#
3
+
# Infrastructure services for local development of barazo-api and barazo-web.
4
+
# Does NOT include the API or web containers (run those with pnpm dev:api / dev:web).
5
+
#
6
+
# Usage:
7
+
# cp .env.example .env.dev
8
+
# docker compose -f docker-compose.dev.yml up -d
9
+
#
10
+
# Services: PostgreSQL 16 (pgvector), Valkey 8, Tap (AT Protocol firehose)
11
+
12
+
services:
13
+
postgres:
14
+
image: pgvector/pgvector:pg16
15
+
ports:
16
+
- "${POSTGRES_PORT:-5432}:5432"
17
+
environment:
18
+
POSTGRES_USER: ${POSTGRES_USER:-barazo}
19
+
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-barazo_dev}
20
+
POSTGRES_DB: ${POSTGRES_DB:-barazo}
21
+
volumes:
22
+
- pgdata:/var/lib/postgresql/data
23
+
healthcheck:
24
+
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-barazo}"]
25
+
interval: 10s
26
+
timeout: 5s
27
+
retries: 5
28
+
29
+
valkey:
30
+
image: valkey/valkey:8-alpine
31
+
ports:
32
+
- "${VALKEY_PORT:-6379}:6379"
33
+
volumes:
34
+
- valkeydata:/data
35
+
healthcheck:
36
+
test: ["CMD", "valkey-cli", "ping"]
37
+
interval: 10s
38
+
timeout: 5s
39
+
retries: 3
40
+
41
+
tap:
42
+
image: ghcr.io/bluesky-social/indigo/tap:latest
43
+
platform: linux/amd64
44
+
ports:
45
+
- "${TAP_PORT:-2480}:2480"
46
+
environment:
47
+
TAP_RELAY_URL: ${TAP_RELAY_URL:-https://bsky.network}
48
+
TAP_SIGNAL_COLLECTION: forum.barazo.topic.post
49
+
TAP_COLLECTION_FILTERS: forum.barazo.topic.post,forum.barazo.topic.reply,forum.barazo.interaction.reaction
50
+
TAP_DATABASE_URL: sqlite:///data/tap.db
51
+
TAP_ADMIN_PASSWORD: ${TAP_ADMIN_PASSWORD:-tap_dev_secret}
52
+
volumes:
53
+
- tapdata:/data
54
+
55
+
volumes:
56
+
pgdata:
57
+
valkeydata:
58
+
tapdata: