Getting Started

Three steps to a running server. You need Docker Compose and nothing else — the container builds Floodgate from the source you just cloned, so no Gleam or Erlang toolchain is required. To build without Docker instead, skip to build from source.

1. get the source

git clone https://github.com/tylerbutler/floodgate && cd floodgate

2. start the server

docker compose up -d --wait

The first run builds the image, so it takes a few minutes; --wait holds until the container reports healthy. Later runs start in seconds.

3. confirm it answers

curl localhost:3000/health

{"status":"ok"}

That is Floodgate serving both wire protocols from one process: /socket.io/ for the official Fluid drivers, and /socket/websocket for Phoenix Channels clients. Point a Fluid Framework app at http://localhost:3000 and it will connect.

what the Compose file assumes

The bundled docker-compose.yml is a development configuration: it ships known secrets (FLOODGATE_JWT_SECRET=dev-tenant-secret-key, a token-mint secret, and an admin key), and it sets FLOODGATE_ALLOWED_ORIGINS=* so browser clients on any origin can connect. Replace all of them before this faces anything real — every value is listed in Configuration.

operating it

docker compose logs -f floodgate

follow the server log

docker compose down -v

[destructive] Removes the storage volume. Every document, git object, and persisted tenant on this server is deleted. Omit -v to stop the container and keep the data.

build from source

Needs Gleam 1.13 or newer and Erlang/OTP. The repository pins both in mise.toml, so mise install will fetch the versions Floodgate is built against.

FLOODGATE_JWT_SECRET=dev-secret gleam run

Floodgate refuses to start without an explicit JWT secret — there is no default that would quietly leave a deployment unauthenticated. That secret also seeds the startup tenant (FLOODGATE_TENANT_ID, default fluid) with its first secret slot; see Multi-tenancy for what that tenant can do beyond boot.

next

The listen address, storage backend, connection limits, and every other knob live in Configuration. If something didn't start, docker compose logs -f floodgate prints the reason — a missing JWT secret and a port already in use are the two common ones. Anything else is worth an issue.