Преминаване към съдържанието

Преглеждате предварителния сайт с документацияСъдържанието тук е за тестване и може да се различава от продукционната документация.

Към продукционната документация

Run as a service

Това съдържание все още не е достъпно на вашия език.

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 first.

From the application checkout, copy the units:

Use your administrative shell for this section, not the onetime service account. Install on 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.

Terminal window
sudo cp etc/examples/systemd/onetimesecret-*.service /etc/systemd/system/

Full mode with SQLite: allow the account database directory

Section titled “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:

Terminal window
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.

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.

Terminal window
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, sign in, restart the service, and sign in again to check database writes and persistence. Merely reaching the homepage does not exercise those writes.

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:

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 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 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

Section titled “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

Section titled “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, then enable both units:

Terminal window
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.

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.

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:

Terminal window
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

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:

Terminal window
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.