Installation Guide#

Step-by-step guide to deploying a Barazo forum on your own server.

Prerequisites#

• VPS or dedicated server with a public IP address
  • Minimum: 2 vCPU, 4 GB RAM, 20 GB SSD (Hetzner CX22 recommended)
  • Linux (Ubuntu 22.04+ or Debian 12+ recommended)
• Domain name with a DNS A record pointing to your server's IP
• Docker v24+ and Docker Compose v2
• SSH access to your server

1. Install Docker#

If Docker is not already installed:

# Install Docker (official script)
curl -fsSL https://get.docker.com | sh

# Add your user to the docker group (avoids sudo for docker commands)
sudo usermod -aG docker $USER

# Log out and back in for group change to take effect
exit
# SSH back in

# Verify
docker --version
docker compose version

2. Clone the Repository#

git clone https://github.com/singi-labs/barazo-deploy.git
cd barazo-deploy

3. Configure Environment#

cp .env.example .env
nano .env  # or your preferred editor

Required variables to set:

Generate passwords with:

openssl rand -base64 24

4. Start Services#

docker compose up -d

This starts all 6 services: PostgreSQL, Valkey, Tap, API, Web, and Caddy.

First startup may pull several Docker images (allow a few minutes on slower connections).

5. Verify Installation#

# Check all services are running
docker compose ps

# Run smoke test
./scripts/smoke-test.sh https://your-domain.com

All services should show healthy status. Caddy automatically obtains an SSL certificate from Let's Encrypt on first request.

Visit https://your-domain.com in your browser. You should see the Barazo forum.

6. First-Time Setup#

The first user to complete the setup wizard becomes the community administrator. Open your forum URL and follow the on-screen instructions to:

1. Sign in with your AT Protocol account (Bluesky)
2. Set community name and description
3. Create initial categories
4. Configure moderation settings

Troubleshooting#

Caddy fails to obtain SSL certificate:

• Verify your DNS A record points to the server's IP: dig +short your-domain.com
• Ensure ports 80 and 443 are open in your firewall
• Check Caddy logs: docker compose logs caddy

Services fail to start:

• Check logs: docker compose logs
• Verify .env has no syntax errors
• Ensure all required variables are set (no CHANGE_ME remaining)

Database connection errors:

• Verify DATABASE_URL password matches POSTGRES_PASSWORD
• Check PostgreSQL logs: docker compose logs postgres

See also: Troubleshooting in the Administration Guide.

Staging Environment#

The 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.

Setup#

# Clone the repo on your staging VPS
git clone https://github.com/singi-labs/barazo-deploy.git
cd barazo-deploy

# Copy the staging template and fill in secrets
cp .env.staging .env
nano .env  # Replace all CHANGE_ME values with real secrets

Generate secrets:

openssl rand -base64 24   # For POSTGRES_PASSWORD, VALKEY_PASSWORD, TAP_ADMIN_PASSWORD
openssl rand -base64 32   # For SESSION_SECRET

Start Staging#

docker compose -f docker-compose.yml -f docker-compose.staging.yml up -d

The staging overlay applies:

• :latest image tags (auto-updates on new releases)
• NODE_ENV=staging and LOG_LEVEL=debug
• Relaxed rate limits for testing

Seed Test Data#

After the first deployment (or after a reset), populate the database with test data:

./scripts/seed-staging.sh

This creates 5 categories, 5 test users, 10 topics, and 18 replies. Use --minimal to seed only categories.

Reset Staging#

To wipe all staging data and start fresh:

./scripts/reset-staging.sh

This 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.

Smoke Test#

./scripts/smoke-test.sh https://staging.barazo.forum

Staging vs. Production Differences#