Self-hosting

Crewhall runs on one Linux server with Docker Compose. This page covers what you need, how to start the stack, the first-run setup wizard, optional services, and how to back up, restore and update. The examples use hub.example.com; replace it with your own domain.

Requirements​

• A Linux server with at least 2 vCPU, 4 GB RAM and enough disk for your files.
• Docker Engine 24 or later with Compose v2 (docker compose version).
• DNS A/AAAA records that point to the server:
  • hub.example.com for the app and the API.
  • s3.example.com for file uploads and downloads. Browsers connect to this address directly.
  • Optional: docs.example.com (portal site), lk.example.com (meetings) and office.example.com (Office documents).
• Ports 80 and 443 open to the internet.
• An SMTP account for outgoing email. It is optional but recommended.

The stack​

The stack is defined in docker/compose.yml. These services always run:

backend, worker and collab use the same image with different commands.

Prepare the environment file​

git clone https://github.com/Milvasoft/crewhall.git crewhall && cd crewhall
cp docker/.env.example docker/.env

Edit docker/.env. These values matter most:

If ports 80 and 443 are taken, or another reverse proxy sits in front, set HTTP_PORT and HTTPS_PORT, and set the public addresses HUB_URL, S3_PUBLIC_URL, COLLAB_PUBLIC_URL and PORTAL_PUBLIC_URL. Include the port when it is not 443, for example https://hub.example.com:8443.

Start the stack​

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

The first start builds the images, which takes a few minutes. The backend runs database migrations on start. The worker starts when the backend is healthy. If you use prebuilt images, set CREWHALL_REGISTRY and CREWHALL_VERSION and use pull instead of --build.

Check that it is ready:

curl -s https://hub.example.com/readyz

The response is {"status":"ready"}.

First-run setup wizard​

1. Get the setup token from the logs:

   docker compose -f docker/compose.yml --env-file docker/.env logs backend | grep -i "setup"
   
2. Open https://hub.example.com. The wizard asks for the setup token, then walks you through four steps: Organization (name, ID and default language), First admin (the owner account), Shared spaces and Invite the team. A system check shows whether the database, storage and email are connected.
3. The owner must turn on two-step verification (TOTP or a passkey) at first sign-in.

After setup the token no longer works. You can change the name, logo and colors later in Admin › Brand. See Administration.

DNS and TLS​

Caddy gets certificates from Let's Encrypt on its own. It needs the DNS records to point at the server and ports 80 and 443 to be reachable. If a certificate is not issued, check DNS and the firewall, then read docker compose ... logs caddy.

If you put another proxy in front of Caddy, it must pass /ws and /collab as WebSockets (forward the Upgrade header). Otherwise chat and co-editing do not update live.

Storage​

Files go to the bundled SeaweedFS by default. Uploads and downloads use presigned URLs, so the browser talks to S3_DOMAIN directly. Opening https://s3.example.com in a browser shows an XML error page; that is normal.

You can use any other S3-compatible service instead by changing the S3_* settings in the compose file. The bucket's CORS settings must allow your hub domain and expose the ETag header.

Email​

With SMTP_URL set, Crewhall sends invitations, password resets and notifications. Without it, invitations are shown as links that you send yourself, and password reset and notification emails do not go out. Admins can also set a separate SMTP server in Admin › Notification delivery and send a test email there.

Optional profiles​

Turn on extra services with --profile. Each one needs its own settings in docker/.env.

Meetings (meet)​

1. Set LK_DOMAIN, LIVEKIT_API_KEY, LIVEKIT_API_SECRET, TURN_USER and TURN_PASSWORD. Set MEET_EGRESS_ENABLED=true for recordings. Egress needs 2-4 GB of RAM.
2. Open 7881/tcp, 50000-60000/udp, 3478/udp and 3478/tcp, and 49160-49200/udp.
3. Start with --profile meet.

The LiveKit DNS record must point straight at the server. If you use a CDN proxy, turn the proxy off for that record, because media uses UDP. Without keys, meetings are unavailable and everything else works. See Meetings.

Portal site (portal)​

1. In Portal › Settings, create the read key under the Next.js connection.
2. Set PORTAL_DOMAIN, PORTAL_CONTENT_TOKEN (the read key) and PORTAL_REVALIDATE_SECRET.
3. Start with --profile portal. Published changes show on the site within seconds. See Portal.

Office documents (office)​

The document server is a separate, unmodified service under its own license (AGPLv3). Crewhall only talks to it over the network.

1. Set OFFICE_DOMAIN and OFFICE_JWT_SECRET (32 or more random characters).
2. Start with --profile office. It needs at least 4 GB of memory.
3. In Admin › Integrations › Office, enter the server address https://office.example.com, the internal address http://office and the same JWT secret. Select Test the connection, then turn on Office editing.

Speech recognition (ai)​

The ai profile runs a speech recognition server with an OpenAI-compatible API. In Admin › AI › Meeting notes, set the speech recognition server to http://whisper:8000/v1 and choose a model. The model downloads on first use.

Backups, restore and update​

The crewhall command in tools/crewhall backs up the database and files, restores them and updates the stack. Run it on the server from the repository root.

tools/crewhall/crewhall backup
tools/crewhall/crewhall list
tools/crewhall/crewhall restore <id>
tools/crewhall/crewhall export <id> > crewhall-backup.tar
tools/crewhall/crewhall import < crewhall-backup.tar
tools/crewhall/crewhall prune --keep 14

• Backups are stored in the backups Docker volume. Files are stored once by content, so each backup only adds what changed.
• Copy backups off the server regularly with export.
• restore stops the app services, replaces the database and files with the backup, and starts them again.
• docker/.env is not included by default. Add --with-config to include it encrypted; the passphrase is read from CREWHALL_BACKUP_PASSPHRASE.
• Restore with the same AUTH_SECRET as the installation the backup came from.
• Pass --profile meet or --profile portal if you use them.

You can also turn on a nightly backup in Admin › Backups.

To update:

tools/crewhall/crewhall update 1.5.0          # prebuilt images
git pull && tools/crewhall/crewhall update --build   # built from source

The command takes a backup first, then starts the new version. If the backend does not become healthy, it puts back the old images, the old .env and the backup.