Run without the dashboard

Without a terminal, for example as a service, the server runs without the dashboard and also writes its log to standard output:

./uniform-chat-server --Host:Ui=None

Host:Ui chooses the mode:

Value	Mode
Auto (default)	The dashboard when input and output are a terminal; none when either is redirected, as under systemd or with > server.log
Dashboard	Dashboard for monitoring server status and for perusing logs.
None	No dashboard.

Stop the server with Ctrl+C, or with SIGTERM from a service manager. It stops within a few seconds: clients waiting for new messages get their answer at once, and the database is written out before the program ends. The log shows Stopping… and Stopped.

As a user service

To run the server as your own user, put the program in a folder of its own, e.g. ~/uniform-chat-server, then run it from a user unit. Its settings are in ~/.config/uniform-chat-server and its data in ~/.local/share/uniform-chat-server.

Unpack the downloaded release there:

mkdir -p ~/uniform-chat-server
tar -xzf uniform-chat-server-<version>-linux-x64.tar.gz -C ~/uniform-chat-server --strip-components=1

Or, from the source, publish it there:

dotnet publish src/Uniform.Chat.Server -c Release -o ~/uniform-chat-server

Then write the unit file:

# ~/.config/systemd/user/uniform-chat-server.service
[Unit]
Description=Uniform Chat homeserver

[Service]
ExecStart=%h/uniform-chat-server/uniform-chat-server
Restart=on-failure

[Install]
WantedBy=default.target

systemctl --user enable --now uniform-chat-server
journalctl --user -u uniform-chat-server -f

systemd connects the server's input to /dev/null and its output to the journal, so Auto runs without the dashboard there and the log goes to the journal. A user service stops when you log out, unless lingering is on: sudo loginctl enable-linger $USER.

From the apt package

The uniform-chat-server package, see Installing, sets up the system service for you:

What	Where
Program	/opt/uniform-chat/server/uniform-chat-server, also as the command uniform-chat-server
Service	uniform-chat-server, run by the system user uniform-chat, which the package creates
Settings	/etc/uniform-chat-server/settings.json
Data: database, signing key and files	/var/lib/uniform-chat-server
Logs: one file per start, the newest 20 kept; also in the journal, journalctl -u uniform-chat-server	/var/log/uniform-chat-server

The service is off after installing, as the server needs its name and address first. Write the settings, readable only by the service, as they may hold secrets, then start it and have it start at boot:

sudo nano /etc/uniform-chat-server/settings.json
sudo chown uniform-chat:uniform-chat /etc/uniform-chat-server/settings.json
sudo chmod 600 /etc/uniform-chat-server/settings.json
sudo systemctl enable --now uniform-chat-server

Step 3 below has a short example of the settings, and Installing a complete one. The service may listen on ports below 1024, such as 443. It cannot see the home folders, so keep certificates elsewhere; the note at the end of this page tells how to give it certbot's certificates. Control it and read its log as in the table below. sudo apt upgrade restarts a running service with the new version.

To change the service, e.g. to add environment variables, use sudo systemctl edit uniform-chat-server, which keeps your changes over updates. sudo apt remove uniform-chat-server stops and removes the service and the program, but keeps the settings, the data and the user.

To manage the running service, open the dashboard on it; the service keeps serving meanwhile:

sudo uniform-chat-server manage

The manager connects through the service's admin socket, /run/uniform-chat-server/admin.sock, which only root and the uniform-chat group may open, and needs no account. It has the users, rooms and reports windows, the service's logs, and its settings. The settings work as in the dashboard, through the service itself: Apply changes the running service at once, and Save has the service write its settings file. Options marked ↻ take effect when the service starts again: sudo systemctl restart uniform-chat-server. Secrets, such as registration tokens, show as hidden and are changed only in the file. Ctrl+Q closes the manager, not the server. See Remote administration to manage a server on another machine.

The dashboard of the server itself still runs when the service is stopped. Only one server runs on a data folder at a time: while the service still runs or is stopping, it exits at once with Another server (pid N) is using /var/lib/uniform-chat-server; stop it first.

sudo systemctl stop uniform-chat-server
sudo -u uniform-chat XDG_CONFIG_HOME=/etc XDG_DATA_HOME=/var/lib uniform-chat-server --Host:Ui=Dashboard
sudo systemctl start uniform-chat-server

If you set up the service by hand before, with the steps below, remove your unit file /etc/systemd/system/uniform-chat-server.service, which would otherwise be used in place of the package's, and give the settings to the new user; the service hands the data folder over itself at its next start:

sudo rm /etc/systemd/system/uniform-chat-server.service
sudo chown -R uniform-chat:uniform-chat /etc/uniform-chat-server
sudo systemctl daemon-reload
sudo systemctl restart uniform-chat-server

As a system service (Ubuntu)

Without the package, set the service up by hand.

