Installation with byroctl (recommended)¶

byroctl installs byro as a set of Docker containers, keeps everything it needs in one directory and installs updates with a single command. It is meant for administrators of small and medium sized organizations who want a working byro on a Linux server without assembling the pieces by hand.

What you get:

the official byro container image, pinned to an exact release,
a PostgreSQL database (or a connection to your own),
optionally Caddy as a reverse proxy that obtains and renews TLS certificates,
one configuration file, byro.conf,
plugins from a catalog or as pip requirements, built into the image for you (plugin management),
byroctl update with a safeguard copy of the database before every update.

Everything byroctl starts is plain Docker Compose. You can always look at the files in the installation directory and use docker compose directly.

Prerequisites¶

A Linux server (Debian or Ubuntu are the tested platforms) with a DNS name that points to it.
Docker Engine 24 or newer with the Compose plugin 2.20 or newer. Your user must be allowed to use Docker (member of the docker group). Note that membership in that group is equivalent to root access on the machine.
bash 4 or newer and curl. Both are present on every current Linux distribution. macOS still ships bash 3.2, so to try the installer on a Mac install a current bash first (brew install bash) and run the commands below with that bash (/opt/homebrew/bin/bash) or a Linux VM.
Free ports 80 and 443 if Caddy should terminate TLS for you, otherwise a reverse proxy of your own that forwards to byro.
An SMTP server to send mail. It can be configured later.
Roughly 2 GB of free disk space for the images, plus room for your data.

The installer does not need root. byro lives in one directory that you own; the installer proposes the directory you run it from. A system-wide location such as /opt/byro works too - create it once and hand it to your user:

$ sudo mkdir -p /opt/byro && sudo chown "$(id -u):$(id -g)" /opt/byro

Installation¶

Create the directory byro should live in, change into it and run the bootstrap script. It downloads byroctl for the current stable release, verifies it and starts the installation:

$ mkdir ~/byro && cd ~/byro
$ bash -c "$(curl -fsSL https://raw.githubusercontent.com/byro/byro/stable/install.sh)"

Add -- --root /path to name the directory up front (a relative path is taken from the current directory), -- --dry-run to see what the script would do without changing anything, -- --version vYYYY.M.P to install a specific release instead of the current stable one, or -- --no-symlink if byroctl should not be linked into /usr/local/bin or ~/.local/bin.

The installer asks a few questions, each with a sensible default:

the installation directory, proposing the current one (skipped with --root); a directory that already holds files but no byro installation has to be confirmed,
the public URL of your byro, for example https://byro.example.org,
whether byro should obtain TLS certificates itself (Caddy, ports 80 and 443 must be free), whether you run your own reverse proxy, or whether byro is reached directly without HTTPS (only for tests),
language and time zone,
whether to use the built-in PostgreSQL or an external database,
how to send mail: a mail server on the same machine, an external SMTP server, or later,
which plugins from the catalog to install (short names such as finance-import-bank-files; none by default, see plugin management),
user name, e-mail address and password of the first administrator.

Then it writes the configuration, downloads the images, builds the plugin image if you chose plugins, creates the database schema, creates the administrator account and starts byro. At the end it prints the URL and the paths you need to know.

Unattended installation¶

Every answer can be given up front with --set KEY=VALUE, passwords only through environment variables so that they never appear in a process list or shell history. Without a terminal nobody can confirm the installation directory, so --non-interactive requires --root:

$ export BYROCTL_ADMIN_PASSWORD='…'
$ bash -c "$(curl -fsSL https://raw.githubusercontent.com/byro/byro/stable/install.sh)" -- \
    --non-interactive --root /opt/byro \
    --set BYRO_SITE_URL=https://byro.example.org \
    --set BYROCTL_PROXY=caddy \
    --set BYRO_LANGUAGE_CODE=de --set BYRO_TIME_ZONE=Europe/Berlin \
    --set BYROCTL_MAIL=smtp --set BYRO_MAIL_HOST=mail.example.org --set BYRO_MAIL_FROM=byro@example.org \
    --admin-user admin --admin-email admin@example.org

