Quick start

This is the shortest supported path to a public Bearicorn hub: one Linux server, Docker Compose, PostgreSQL, and Caddy for automatic HTTPS.

If you already operate a reverse proxy, use the Direct HTTP stack instead. Read the full requirements before installing a long-lived or business-critical hub.

Requirements

• a Linux server you can reach with SSH;
• Docker Engine with the Compose plugin;
• a domain name with an A record pointing to the server; and
• inbound TCP ports 80 and 443 open to the internet.

For a starting size, use 2 vCPUs, 4 GB of RAM, and 30 GB of persistent disk. This is an operator recommendation, not a measured minimum; monitor the host and increase it for larger hubs.

Set up the server

Step 1 - Install Docker

Use the guide for your server:

• Debian or Ubuntu — recommended
• Fedora
• Alpine Linux — distribution packages

Cloud providers need a VM, static IP, and firewall rules first: AWS, Google Cloud, or DigitalOcean.

Step 2 - Download Bearicorn

sudo mkdir -p /opt/bearicorn
sudo chown "$USER":"$USER" /opt/bearicorn
cd /opt/bearicorn
git clone https://github.com/bybearicorn/monorepo.git
cd monorepo/deploy/compose

Step 3 - Configure the Caddy stack

cp .env.caddy .env
openssl rand -hex 32
openssl rand -hex 16

Edit .env and replace:

• JWT_SECRET with the first generated value;
• DB_PASSWORD with the second generated value; and
• CADDY_SITE_ADDRESS with your domain, such as chat.example.com.

Keep secrets out of source control

Do not use the placeholder values on a live server. Keep .env readable only by trusted administrators and do not commit it.

Step 4 - Start Bearicorn

docker compose --env-file .env -f docker-compose.caddy.yml up --build -d
docker compose --env-file .env -f docker-compose.caddy.yml ps

Open https://chat.example.com, using the exact host in CADDY_SITE_ADDRESS. The first account created in a fresh workspace becomes an administrator. Database migrations run when the application starts.

Verify the installation

All three services should be running and PostgreSQL should report healthy:

docker compose --env-file .env -f docker-compose.caddy.yml ps
docker compose --env-file .env -f docker-compose.caddy.yml logs --tail=100 caddy hub-app postgres

If HTTPS is not ready, confirm that DNS resolves to this server and ports 80 and 443 are reachable. Continue with troubleshooting if a container is restarting.

Protect the installation

Before inviting users:

1. create and test a PostgreSQL backup;
2. record the deployed Git revision and protect the .env file; and
3. review the security model.