On a server, run it as a system service named uniform-chat-server: it starts at boot, runs as a user of its own, and is controlled with sudo systemctl. The steps below put the program in /opt/uniform-chat-server, the settings in /etc/uniform-chat-server, and the data in /var/lib/uniform-chat-server.

1. Create a system user for the server, with no login:

   sudo useradd --system --home-dir /var/lib/uniform-chat-server --shell /usr/sbin/nologin uniform-chat-server
   

2. Unpack the downloaded release in /opt/uniform-chat-server; or, from the source, publish it there:

   sudo mkdir -p /opt/uniform-chat-server
   sudo tar -xzf uniform-chat-server-<version>-linux-x64.tar.gz -C /opt/uniform-chat-server --strip-components=1
   

   sudo dotnet publish src/Uniform.Chat.Server -c Release -o /opt/uniform-chat-server
   

3. Write the settings to /etc/uniform-chat-server/settings.json, readable only by the server, as it may hold secrets such as the TURN secret. For example, behind nginx on the same machine:

   sudo mkdir -p /etc/uniform-chat-server
   sudo nano /etc/uniform-chat-server/settings.json
   sudo chown -R uniform-chat-server:uniform-chat-server /etc/uniform-chat-server
   sudo chmod 600 /etc/uniform-chat-server/settings.json
   

   {
     "Urls": "http://127.0.0.1:8008",
     "Server": {
       "ServerName": "example.org",
       "PublicBaseUrl": "https://example.org",
       "TrustedProxies": "127.0.0.1",
       "Registration": "Token",
       "RegistrationTokens": "a-long-random-token"
     }
   }
   

   Installing has a complete example with federation and calls, and the nginx site in front; Settings lists every option.

4. Write the unit file /etc/systemd/system/uniform-chat-server.service:

   [Unit]
   Description=Uniform Chat homeserver
   After=network-online.target
   Wants=network-online.target
   
   [Service]
   User=uniform-chat-server
   Group=uniform-chat-server
   ExecStart=/opt/uniform-chat-server/uniform-chat-server --Host:Ui=None
   WorkingDirectory=/var/lib/uniform-chat-server
   # Settings from /etc/uniform-chat-server, data in /var/lib/uniform-chat-server
   Environment=XDG_CONFIG_HOME=/etc
   Environment=XDG_DATA_HOME=/var/lib
   StateDirectory=uniform-chat-server
   StateDirectoryMode=0700
   Restart=on-failure
   RestartSec=5
   # Stop gracefully: SIGTERM, then wait for the database to close
   TimeoutStopSec=30
   # Hardening: no new privileges, read-only system, private /tmp
   NoNewPrivileges=true
   ProtectSystem=strict
   ProtectHome=true
   PrivateTmp=true
   ReadWritePaths=/var/lib/uniform-chat-server /etc/uniform-chat-server
   
   [Install]
   WantedBy=multi-user.target
   

   The server adds its own name to XDG_CONFIG_HOME and XDG_DATA_HOME, which gives the two folders above. /etc/uniform-chat-server is writable so that the settings window, if you ever run the dashboard as this user, can save there; take it out of ReadWritePaths to keep the settings read-only.

5. Start it, and have it start at boot:

   sudo systemctl daemon-reload
   sudo systemctl enable --now uniform-chat-server
   

Then control it with systemctl, and read its log from the journal:

Command	Does
sudo systemctl status uniform-chat-server	Show whether it runs, and the latest log lines
sudo systemctl stop uniform-chat-server	Stop it
sudo systemctl start uniform-chat-server	Start it
sudo systemctl restart uniform-chat-server	Restart it, e.g. after changing the settings
sudo systemctl disable uniform-chat-server	Not start it at boot any more
journalctl -u uniform-chat-server -f	Follow the log
journalctl -u uniform-chat-server --since today	Today's log

The server also keeps its own log files in /var/lib/uniform-chat-server/logs, with its database and signing key; see Files. To update the server, see Updating.

Note

To serve HTTPS itself, without a proxy, the server needs to read the certificate and to listen on port 443:

• Ports below 1024 need AmbientCapabilities=CAP_NET_BIND_SERVICE in the [Service] section, which the package's service has; or listen on 8448 instead.

• certbot keeps its files readable only by root. Copy them where the server can read them in a deploy hook, e.g. /etc/letsencrypt/renewal-hooks/deploy/uniform-chat-server.sh; with the package, the user is uniform-chat:

  #!/bin/sh
  install -o uniform-chat-server -g uniform-chat-server -m 600 "$RENEWED_LINEAGE/fullchain.pem" "$RENEWED_LINEAGE/privkey.pem" /etc/uniform-chat-server/tls/
  

  and point Tls:CertificatePath and Tls:KeyPath at /etc/uniform-chat-server/tls/. The server picks up renewed files without a restart.