Installation

The supported quick-start path is the bella.network APT repository. It installs the executable and a hardened systemd template for running one or more instances.

PassBeyond is also published as an OCI image. Use Container deployment when Docker, Podman, Compose, or a container-based reverse proxy is the better fit.

Install with APT

The repository publishes packages for amd64 and arm64:

curl -fsSL https://repo.bella.network/_static/bella-archive-keyring.gpg \
  | sudo tee /usr/share/keyrings/bella-archive-keyring.gpg >/dev/null

sudo tee /etc/apt/sources.list.d/repo.bella.network.sources >/dev/null <<'EOF'
Types: deb
URIs: https://repo.bella.network/deb
Suites: stable
Components: main
Architectures: amd64 arm64
Signed-By: /usr/share/keyrings/bella-archive-keyring.gpg
EOF

sudo apt update
sudo apt install passbeyond

The repository itself also has a configuration guide.

Installed components

Path	Purpose
/usr/bin/passbeyond	PassBeyond executable
/etc/passbeyond/<instance>.yaml	Static configuration for one instance
/var/lib/passbeyond/	Working directory and recommended location for dynamic state
passbeyond@.service	systemd template unit

The package creates an unprivileged passbeyond user and group. The shipped default.yaml is an example and is intentionally not ready for use.

Run an instance

Each YAML filename maps to one systemd instance. For /etc/passbeyond/wiki.yaml, run:

sudo systemctl enable --now passbeyond@wiki.service

Use a unique domain, listen port, target URL, and dynamic configPath for every instance. Multiple instances must never write to the same dynamic JSON file.

Upgrade

Upgrade through APT and inspect the service logs afterward:

sudo apt update
sudo apt install --only-upgrade passbeyond
sudo systemctl --failed

Back up /etc/passbeyond/ and the dynamic state files in /var/lib/passbeyond/ before an upgrade. The package restarts enabled instances for which it finds a YAML configuration. See Backup and restore for a consistent procedure.

Build from source

Install the Go version required by the repository's go.mod, then clone and test the project:

git clone https://gitlab.com/bella.network/passbeyond.git
cd passbeyond
go mod download
go test ./...
go build -trimpath -o ./bin/passbeyond ./cmd/passbeyond

Run a source build with an explicit configuration file:

./bin/passbeyond --config ./config.yaml

For production, prefer a tagged release and reproduce the package's unprivileged service setup. The application needs write access to its dynamic state file but does not need root privileges or a privileged listening port.

Verify the installation

The executable has no separate version or health command. Verify a configured instance through systemd, its logs, and the public metadata endpoint:

systemctl status passbeyond@wiki.service
journalctl -u passbeyond@wiki.service -n 100 --no-pager
curl --fail --show-error https://wiki.example.com/saml/metadata.xml