Documentation

Bootstrap the first administrator

peryx bootstrap-administrator creates the first local administrator in a data directory. Run it before peryx serve. The command opens the metadata store and exits after the transaction; it does not bind a socket or start scheduled jobs.

The password must contain 15 to 1,024 Unicode characters. Peryx accepts spaces and other Unicode characters without composition rules, following the OWASP authentication guidance. Secret input has a 1 MiB byte limit and must use UTF-8. Peryx removes one terminal LF or CRLF from standard input and secret files; it preserves every other character.

First start

Read the password without placing it in shell history or the process arguments:

$ peryx init --data-dir /var/lib/peryx
$ read -rs PERYX_BOOTSTRAP_PASSWORD
$ printf '%s\n' "$PERYX_BOOTSTRAP_PASSWORD" | peryx bootstrap-administrator admin --data-dir /var/lib/peryx --password-stdin
$ unset PERYX_BOOTSTRAP_PASSWORD
administrator	usr_...	admin
$ peryx serve --data-dir /var/lib/peryx

The shell variable stays local unless the operator exported it. The peryx process receives the password through standard input, so tools that inspect process arguments cannot read it.

Secret file

Create the file with access limited to the account that runs peryx, then pass its path:

$ install -m 600 /dev/null /run/peryx-administrator-password
$ read -rs PERYX_BOOTSTRAP_PASSWORD
$ printf '%s\n' "$PERYX_BOOTSTRAP_PASSWORD" > /run/peryx-administrator-password
$ unset PERYX_BOOTSTRAP_PASSWORD
$ peryx bootstrap-administrator admin --data-dir /var/lib/peryx --password-file /run/peryx-administrator-password
$ rm /run/peryx-administrator-password

Peryx reads the file once. The lifecycle record contains the stable user ID, and the security event identifies the bootstrap action. Both exclude credential material and the source path.

systemd credentials

systemd credentials expose secrets as files under $CREDENTIALS_DIRECTORY without passing their contents through the process environment. A one-shot unit can load the password and bootstrap the same data directory used by the service:

[Unit]
Description=Create the first peryx administrator
Before=peryx.service

[Service]
Type=oneshot
User=peryx
LoadCredential=administrator-password:/etc/peryx/administrator-password
ExecStart=/usr/bin/peryx bootstrap-administrator admin --data-dir /var/lib/peryx --password-file %d/administrator-password

Run the unit once, confirm it succeeded, then remove its LoadCredential= source. A second run fails after the first administrator grant commits.

Container first start

Mount the data volume and secret into a short-lived container before starting the long-running container. Replace your-peryx-image:tag with the image that contains the installed peryx binary.

$ docker run --rm \
    --volume peryx-data:/var/lib/peryx \
    --volume "$PWD/administrator-password:/run/secrets/peryx-administrator-password:ro" \
    your-peryx-image:tag \
    peryx bootstrap-administrator admin \
      --data-dir /var/lib/peryx \
      --password-file /run/secrets/peryx-administrator-password
$ docker run --rm --volume peryx-data:/var/lib/peryx your-peryx-image:tag peryx serve --data-dir /var/lib/peryx

Keep the secret outside the image and remove the host copy after bootstrap.

Refusal and recovery

The metadata transaction checks for an administrator grant before writing. It creates the user, Argon2id verifier, server administrator grant, and lifecycle record in one commit. Concurrent commands serialize on the metadata writer, so one command commits and the other reports that an administrator grant exists. A failed write leaves none of those records.

The command stops working while any administrator grant exists. This prevents local bootstrap from becoming a second administrator-creation path after setup; use an authenticated management operation for later accounts and grants.

A lost password does not reopen bootstrap because the administrator grant remains. Use another authenticated administrator to replace the verifier, or restore a protected metadata backup. If recovery leaves the store with no administrator grant, run the same secret-file command against that recovered data directory before restarting the server:

$ peryx bootstrap-administrator recovery-admin \
    --data-dir /srv/peryx-recovered \
    --password-file /run/secrets/peryx-recovery-password

Create at least two administrator accounts through authenticated management. An operator with write access to the metadata directory controls local identity state, so restrict the directory and bootstrap secret to the service account.

On this page