BYROCTL_PROXY accepts caddy, own or none; BYROCTL_DB accepts internal or external; BYROCTL_MAIL accepts host, smtp or skip; BYROCTL_PLUGINS takes catalog short names separated by spaces (--set BYROCTL_PLUGINS="finance-import-bank-files"). Plugins given as pip requirements use --plugin instead, once per plugin: --plugin 'byro-x==1.2.0'. Passwords for an external database or an SMTP account come from BYROCTL_DB_PASSWORD and BYROCTL_MAIL_PASSWORD. --skip-superuser does not create an administrator account (create one later with byroctl manage createsuperuser); --no-pull uses an image that is already present locally instead of pulling one (only useful for development). byroctl install --help lists all options.

If the installation stops halfway, for example because the administrator's e-mail address was rejected, fix the input and run byroctl install again. It continues where it stopped and does not ask the general questions again.

The installation directory¶

Everything lives in the directory you chose, here /opt/byro:

/opt/byro/
├── byroctl                     the tool itself (linked into /usr/local/bin)
├── byro.conf                   your configuration - the only file you edit
├── .env -> byro.conf           lets plain "docker compose" read the same file
├── docker-compose.yml          byro services (do not edit, byroctl replaces it on update)
├── compose/postgres.yml        add-on: built-in PostgreSQL
├── compose/caddy.yml           add-on: Caddy reverse proxy
├── compose/plugins.yml         add-on: byro with plugins (active while plugins are listed)
├── Caddyfile
├── plugin-catalog.conf         the plugin catalog of the installed release
├── plugins/plugins.txt         your plugin list (pip requirements)
├── plugins/Dockerfile          builds the image with plugins (do not edit)
├── data/                       documents, uploads, keys, the secret key, logs
├── db/                         PostgreSQL data
├── caddy/                      certificates (only with Caddy)
├── backups/                    safeguard copies made before updates and plugin changes
└── .byroctl/                   internal state

Local additions, for example extra labels for a reverse proxy, belong in a docker-compose.override.yml next to these files; byroctl never touches it.

Configuration¶

byro.conf holds the settings of byro itself (BYRO_*, see Configuration for every option), the deployment settings (BYRO_DEPLOY_*) and the list of Compose files (COMPOSE_FILE). Read and change it with byroctl:

$ byroctl config get BYRO_SITE_URL
$ byroctl config set BYRO_MAIL_HOST mail.example.org --apply
$ byroctl config edit
$ byroctl config check

--apply validates the file and recreates only the containers whose settings changed. Passwords are set from the environment instead of the command line:

$ BYROCTL_VALUE='…' byroctl config set BYRO_MAIL_PASSWORD --apply

If you edit the file by hand: put values that contain $, #, spaces, quotes or backslashes in single quotes. Compose interpolates $ inside double quotes and unquoted values, and an unquoted # after a space starts a comment. byroctl config check reports such mistakes.

Everyday commands¶

$ byroctl start                  start the stack and wait until byro is healthy
$ byroctl stop                   stop the containers, keep all data
$ byroctl restart                recreate the byro services (not the database)
$ byroctl logs [-f] [web db …]   show (or follow) logs of one or more services
$ byroctl manage <command>       run a byro management command, see below
$ byroctl plugin list|add|remove|update|rebuild   manage plugins (see below)
$ byroctl version                installed release, image digest, running version, plugins
$ byroctl self-update            re-fetch byroctl for the installed release (repair)

Plugins have dedicated pages: Plugins and plugin management; every management command is listed under Management commands.

Environment variables¶

These variables affect byroctl and install.sh themselves, not byro (which is configured through byro.conf), and are not needed for normal operation:

