# Run as a service

> Keep a bare-metal install running under systemd with the three unit files the project ships, and decide whether you need more than the web unit.

An install started from a shell dies with the shell. The project ships three systemd unit files under `etc/examples/systemd/` — `onetimesecret-web.service`, `onetimesecret-worker.service` and `onetimesecret-scheduler.service`. Use them as the starting point, then add the storage permission below if you use full authentication with SQLite.

They assume a finished bare-metal install, so work through [Install on Linux](/en/install/linux) first.

## Install the units

From the application checkout, copy the units:

Use your administrative shell for this section, not the `onetime` service account. [Install on Linux](/en/install/linux) enters that account’s login shell; run `exit` to return to your administrative shell, then change to `/var/lib/onetimesecret` before running the commands below. The service account does not need sudo rights. Keep the SQLite directory grant below when using the default full-mode database.

```bash
sudo cp etc/examples/systemd/onetimesecret-*.service /etc/systemd/system/
```

### Full mode with SQLite: allow the account database directory

The default `AUTH_DATABASE_URL` is `sqlite://data/auth.db`. With the shipped working directory, this is `/var/lib/onetimesecret/data/auth.db`. The units use `ProtectSystem=strict` and grant writes to `tmp` and `log` only. Without an additional grant, SQLite cannot create or update the database or its journal.

Before starting any service that uses this database, add a drop-in for all three units:

```bash
for unit in onetimesecret-web onetimesecret-worker onetimesecret-scheduler; do
  sudo install -d -m 0755 "/etc/systemd/system/$unit.service.d"
  printf '[Service]\nStateDirectory=onetimesecret/data\nStateDirectoryMode=0750\n' |
    sudo tee "/etc/systemd/system/$unit.service.d/sqlite.conf" >/dev/null
done
```

