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
- A Linux host with Docker and Docker Compose. The passkey-only file needs Compose 2.24.4 or later.
- A hostname you control, such as
chat.example.org, served over https. Passkeys are bound to that hostname, so it cannot be an IP address and should not change later. - For calls: one port, UDP and TCP, that members can reach directly on a public IPv4 address. Without it the server runs and calls have no audio or video. Calls and media has the steps.
- Memory for the default caps: 1 GiB for the server, 1 GiB for Postgres and 3 GiB for the scanner. They are caps, not reservations. Raise or lower them in the environment file.
What the compose file runs
| Service | What it does | Reachable from |
|---|---|---|
tinyserver | The 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-init | Runs 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 |
postgres | The database | The internal network, which has no route to the internet |
clamd | Scans uploads before anyone can fetch them | The server only. It has a route out for signature updates. |
pocket-id | An 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 |
tunnel | cloudflared. 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 .envCompose refuses to start while one of these seven is empty. Keep .env and deploy/secrets to yourself; neither is committed.
| Variable | What it is | Make it with |
|---|---|---|
POSTGRES_PASSWORD | The Postgres superuser. Only the postgres container has it. | openssl rand -hex 24 |
APP_OWNER_PASSWORD | The role that owns the schema and migrates it | openssl rand -hex 24 |
APP_RUNTIME_PASSWORD | The role the server runs as. Letters and digits only: it goes into a database URL. | openssl rand -hex 24 |
TINYSERVER_MEDIA_HMAC_SECRET | Signs attachment links. 64 hex characters. | openssl rand -hex 32 |
TINYSERVER_PUBLIC_URL | The address people type into tinyclient, such as https://chat.example.org. A hostname, no path, no trailing slash. | |
AUTH_PUBLIC_URL | Pocket 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_TOKEN | The 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:
| Hostname | Tunnel sends it to | Used for |
|---|---|---|
TINYSERVER_PUBLIC_URL | http://tinyserver:8080 | Chat, the live socket, and the server’s own passkey pages |
AUTH_PUBLIC_URL | http://pocket-id:1411 | Pocket 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 -dsetup.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-inviteThe 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-inviteThe 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.
| Field | Meaning |
|---|---|
ok | true when the schema is there and media is not down |
schema | ready or missing |
media | off (no public address set), up, or down |
transports | While 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 -dPut TUNNEL_TOKEN=unused in .env. Your front end must do three things:
- End TLS for the hostname in
TINYSERVER_PUBLIC_URL. tinyserver does not do TLS itself, and browsers refuse passkeys on plain http. - Pass WebSockets. The live socket is
/v1/live. Leave idle connections open. - 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 inTINYSERVER_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 -- serveservewill not start without a scanner: setTINYSERVER_CLAMD_SOCKETtohost:port, orTINYSERVER_ALLOW_FAKE_SCAN=1when no clamd is running.- Keep the example’s
TINYSERVER_PUBLIC_URL=http://localhost:8080. An IP address such as127.0.0.1stops the start, because passkeys are bound to a hostname. - Without the OIDC variables the server is passkeys only.
- It listens on
127.0.0.1:8080unlessBINDsays otherwise. The passwords in this.env.exampleare known development ones, which is why this Postgres never listens on a network address.