BYRO_ROOT - installation directory, an alternative to byroctl --root DIR.
BYROCTL_WEB_HEALTH_TIMEOUT - seconds start/update/config set --apply wait at most for a healthy web service (default 180).
BYROCTL_OIDC_CLIENT_SECRET - OIDC client secret for byroctl install, if you set up OIDC login right at installation time (see Configuration).
BYROCTL_RAW_BASE, BYROCTL_SOURCE_DIR - alternative source for deployment files and byroctl itself (a registry mirror, or a local deploy/ checkout); for development and testing only, not meant for production use.
BYROCTL_STABLE_URL, BYROCTL_STABLE_FILE - affect only install.sh and replace the URL or local file it resolves the current stable release from (default $BYROCTL_RAW_BASE/stable/stable.env); also development and testing only.

Updates¶

$ byroctl update --check
$ byroctl update

update --check compares the installed release with the current stable one and shows the link to the release notes. update then

switches to the byroctl that belongs to the new release,
writes a pre-update safeguard to backups/: a dump of the database, your byro.conf, your plugins/plugins.txt and the secret key file,
adds new configuration options with their defaults to byro.conf (nothing is removed or reordered),
replaces the Compose files, pulls the new image and pins its digest,
rebuilds the plugin image on top of the new release if you use plugins (with your pins unchanged; --update-plugins moves catalog plugins to their current release in the same run, see plugin management),
stops byro, applies the database migrations and starts the new release.

If a release is flagged as breaking, byroctl asks you to read the release notes and confirm (--yes). If a release changes files in data/, byroctl refuses to continue until you confirm with --data-safeguard-done that you have a full backup of that directory. Downgrades are not supported.

Should a migration fail, the byro services stay stopped and byroctl prints the way back to the previous release, including the location of the safeguard.

More byroctl update options:

--check only reports whether an update is available, changes nothing. Exits 0 if an update is pending, 3 if you already run the current release - useful for scripts and monitoring.
--to TAG updates to a specific release instead of the current stable one.
--prefetch only downloads the target image, changes nothing else.
--skip-safeguard skips the pre-update safeguard copy (not recommended).
--non-interactive never prompts; combine with --yes (and --data-safeguard-done if needed) for unattended updates.
--no-pull uses the target image already present locally (development only).

Note

The pre-update safeguard is not a backup. It contains the database, byro.conf and the secret key, but none of the documents and other files in data/.

Backups¶

Back up these three things regularly, ideally while byro is stopped or with a consistent database dump:

data/ - documents, uploads, GnuPG keys and .secret. Losing .secret invalidates all sessions and all MFA devices.

the database - db/ while the stack is stopped, or a dump:

$ cd /opt/byro && docker compose exec -T db pg_dump -Fc -U byro byro > byro.dump

byro.conf - it contains your passwords, keep the copy private.

Restoring from this backup, and moving to a new host, are described in Backup and restore.

Reverse proxy¶

With BYROCTL_PROXY=caddy byro ships its own reverse proxy. Caddy listens on ports 80 and 443, obtains a certificate from Let's Encrypt for the host in BYRO_SITE_URL and forwards requests to byro.

With your own reverse proxy (BYROCTL_PROXY=own) byro listens on 127.0.0.1:8345 (BYRO_DEPLOY_BIND and BYRO_DEPLOY_PORT). Forward HTTPS traffic there, pass the Host header through and set X-Forwarded-Proto. byroctl sets BYRO_TRUST_PROXY=true in this mode so that byro treats forwarded requests as secure. Never set it when byro is reachable directly, because clients could forge the header.

Troubleshooting¶

byroctl config check validates byro.conf and the Compose files. It also refuses a configuration in which BYRO_OIDC_ADMIN_GROUP and BYRO_OIDC_STAFF_GROUP name different groups, and reminds you that BYRO_OIDC_ADMIN_GROUP is deprecated (see Configuration).
byroctl logs web shows what the web service is doing; byroctl logs db the database.
docker compose ps in the installation directory shows the containers and their health.
A port in use during installation means another service listens there: choose the own proxy mode or another BYRO_DEPLOY_PORT.
byroctl self-update re-fetches byroctl for the installed release if the script was damaged.

Health checks, log locations and more failure modes are covered in Monitoring, logging and troubleshooting.