`StateDirectory` creates the directory with the unit’s `onetime` ownership and allows writes there despite `ProtectSystem=strict`. It adds to the shipped `tmp` and `log` entries; do not reset that list or disable filesystem protection. See the [systemd directory settings](https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#RuntimeDirectory=).

This drop-in is for the default SQLite path. For a custom path, create its parent directory with `onetime` ownership and grant that directory with `ReadWritePaths=` in each unit instead. SQLite needs directory access for journals as well as access to the database file. PostgreSQL deployments do not need this SQLite directory grant.

### Start the web service

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now onetimesecret-web
```

`enable --now` starts the service and enables it at boot. If applying a drop-in to running services, restart the web service and any worker or scheduler you already run so they receive the new permissions.

Inspect `systemctl cat onetimesecret-web` and `journalctl -u onetimesecret-web` if it fails. In full mode, [create the first account](/en/install/verify#create-the-first-account), sign in, restart the service, and sign in again to check database writes and persistence. Merely reaching the homepage does not exercise those writes.

## What the units assume

Each unit runs as the user and group `onetime`, with `WorkingDirectory` set to `/var/lib/onetimesecret`, and expects Valkey or Redis to be up already — the web unit orders itself `After=network.target redis-server.service valkey.service`, hedging across both common service names. The worker and scheduler additionally order themselves after `onetimesecret-web.service`.

The units source `.env` from the working directory inside `ExecStart`:

```ini
ExecStart=/bin/bash -lc 'set -a; source .env; set +a; exec bundle exec puma -C etc/puma.rb'
```

The worker and scheduler use the same form around `bin/ots worker` and `bin/ots scheduler`. All three units also read `/etc/default/onetimesecret` before `.env`; see [Environment files](#environment-files) for which value applies.

The `-l` in `bash -lc` is load-bearing beyond `.env`. It is what puts a Ruby installed for the `onetime` user on the service’s `PATH` — but only through the files a login shell actually reads, which are `/etc/profile` and then the first of `~/.bash_profile`, `~/.bash_login` and `~/.profile`. `~/.bashrc` is not among them, so a version manager initialized there is invisible here and the unit dies with `bundle: command not found`. [Install on Linux](/en/install/linux) writes the rbenv line into `~/.profile` for that reason; if you set Ruby up some other way, put its initialization in one of those three files, or in an `/etc/profile.d/` snippet that `/etc/profile` picks up.

Setting `PATH` through systemd’s `Environment=` or `EnvironmentFile=` is not a substitute. Those are applied to the process systemd starts, which here is the login shell, and `/etc/profile` then runs and sets its own `PATH` over the top.

### If the app is not at /var/lib/onetimesecret

`WorkingDirectory` is a literal path, not a search. An install that sits in the `onetime` user’s home directory, or under `/opt`, will not be found, and systemd fails the unit before Puma runs. Move the install to `/var/lib/onetimesecret` rather than editing the units: it is the layout the shipped files are written against, and it keeps all three of them correct as delivered. If you keep the app elsewhere, change `WorkingDirectory` in all three files and keep them identical — the web unit’s own header tells you to adjust it.

`ProtectHome=true` is a second reason to keep the shipped layout. It makes `/home` inaccessible to the service, so an install — or a version manager — under a user’s home directory in `/home` stays unreachable even once `WorkingDirectory` points at it. `/var/lib/onetimesecret` is not under `/home` and is unaffected.

## When you need the worker and the scheduler

The worker and scheduler unit headers say they are required for full authentication mode with PostgreSQL and RabbitMQ. That is wrong in both halves, and the real rule is simpler: **background jobs are off unless you set `JOBS_ENABLED=true`.** While jobs are off, the web process sends email synchronously in-process, nothing publishes work for the worker to consume, and both extra services would sit idle. RabbitMQ matters in exactly the same case — it is the broker the worker consumes from, and nothing needs it until jobs are on.

Authentication mode does not decide this. Full mode adds a SQL account database, which defaults to SQLite, not a job queue; a full-mode instance with jobs off runs on the web unit alone.

`JOBS_ENABLED` is read from the environment. Set `JOBS_ENABLED=true` in one of the two environment files described in [Environment files](#environment-files), then enable both units:

```bash
sudo systemctl enable --now onetimesecret-worker onetimesecret-scheduler
```

While jobs are off, the health endpoint reports the job queue as `not_configured` rather than as a failure, so an instance running on the web unit alone does not look broken there.

## What the units already handle

All three restart `on-failure` after 5 seconds, with a start limit of five attempts per 60 seconds so a genuinely broken instance stops flapping and stays down where you can see it. Stop timeouts differ deliberately: 30 seconds for the web and scheduler units, 60 seconds for the worker so in-flight jobs can drain before it is killed.

Each unit runs with `NoNewPrivileges=true`, `ProtectSystem=strict`, `ProtectHome=true` and `PrivateTmp=true`, and declares `StateDirectory=onetimesecret/tmp onetimesecret/log`. Under `ProtectSystem=strict` the filesystem is read-only apart from what the unit is granted, so any additional path the app has to write to needs granting deliberately.

## Environment files

Each unit reads two files, in this order:

1. `/etc/default/onetimesecret`, through `EnvironmentFile=-/etc/default/onetimesecret`. The leading `-` means the service starts whether or not the file exists.
2. `.env` in the working directory, sourced inside `ExecStart`.

A variable set in both files takes its value from `.env`, because it is read last. Between the two, `bash -l` in `ExecStart` reads the login files described above, such as `~/.profile`, so a variable exported there also overrides `/etc/default/onetimesecret`.

`/etc/default/onetimesecret` is the file for a service installation, such as staging or production; `.env` is the development file. On a service installation, `.env` keeps what `bin/install` wrote there, and any setting you add for the host, such as `JOBS_ENABLED`, goes in `/etc/default/onetimesecret`. Keep each variable in one file: if you set a variable in `/etc/default/onetimesecret`, remove it from `.env`, or the `.env` value still applies. systemd reads `/etc/default/onetimesecret` as root before it starts the unit, so keep the file owned by root with mode `600`; the `onetime` user does not need to read it.

Leave the secrets that `bin/install` manages in `.env`: `SECRET` and the other keys it writes there. The installer reads them only from `.env`. If `SECRET` is missing, it stops; if another of its keys is missing, it writes a new value to `.env`, which then overrides the copy in `/etc/default/onetimesecret`.

To see the value of a variable, here `JOBS_ENABLED`, that a running service uses:

```bash
pid=$(systemctl show -p MainPID --value onetimesecret-web)
if [ "$pid" = 0 ]; then
  echo "onetimesecret-web is not running"
else
  sudo cat "/proc/$pid/environ" | tr '\0' '\n' | grep '^JOBS_ENABLED='
fi
```

## Without systemd

`Procfile.example` defines the same processes for any Procfile runner — foreman, hivemind or goreman. Only the `web` line is uncommented; the worker and scheduler lines are shipped commented out. Export the environment first, the same way the units do:

```bash
set -a; source .env; set +a
foreman start -f Procfile.example
```

In a container none of this applies. The main image runs a single process, and multi-process supervision is the S6 variant’s job.

Once the services are running, confirm the instance actually serves: [Verify your install](/en/install/verify).