Deploy MonoRelay to production using all five methods

MonoRelay supports five deployment methods. Docker is the recommended choice for most production environments because it handles dependencies, isolation, and data persistence automatically. If you prefer to run MonoRelay directly on the host, systemd and PM2 both provide automatic restart and log management.

Docker
systemd
Background script
PM2
Direct Python

Docker is the fastest path to a production-ready deployment. The official image is built on python:3.12-slim and exposes port 8787.1. Copy and edit the configuration file

cp config.yml.example config.yml
# Edit config.yml — set access_key and add your provider API keys

2. Start the container

docker compose up -d

3. Verify the container is healthy

docker compose ps
docker compose logs -f monorelay

Common commands

# Stop the service
docker compose down

# Restart after a config change
docker compose restart monorelay

# Rebuild the image after a code update
docker compose build && docker compose up -d

Environment variablesThe docker-compose.yml passes the following environment variables to the container. You can override them in a .env file or directly in docker-compose.yml.

Variable	Description	Default
`TZ`	Container timezone	`Asia/Shanghai`

Data persistenceDocker Compose creates a named volume (monorelay-data) mounted at /app/data. The following files are persisted across container restarts and upgrades:

File	Contents
`data/users.db`	User accounts and roles
`data/requests.db`	Full request and response log
`data/stats.json`	Aggregated request statistics
`data/config.yml`	Runtime configuration (written by the in-browser config editor)

Your config.yml on the host is mounted read-only at /app/config.yml. Edits made through the admin dashboard’s config editor are written to the persistent volume at /app/data/config.yml and take precedence.

The systemd method is recommended for Linux production servers. It provides automatic restart on failure, log integration with journald, and start-on-boot support.Install the serviceRun the install script from the project root. It detects your Python path and current user, writes a unit file to /etc/systemd/system/monorelay.service, and starts the service immediately.

sudo bash scripts/service_install.sh

The generated unit file runs:

python3 -m backend.main --port 8787 --host 0.0.0.0

Manage the service

# Check status
sudo systemctl status monorelay

# Follow logs
sudo journalctl -u monorelay -f

# Restart (e.g., after editing config.yml)
sudo systemctl restart monorelay

# Stop
sudo systemctl stop monorelay

Uninstall the service

sudo bash scripts/service_uninstall.sh

The service is enabled at install time, so it starts automatically on the next system boot. To disable autostart without removing the service, run sudo systemctl disable monorelay.

start-bg.sh is a lightweight bash wrapper that manages MonoRelay as a background process. It automatically creates a virtual environment and installs dependencies on first run.Start in the background

./start-bg.sh start

Check status

./start-bg.sh status

Restart after a config change

./start-bg.sh restart

Stop the server

./start-bg.sh stop

You can pass additional arguments that are forwarded to the underlying Python process:

./start-bg.sh start --port 9000 --config /etc/monorelay/config.yml

The background script uses start.py internally. If start-bg.sh is not executable, run chmod +x start-bg.sh first.

PM2 is a Node.js process manager that works well for MonoRelay if you already use it to manage other services on the same host.Install PM2

npm install -g pm2

Start MonoRelay

pm2 start "python -m backend.main" --name monorelay

Manage the process

# View status
pm2 status

# Follow logs
pm2 logs monorelay

# Restart
pm2 restart monorelay

# Stop
pm2 stop monorelay

Enable start on boot

pm2 save
pm2 startup

Run the command that pm2 startup prints to register PM2 with your init system.

To pass custom flags, use: pm2 start "python -m backend.main --port 9000" --name monorelay

Running Python directly is the simplest option and works well for development or for environments where you manage the process yourself.Install dependencies

pip install -r requirements.txt

Start the server

python -m backend.main

Custom port

python -m backend.main --port 9000

Custom config file path

python -m backend.main --config /etc/monorelay/config.yml

Both flags together

python -m backend.main --host 0.0.0.0 --port 9000 --config /etc/monorelay/config.yml

Running Python directly provides no automatic restart. If the process crashes, you must restart it manually. For production, use systemd, PM2, or Docker instead.

Port reference

Port	Service
`8787`	MonoRelay API and admin dashboard

Data persistence

Regardless of the deployment method, MonoRelay writes its runtime data to the ./data/ directory (relative to the working directory where the server was started). All files in this directory should be backed up if you need to preserve logs and user accounts across reinstalls.

Path	Contents
`data/users.db`	User accounts, roles, and OAuth identities
`data/requests.db`	SQLite log of every request and response
`data/stats.json`	Aggregated usage statistics
`data/config.yml`	Config written by the in-browser editor (overrides `config.yml`)

The data/ directory is excluded from version control (.gitignore). Do not delete it while the server is running.

Nginx reverse proxy

To serve MonoRelay over HTTPS or on a standard port, place Nginx in front of it. The following configuration proxies all traffic to MonoRelay on port 8787 and adds SSE-specific settings for the log stream endpoint.

server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate     /path/to/fullchain.cer;
    ssl_certificate_key /path/to/your-domain.key;

    # SSE log stream — disable buffering
    location /api/logs/stream {
        proxy_pass http://127.0.0.1:8787;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_cache off;
        chunked_transfer_encoding on;
        tcp_nopush on;
        tcp_nodelay on;
        keepalive_timeout 300;
    }

    # All other routes
    location / {
        proxy_pass http://127.0.0.1:8787;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$host$request_uri;
}

After adding the Nginx config, set public_host in config.yml so MonoRelay generates correct API URLs in the admin dashboard:

config.yml

server:
  public_host: "https://your-domain.com"

Get Started

Configuration

Admin Dashboard

Authentication

Deploy MonoRelay to production using all five methods

Port reference

Data persistence

Nginx reverse proxy

Build docs developers (and LLMs) love

Get Started

Configuration

Admin Dashboard

Authentication

Documentation Index

​Port reference

​Data persistence

​Nginx reverse proxy

Build docs developers (and LLMs) love

Port reference

Data persistence

Nginx reverse proxy