Deployment

This page covers running a server for real users: a TLS reverse proxy in front, a service manager to keep it running, and logs. It assumes you have a working server from Run a server.

Reverse proxy

Run originchats-osl behind a reverse proxy that handles HTTPS. The server listens on 127.0.0.1:5613 by default, which only the proxy on the same machine can reach.

The proxy must:

• Forward every path to the server, including WebSocket upgrades on /. HTTP routes and the WebSocket share one port.
• Allow request bodies at least as large as the server’s own limit: 32 MiB or twice attachments.max_size, whichever is larger. With the default 100 MiB max_size, that’s 200 MiB.
• Serve the same public address you set in server.url, not the private listen address.

With Caddy, WebSocket upgrades are forwarded automatically:

chat.example.com {
  reverse_proxy 127.0.0.1:5613
}

With nginx, forward the upgrade headers and raise the body limit:

server {
  listen 443 ssl;
  server_name chat.example.com;
  # ssl_certificate and ssl_certificate_key go here

  client_max_body_size 200m;

  location / {
    proxy_pass http://127.0.0.1:5613;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 1h;
  }
}

The server pings every WebSocket every 30 seconds, so a proxy read timeout of a minute or more keeps idle connections open.

/info is a public page that works as a basic reachability check. There’s no separate health endpoint.

Secrets

Keep secrets in .env in the database directory, or in the service’s environment. Values already in the environment win over .env. See Environment variables for the full list.

Managed restarts and updates

Start the server through the launcher:

./scripts/run.sh /srv/originchats/db

Running under scripts/run.sh gives you two things that a directly started binary lacks:

• The owner can restart or update the server from a client with server_maintenance. A server started with originchats-osl use reports both actions as unsupported, with the reason Start the server with scripts/run.sh to enable remote restarts and updates.
• A restart or update request makes the server exit with status 75, and the launcher starts it again.

The launcher stops on any other exit, including a crash or a startup error. It doesn’t restart after those, so run it under a service manager if you want crash recovery and start on boot.

See Updating for what an update does and how to prepare for one.

Run as a service

This systemd unit runs the launcher, restarts it after a crash, and starts it on boot. Adjust the user and paths.

[Unit]
Description=OriginChats server
After=network-online.target
Wants=network-online.target

[Service]
User=originchats
WorkingDirectory=/srv/originchats/originchats-osl
ExecStart=/srv/originchats/originchats-osl/scripts/run.sh /srv/originchats/db
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

The launcher compiles the server each time it starts, so the service user needs osl and Go on its PATH and write access to the checkout. The launcher exits with status 0 when systemd stops it, so a normal systemctl stop isn’t treated as a failure.

Logs

The server writes logs to standard output. Under systemd, read them with journalctl -u <unit>.

Each line has a time, a level, a source such as server.startup or api.request, a message, and extra fields. Fields whose names contain password, token, validator, or signature, and a field named auth, are shown as [redacted].

Set the lowest level shown with ORIGINCHATS_LOG_LEVEL, or LOG_LEVEL if that’s unset. The chosen level and every level below it in this table are printed.

Level	Used for
debug	Every WebSocket command from a logged-in user, and every HTTP request.
info	Startup, database loading, migrations, and other normal events. This is the default.
success	Completed milestones, such as server listening.
warn	Failed commands, commands that took 500 ms or more, HTTP 4xx responses, and HTTP requests that took a second or more.
error	HTTP 5xx responses, failed notification delivery, failed updates, and startup failures.