Docker and VPS
Every release publishes an image for linux/amd64 and linux/arm64 to
ghcr.io/blazeiscoding/ownbase. The release run builds it from the release's
commit, runs the container tests against it, and pushes that same image under
the release's version without its v (0.2.0-alpha.5); latest follows the
newest release, as the website's downloads do. The release notes give its digest.
Run it with no clone:
docker run -d --name ownbase -p 8543:8543 -v ownbase-data:/data ghcr.io/blazeiscoding/ownbase
The server prints the claim code the first person to sign up needs
(docker logs ownbase). For the compose file, which names the workspace, makes
it invite-only, restarts the server and drops its privileges, fetch it on its own:
curl -fsSLO https://raw.githubusercontent.com/Blazeiscoding/OwnBase/main/docker/docker-compose.yml
docker compose up -d
OWNBASE_VERSION in the environment or a .env beside the file pins a release.
To build from source, run docker compose -f docker/docker-compose.yml up -d --build
from a clone.
Data lives in a named volume at /data; the server runs as a non-root user.
The compose file's --name and --invite-only set up a new workspace; once it
has an owner, its name and who may join are changed in Workspace settings,
and a restart keeps them (see Who may join).
The workspace's icon is set there too, by the same people, and kept in the
database's meta table (workspace_icon_type, _version and _data), so a
backup and a restore carry it. It is a PNG, JPEG or WebP of at most 256 KB and
1024 pixels a side; the app cuts the picture someone chooses to 256 pixels
square before sending it, and the server checks its first bytes and never
decodes or resizes it. PUT and DELETE /api/admin/workspace/icon change it,
each recorded in the administrative record without the image, and
GET /api/workspace/icon serves it to anyone, signed in or not, since the join
screen shows it; asked for with ?v=<version>, as clients do, it may be cached
for a year, as a new picture has a new version.
GET /api/health checks the process and database. Docker's health status reports
failures; the restart policy restarts exited processes, not merely unhealthy ones.
GET /api/admin/status, signed in as the owner or an admin, says whether the
server is keeping up: schema version, uptime, the database and its log on disk,
attachment storage against its limit, free disk space, waiting and failed app
deliveries (with the oldest waiting), queued, held and failed scheduled
messages, how retention's last sweeps went, open connections, and how late the
event loop ran over the last full minute. It is counts, sizes and times only:
no message, file name, address, token or delivery error, so it can be pasted
into a request for help. In the app, the owner and admins find the same figures
at the end of Diagnostics, shown in full before they are copied or saved
as a file.
Reading the workspace status#
What each line of the status means, what is ordinary, and what to do when it is not. There are no fixed warning thresholds yet: they wait on measuring the workspace on reference hardware (OPT-01). A line that keeps getting worse between two readings an hour apart matters more than any one number.
| Line | Ordinary | Look into it when | What to do |
|---|---|---|---|
| Server (version, schema, uptime) | The version you installed; uptime since the last start | Uptime keeps resetting | The process is restarting: read its log, and check Docker's restart count or the service manager |
| Database and log | The log is a few megabytes. SQLite reuses it rather than shrinking it, so its size is the most it has needed since the server started | The log keeps growing across readings | Something kept the database open for reading a long time, such as a very long backup. It is folded back in when that ends, and removed when the server stops |
| Attachments | Below the --storage-limit-mb you set, or "no limit" | Close to the limit | Raise the limit, or remove old files (deleting their messages frees them), or turn on Keeping less history. Uploads past the limit are refused with 507; nothing is lost |
| Attachment removal | 0 waiting, or a few for a moment; 0 retrying and set aside | Retrying or set aside above 0 | Retrying: the log's attachment cleanup deferred names each file and error, often a permission or a file held open; each is tried again later. Set aside: not a file name the server gives, never tried |
| Free disk | Comfortably more than the database and attachments together | Less than the next few weeks of growth, or less than one backup | Free space before the disk fills: a full disk stops every write, messages included. "unknown" means the system did not say |
| App deliveries waiting | 0, or a few for a moment | The count, or how long the oldest has waited, keeps growing | A receiver is slow or not answering; deliveries to it wait in order. Check the app's endpoint. See Integration delivery |
| App deliveries given up | 0 | Above 0 | An endpoint used up its retries, and its queue was set aside with it. Repair the endpoint, then retry in Apps and integrations, which restores the queue in order. Kept seven days |
| Scheduled messages queued | Messages people scheduled | — | Nothing; they send when due |
| Scheduled messages held for a retry | 0 | Above 0 for long | Each is waiting on something that may clear: an archived channel, a lost membership, a deactivated author. It is tried again a minute later, or as soon as that changes |
| Scheduled messages failed | 0 | Above 0 | Terminal: the author sees it as Not sent under Scheduled and can reschedule it. Nothing retries it |
| Backups | "not scheduled", or last done within the time between backups, with the next one due | A failure, or no backup for longer than the time between them | The server log says why: usually no room on the disk, or no permission to write to --backup-dir. Fix it and the next try goes ahead within the hour |
| History removal | "off", or last done within the hour | "not run yet" for more than an hour, or failures since | Read the server log for retention sweep failed, which carries the error. Each failure is tried again the next hour, and the server keeps running |
| Background work | all running | Failing for more than a minute or two | Read the server log for background work failed, which names the queue and carries the error. The server keeps serving and tries again each round; queued work waits rather than being lost |
| Connections | About one to three sockets per person (tabs, devices) | Many more sockets than people, or both climbing without new members | Clients reconnecting in a loop, often a proxy that drops WebSockets; see Behind a reverse proxy |
| Event loop delay | A few milliseconds at p50 and p99 | p99 near or above 100 ms, the project's main-loop target, minute after minute | The server is busy enough that requests wait. Compare with what was happening (a large import, a retention sweep, a backup) and with free CPU and disk; a sustained figure is worth reporting with the status attached |
The status holds no message, name, file name, address or delivery error, so it can go into a request for help as it is. Diagnostics in the app saves it as a file for that.
Metrics for Prometheus#
Start the server with --metrics-token <token>, or set OWNBASE_METRICS_TOKEN,
which keeps the token out of the process list. GET /metrics then answers in
Prometheus's text format to a request carrying Authorization: Bearer <token>,
and refuses any other with 401. Without a token the path does not exist. The
token must be at least 16 characters with no spaces.
scrape_configs:
- job_name: ownbase
scheme: https
authorization:
credentials_file: /etc/prometheus/ownbase-token
static_configs:
- targets: ["chat.example.org"]
To read it by hand:
curl -H "Authorization: Bearer $OWNBASE_METRICS_TOKEN" https://chat.example.org/metrics.
Metrics hold counts only: no names, ids, addresses or message text. Requests are
labelled by the route's pattern (/api/channels/:id/messages), never the
address asked for, so the number of series stays fixed. An address no route has
is counted under unmatched.
| Metric | Meaning |
|---|---|
ownbase_info{version} | Always 1; the label carries the server's version |
ownbase_uptime_seconds | Seconds since the server started |
ownbase_open_sockets | Sockets open now, signed in or not yet |
ownbase_connected_people | People connected now, each counted once however many devices they use |
ownbase_signed_in_sessions | Sessions signed in and not expired |
ownbase_events_written_total | Counter of events written to the workspace's log; rate() of it is events a second |
ownbase_http_requests_total{method,route,code} | Counter of requests answered |
ownbase_http_request_duration_seconds{method,route} | Histogram of how long requests took |
ownbase_database_bytes, ownbase_database_wal_bytes | Size of the database file and of its write-ahead log |
ownbase_disk_free_bytes | Free space where the workspace is kept, when the system says |
ownbase_files_stored, ownbase_files_stored_bytes | Attachments stored, and their bytes |
ownbase_files_limit_bytes | The --storage-limit-mb limit, when one is set |
ownbase_file_removals{state} | Deleted attachments whose files are still to be removed: waiting, retrying, rejected |
ownbase_app_deliveries{state} | Events for apps waiting to be delivered, and given up on |
ownbase_scheduled_messages{state} | Scheduled messages queued, held for a retry, and failed |
ownbase_backups_enabled | 1 when the server takes backups on a timer |
ownbase_backup_last_success_age_seconds | Seconds since the last scheduled backup finished well; absent until one has |
ownbase_backup_failures | Scheduled backups failed since the last good one |
ownbase_retention_failures | History removals failed since the last good one, when --retention-days is set |
ownbase_event_loop_delay_seconds{quantile} | How late the event loop ran over the last full minute, at 0.5, 0.99 and 1 (the most) |
ownbase_background_queues_failing | Background queues failing now |
ownbase_huddles, ownbase_huddle_people | Huddles going now, and the people in them |
ownbase_push_subscriptions | Browsers subscribed to notifications while OwnBase is closed |
ownbase_pushes_total{result} | Counter of pushes to closed browsers: sent, failed, or dropped from a full queue |
The table above says what is ordinary for each
of these and what to do when it is not. Good first alerts:
ownbase_backup_last_success_age_seconds past twice the time between backups,
ownbase_disk_free_bytes below one backup's size, and
ownbase_app_deliveries{state="failed"} > 0.
An hour of steady use#
scripts/measure-soak.mts runs one server for a set time against scripted
people who post, reply, edit, delete, react, upload and remove files, join and
leave channels, drop and reconnect, sign in and out, read history and start
huddles, and samples the server once a minute. The Soak workflow runs it on
a GitHub runner when started by hand.
The first full run, on 13 November 2026 (v0.2.0, a 4-core runner with 16 GB, Node 24), had 20 people on a workspace seeded with 20,000 messages for 60 minutes:
| Over the hour | Start | End |
|---|---|---|
| Server memory (resident) | 316 MiB | 318.1 MiB |
| JavaScript heap | 30.3 MiB | 31.2 MiB |
| Open handles | 32 | 33 |
| Event loop delay, p99 | 12.9 ms | 11.2 ms |
| Send to receive, p50 and p99 | 3.7, 157 ms | 3.5, 106 ms |
| Database | 17.1 MiB | 34 MiB |
"Start" is the first settled minute (the fifth or sixth); the database is as seeded. About 23,700 actions (10,935 posts, 237 huddles, 211 uploads, 513 reconnects) and none failed. Memory and heap rose by about 2 MiB and 1 MiB in the first 40 minutes and then stayed level for the last 20; the database grows because it keeps what was said. Run it again after a change to how the server holds connections, caches or queues, and compare.
Create the owner account before allowing public traffic, using an SSH tunnel if
necessary. The supplied Compose configuration then requires invitations for new
accounts. Place an HTTPS reverse proxy in front and set --public-url in the
service's command, e.g. https://chat.example.org. WebSocket upgrades must be
forwarded. For an internet deployment, bind the published chat port to localhost
when the reverse proxy runs on the host.
Example Caddy configuration on that host:
chat.example.org {
reverse_proxy 127.0.0.1:8543
}