Skip to main content

Self-Hosting Guide

Complete guide to self-hosting Bellamy Book on your own server using the self-host kit (the standard dockerPublish folder): Docker Compose, pre-built images, and one .env file. No application source code required. The installation guides below are the canonical instructions for downloading the kit and self-hosting.

If you are evaluating BellamyBook as a self-hosted social network or planning to build your own platform for a community, start with that overview—then return here for deployment steps.

Can I self-host from this kit alone?​

Yes. Get the kit by cloning the project repository and using the dockerPublish folder (or a release package that includes it). If you have that folder (with docker-compose.yml, .env.example, and config directories), you can:

  1. Copy .env.example to .env and set your domain, secrets, and passwords.
  2. Create the MongoDB keyfile (one command).
  3. Run docker compose pull && docker compose up -d.

The docs and the kit are enough to go from zero to a running instance. Optional services (mail, CAPTCHA, Google Login, video calls) have step-by-step “how to get credentials” in their config pages.

Official repository​

Start from the official repository: BellamyBook on GitHub. Clone the project, copy .env.example to .env, update your values, then run with Docker Compose per the installation guides.

Overview​

Self-hosting gives you:

  • Full control over your data
  • Your own domain and branding
  • Storage (required): MinIO is the default for self-host. You must configure MinIO credentials (MINIO_ROOT_USER, MINIO_ROOT_PASSWORD) and Minio__PublicUrl in .env so the app can store and serve avatars, posts, and media. Alternatively use R2. Optional: SMTP, Turnstile, Google Login, LiveKit
  • One compose, one .env — no build step

Installation (this kit)​

GuideWhen to use it
Self-Host with Pre-Built ImagesYou have only the self-host kit — use this. No source code.
Test the stack on your MacRun the same stack locally (Mac or any machine) before deploying — no server or domain needed.
Make sure Traefik works when you deployChecklist so Traefik routes correctly on your server (hostnames, DNS, ports, HTTPS).
Docker Compose (full project)You have the full Bellamy Book source code and want to run the full stack from source.
Manual InstallationYou want to install without Docker.

Requirements​

For the full stack (API, frontend, admin, workers, databases):

  • CPU: 8+ cores
  • RAM: 16GB+
  • Storage: 200GB+ SSD
  • Software: Docker and Docker Compose

For local testing with fewer services, 3–5 cores and 6–10GB RAM can be enough.

Quick start (self-host kit)​

If you have only the self-host kit (the folder with docker-compose.yml):

  1. One env file: Copy .env.example to .env. Set DOCKER_REGISTRY, IMAGE_TAG, your domain URLs, and all passwords. Ignore .env.frontend.example and .env.admin.example — they are for image builders. See Three environment files.
  2. MongoDB keyfile: openssl rand -base64 756 > mongo-keyfile && chmod 600 mongo-keyfile (in the folder that contains docker-compose.yml).
  3. Run: docker compose pull && docker compose up -d. The database app runs automatically.
  4. Access: Your configured URLs, or without Traefik: Frontend http://localhost:8081, Admin http://localhost:8084, API http://localhost:5000.

Full step-by-step: Self-Host with Pre-Built Images.

Configuration​

After the stack is running, configure as needed:

WhatGuide
Environment variables (passwords, URLs)Environment
JWT (required for login)JWT Configuration
Database (PostgreSQL, MongoDB, Redis)Database
Storage (MinIO default — configure credentials and Minio__PublicUrl when self-hosting; or R2)Storage

Optional (with “how to get credentials” steps):

WhatGuide
Mail (password reset, notifications)SMTP (Mail Server)
CAPTCHA (login/register)Turnstile
Sign in with GoogleGoogle OAuth
Voice and video callsLiveKit
R2 (object storage)R2 Setup
MinIO securityStorage — MinIO bucket policies

Maintenance​

Support​

Next steps​