Running the server

Starting

moin-server --config /etc/moin/moin-server.toml

Without --config, the server reads the path in the MOIN_CONFIG environment variable, and failing that, moin-server.toml in the current directory. The server runs in the foreground until it's stopped. See Command line for every option.

If the configuration has a mistake, the server says where and exits before changing anything:

error: invalid server configuration at line 4, column 1: unknown field `max_devices`, expected one of …

Error messages never repeat the line itself, since it may hold a password.

The data directory

On first start the server creates its data directory: data beside the configuration file unless data_dir says otherwise. Inside it:

Path	Contents	Present
coordinator.key	The server's private identity key. Its public half is the server ID.	always
state.redb	Members, roles, invitations, the access settings in force, and managed rooms	always
run/admin.sock	The socket moin-server admin talks to, while the server runs	always
pkarr.redb	Discovery records of members' devices	with [server.pkarr]
acme/	The certificate and ACME account key	with automatic certificates

Treat the directory as the server itself:

• Back it up, together with the configuration file. Losing coordinator.key gives the server a new ID and a community nobody has joined; losing state.redb loses every membership, role, invitation and managed room.
• Keep it private. It holds private keys. The server creates it readable only by its own user; keep it that way.
• Keep it when you reinstall or move the server. Copy the whole directory, with the server stopped, and the community carries on unchanged.
• One server per data directory. A second server started on the same directory refuses to start.

Turning a feature off doesn't delete its files, so turning it back on picks up where it left off.

Changing the configuration

Configuration is read at startup. Restart the server to apply a change. The apps reconnect on their own, and calls keep going while they do, apart from calls relayed through this server, which stop until it's back.

Some settings apply without a restart. Send the server SIGHUP and it reads the file again for name, max_connected_devices and the [access] mode, password and invitations. Nobody is disconnected; devices already connected see a new name when they next connect. Anything else you changed waits for a restart, which the log says. Certificate files are reloaded as they change.

sudo systemctl reload moin-server          # with ExecReload in the unit below
docker kill --signal HUP moin-server       # in a container

If you list rooms in the configuration file rather than managing them, keep each room's room_id when you edit the list: the ID is what identifies the room, and its name can change freely.

As a systemd service

Run the server under its own user, so its files and the administration socket belong to that user alone:

sudo useradd --system --home-dir /var/lib/moin --create-home moin

Point the configuration's data_dir at /var/lib/moin, then create /etc/systemd/system/moin-server.service:

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

[Service]
User=moin
Group=moin
ExecStart=/usr/local/bin/moin-server --config /etc/moin/moin-server.toml
ExecReload=/bin/kill -HUP $MAINPID
Restart=on-failure
TimeoutStopSec=60
# Only needed to bind ports below 1024, as the self-contained setup does:
# AmbientCapabilities=CAP_NET_BIND_SERVICE
# Secrets referenced by password_env or bootstrap_secret_env:
# EnvironmentFile=/etc/moin/secrets.env

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now moin-server

Administration commands run as the same user:

sudo -u moin moin-server admin --config /etc/moin/moin-server.toml status

The moin user needs to be able to read the configuration file.

Logs

The server logs to standard error, so systemd's journal or your container runtime collects it without further setup:

journalctl -u moin-server -f

Choose the level and a JSON format under [log]. See Logs for what the server records and what it leaves out.

Stopping

Ctrl-C, or SIGTERM from systemd or a container runtime, shuts the server down in order: it stops taking new connections, closes the connected apps' sessions, then shuts down its relay and other services. This normally takes a few seconds; give it up to a minute before killing it.

Upgrading

Stop the server, replace the binary, and start it again. The data directory carries over.

moin-server admin has to be the same build as the running server. Upgrade both together, and restart the server before using the new admin commands.