barycenter/book/src/deployment/systemd.md

Linux systemd

This guide covers deploying Barycenter as a systemd service on Linux distributions such as Debian, Ubuntu, Fedora, RHEL, and Arch Linux. A systemd unit file is provided in the repository at deploy/systemd/barycenter.service.

Prerequisites

• A Linux system with systemd
• The Rust toolchain (to build from source) or a pre-built binary
• SQLite development libraries (if using SQLite) or a reachable PostgreSQL instance

Step 1: Build the Binary

cargo build --release

The release binary is located at target/release/barycenter.

Step 2: Create a Service User

Create a dedicated system user with no login shell and a home directory for data:

sudo useradd -r -s /bin/false -d /var/lib/barycenter barycenter

Step 3: Install the Binary

sudo cp target/release/barycenter /usr/local/bin/barycenter
sudo chmod 755 /usr/local/bin/barycenter

Step 4: Create Directories

sudo mkdir -p /etc/barycenter
sudo mkdir -p /var/lib/barycenter/data
sudo chown -R barycenter:barycenter /var/lib/barycenter

Directory	Purpose
/etc/barycenter/	Configuration file
/var/lib/barycenter/data/	Database (SQLite), RSA private key, JWKS

Step 5: Install the Configuration File

Copy and edit the configuration file:

sudo cp config.toml /etc/barycenter/config.toml
sudo chmod 640 /etc/barycenter/config.toml
sudo chown root:barycenter /etc/barycenter/config.toml

Edit /etc/barycenter/config.toml to set the correct values for your deployment. At a minimum, configure the public_base_url and database path:

[server]
public_base_url = "https://idp.example.com"

[database]
url = "sqlite:///var/lib/barycenter/data/barycenter.db?mode=rwc"

[keys]
jwks_path = "/var/lib/barycenter/data/jwks.json"
private_key_path = "/var/lib/barycenter/data/private_key.pem"

Step 6: Install the systemd Unit

sudo cp deploy/systemd/barycenter.service /etc/systemd/system/barycenter.service
sudo systemctl daemon-reload

The unit file runs Barycenter as the barycenter user, reads the configuration from /etc/barycenter/config.toml, and restarts the service on failure.

Step 7: Enable and Start

sudo systemctl enable --now barycenter

This enables Barycenter to start automatically on boot and starts it immediately.

Managing the Service

# Check status
sudo systemctl status barycenter

# View logs
sudo journalctl -u barycenter

# Follow logs in real time
sudo journalctl -u barycenter -f

# Restart after a configuration change
sudo systemctl restart barycenter

# Stop the service
sudo systemctl stop barycenter

# Disable automatic start on boot
sudo systemctl disable barycenter

Log Level

Set the log level through the RUST_LOG environment variable. You can override it in the unit file by creating a drop-in:

sudo systemctl edit barycenter

Add the following content:

[Service]
Environment=RUST_LOG=info

Save and restart:

sudo systemctl restart barycenter

Common log level values:

Value	Description
error	Only errors
warn	Warnings and errors
info	Informational messages (recommended for production)
debug	Detailed debugging output
barycenter=debug	Debug output for Barycenter only, info for dependencies

File Permissions Summary

Path	Owner	Mode	Purpose
/usr/local/bin/barycenter	root:root	755	Application binary
/etc/barycenter/config.toml	root:barycenter	640	Configuration file
/var/lib/barycenter/data/	barycenter:barycenter	750	Data directory
/var/lib/barycenter/data/private_key.pem	barycenter:barycenter	600	RSA private key (created at first run)

Upgrading

To upgrade Barycenter to a new version:

# Build the new version
cargo build --release

# Stop the service
sudo systemctl stop barycenter

# Replace the binary
sudo cp target/release/barycenter /usr/local/bin/barycenter

# Start the service
sudo systemctl start barycenter

# Verify
sudo systemctl status barycenter
sudo journalctl -u barycenter --since "1 minute ago"

Database migrations run automatically on startup.

Further Reading

• Production Checklist -- steps to verify before going live
• Reverse Proxy and TLS -- placing Barycenter behind nginx
• Backup and Recovery -- backing up the data directory