Run a server

One Docker Compose file runs one community: the server, Postgres, a file scanner, and a tunnel that carries the web traffic.

The files are in deploy/ of the tinyserver repository. This page follows deploy/README.md, which stays the reference when the two differ.

What you need

What the compose file runs

ServiceWhat it doesReachable from
tinyserverThe HTTP API, the live socket, the sign-in pages and the call server (SFU)Port 8080 inside the network only. The media port is the one port published on the host.
tinyserver-initRuns before the server on every start: migrates the database and, while there is no owner, writes the owner invite. It is the only container with the database owner password.Nothing
postgresThe databaseThe internal network, which has no route to the internet
clamdScans uploads before anyone can fetch themThe server only. It has a route out for signature updates.
pocket-idAn OpenID Connect provider where people sign in with passkeys. Optional: the server also signs people in with its own passkeys.The tunnel, on a second hostname
tunnelcloudflared. Carries https and the live socket to the server, so no web port is opened on the host. Use your own proxy instead if you prefer.Makes an outbound connection to Cloudflare

The environment file

git clone https://github.com/TinyComms/tinyserver
cd tinyserver/deploy
cp .env.example .env

Compose refuses to start while one of these seven is empty. Keep .env and deploy/secrets to yourself; neither is committed.

VariableWhat it isMake it with
POSTGRES_PASSWORDThe Postgres superuser. Only the postgres container has it.openssl rand -hex 24
APP_OWNER_PASSWORDThe role that owns the schema and migrates itopenssl rand -hex 24
APP_RUNTIME_PASSWORDThe role the server runs as. Letters and digits only: it goes into a database URL.openssl rand -hex 24
TINYSERVER_MEDIA_HMAC_SECRETSigns attachment links. 64 hex characters.openssl rand -hex 32
TINYSERVER_PUBLIC_URLThe address people type into tinyclient, such as https://chat.example.org. A hostname, no path, no trailing slash.
AUTH_PUBLIC_URLPocket ID’s address and issuer, such as https://auth.example.org. Keep it set even after Pocket ID is retired: compose still reads it.
TUNNEL_TOKENThe Cloudflare tunnel’s token. With your own proxy, write unused.Cloudflare shows it when you create the tunnel

The optional settings are listed in Operate and upgrade. The .env.example at the top of the repository is for a local checkout, not for this stack.

Two hostnames

Add both as public hostnames on the tunnel in Cloudflare:

HostnameTunnel sends it toUsed for
TINYSERVER_PUBLIC_URLhttp://tinyserver:8080Chat, the live socket, and the server’s own passkey pages
AUTH_PUBLIC_URLhttp://pocket-id:1411Pocket ID’s pages. Not needed on a passkey-only server.

The issuer is AUTH_PUBLIC_URL exactly, with no trailing slash and no path, because that is what Pocket ID puts in its tokens.

Start it

sh pocket-id/setup.sh moss  # moss is the first Pocket ID admin's username
docker compose up -d

setup.sh writes three secrets to deploy/secrets, starts Pocket ID, registers the server as its OpenID Connect client, and prints a one-time login link for that admin, good for an hour. Run it again at any time; every step is skipped when already done.

To run the image CI published for a commit instead of building on the host, see Running a published image.

The first owner

There is no owner password. While the community has no owner, tinyserver-init writes a single-use owner invite, good for 24 hours, to a file. The log names the file and never holds the invite.

docker compose exec tinyserver cat /bootstrap/owner-invite

The file holds a https://tinyclient.io/invite#… link and a tc1. code. In tinyclient, choose Join a server, paste the code and sign in. Whoever does that is the owner. After an owner exists, the file is removed on the next start.

Lost it, or it expired? Make a new one. The old one stops working.

docker compose run --rm --entrypoint tinyserver tinyserver-init bootstrap --owner-invite

The first time the owner opens the server, tinyclient asks what the community keeps about its members. First-run setup describes the three choices.

Check it

Open /health on the chat hostname. Port 8080 is not published on the host, so go through the tunnel or your proxy.

FieldMeaning
oktrue when the schema is there and media is not down
schemaready or missing
mediaoff (no public address set), up, or down
transportsWhile media is up: udp and tcp, plus lan when a LAN address is set

Without Cloudflare

Nothing in tinyserver needs Cloudflare. It is a plain HTTP server on port 8080 inside its container. compose.proxy.yml turns cloudflared off and publishes port 8080 on the host’s loopback for your own proxy:

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

Put TUNNEL_TOKEN=unused in .env. Your front end must do three things:

  1. End TLS for the hostname in TINYSERVER_PUBLIC_URL. tinyserver does not do TLS itself, and browsers refuse passkeys on plain http.
  2. Pass WebSockets. The live socket is /v1/live. Leave idle connections open.
  3. Set one header to the client’s address, replacing whatever the client sent, and name it in TINYSERVER_CLIENT_IP_HEADER. It keys the sign-in rate limits. Without it every member shares the proxy’s one allowance. The server believes the header only from a proxy on a private or loopback address; list a proxy with a public address in TINYSERVER_TRUSTED_PROXIES.

Caddy on the host, which gets the certificate itself, with TINYSERVER_CLIENT_IP_HEADER=x-real-ip:

chat.example.org {
    reverse_proxy 127.0.0.1:8080 {
        header_up X-Real-IP {remote_host}
    }
}

nginx, in a server block that already ends TLS, with the same setting:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_read_timeout 3600s;
}

Another tunnel works the same way: it needs a hostname, TLS, WebSockets and a header with the client’s address. A proxy or tunnel carries the web pages and chat, not call audio; calls still need their own port.

Not tested by the project. These proxy settings were written from each proxy’s documentation and checked only as far as compose accepting the files and the server reading the header. Run a sign-in through yours, and look for “rate limited” in the server log under normal use, before relying on it.

On your own machine

A checkout runs the server against a local Postgres, for development or a server only you use. Rust is the stable toolchain.

cp .env.example .env
docker compose up -d --wait  # Postgres 17 on 127.0.0.1:54329, nothing else
cargo run -p tinyserver -- migrate
cargo run -p tinyserver -- bootstrap
cargo run -p tinyserver -- serve

Edit this page on GitHub