Docs / Hosting OwnBase

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.

LineOrdinaryLook into it whenWhat to do
Server (version, schema, uptime)The version you installed; uptime since the last startUptime keeps resettingThe process is restarting: read its log, and check Docker's restart count or the service manager
Database and logThe log is a few megabytes. SQLite reuses it rather than shrinking it, so its size is the most it has needed since the server startedThe log keeps growing across readingsSomething 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
AttachmentsBelow the --storage-limit-mb you set, or "no limit"Close to the limitRaise 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 removal0 waiting, or a few for a moment; 0 retrying and set asideRetrying or set aside above 0Retrying: 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 diskComfortably more than the database and attachments togetherLess than the next few weeks of growth, or less than one backupFree space before the disk fills: a full disk stops every write, messages included. "unknown" means the system did not say
App deliveries waiting0, or a few for a momentThe count, or how long the oldest has waited, keeps growingA receiver is slow or not answering; deliveries to it wait in order. Check the app's endpoint. See Integration delivery
App deliveries given up0Above 0An 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 queuedMessages people scheduled—Nothing; they send when due
Scheduled messages held for a retry0Above 0 for longEach 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 failed0Above 0Terminal: 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 dueA failure, or no backup for longer than the time between themThe 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 sinceRead 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 workall runningFailing for more than a minute or twoRead 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
ConnectionsAbout one to three sockets per person (tabs, devices)Many more sockets than people, or both climbing without new membersClients reconnecting in a loop, often a proxy that drops WebSockets; see Behind a reverse proxy
Event loop delayA few milliseconds at p50 and p99p99 near or above 100 ms, the project's main-loop target, minute after minuteThe 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.

MetricMeaning
ownbase_info{version}Always 1; the label carries the server's version
ownbase_uptime_secondsSeconds since the server started
ownbase_open_socketsSockets open now, signed in or not yet
ownbase_connected_peoplePeople connected now, each counted once however many devices they use
ownbase_signed_in_sessionsSessions signed in and not expired
ownbase_events_written_totalCounter 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_bytesSize of the database file and of its write-ahead log
ownbase_disk_free_bytesFree space where the workspace is kept, when the system says
ownbase_files_stored, ownbase_files_stored_bytesAttachments stored, and their bytes
ownbase_files_limit_bytesThe --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_enabled1 when the server takes backups on a timer
ownbase_backup_last_success_age_secondsSeconds since the last scheduled backup finished well; absent until one has
ownbase_backup_failuresScheduled backups failed since the last good one
ownbase_retention_failuresHistory 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_failingBackground queues failing now
ownbase_huddles, ownbase_huddle_peopleHuddles going now, and the people in them
ownbase_push_subscriptionsBrowsers 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 hourStartEnd
Server memory (resident)316 MiB318.1 MiB
JavaScript heap30.3 MiB31.2 MiB
Open handles3233
Event loop delay, p9912.9 ms11.2 ms
Send to receive, p50 and p993.7, 157 ms3.5, 106 ms
Database17.1 MiB34 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
}

This page is made from docs/DEPLOYMENT.md.