Pinchflat Service

Defined in /modules/services/pinchflat.nix.

This NixOS module sets up a Pinchflat NGX instance. Read the migration guide before upgrading an existing SHB Pinchflat installation.

Compared to the stock module from nixpkgs, this one sets up, in a fully declarative manner, LDAP and SSO integration and has a nicer option for secrets.

Features

Usage

Initial Configuration

The following snippet assumes a few blocks have been setup already:

shb.pinchflat = {
  enable = true;

  secretKeyBase.result = config.shb.sops.secret."pinchflat/secretKeyBase".result;
  timeZone = "Europe/Brussels";
  mediaDir = "/srv/pinchflat";

  domain = "example.com";
  subdomain = "pinchflat";
  ssl = config.shb.certs.certs.letsencrypt.${domain};

  ldap = {
    enable = true;
  };
  sso = {
    enable = true;
    authEndpoint = "https://${config.shb.authelia.subdomain}.${config.shb.authelia.domain}";
  };
};
shb.sops.secret."pinchflat/secretKeyBase".request = config.shb.pinchflat.secretKeyBase.request;

Secrets can be randomly generated with nix run nixpkgs#openssl -- rand -hex 64.

The user LDAP group is created automatically.

Migrating from original Pinchflat

The module now defaults to Pinchflat NGX. When migrating from original Pinchflat, you can retain the existing media directory, secretKeyBase, domain, and SSO configuration. Existing shb.pinchflat options and the pinchflat.service service name are retained. SQLite remains the default; switching to PostgreSQL or native OIDC is a separate migration.

NGX upgrades the database before displaying its migration review. Take a consistent backup before activating the new NixOS configuration. A NixOS generation rollback alone does not undo database changes; restore the pre-migration application state before starting the old version. See the upstream migration guide and rollback guidance.

On ZFS installations, SHB’s snapshots before activation can provide an additional recovery point. Ensure the configured snapshots include the dataset containing /var/lib/pinchflat and any relevant child datasets. Snapshots are non-recursive by default.

  1. Check that the existing installation is running original Pinchflat 2025.9.26 and has finished its database migrations. NGX requires the original application’s final schema.

  2. Build the new NixOS configuration without activating it. Retain the previous NixOS generation for rollback.

  3. Stop Pinchflat and archive all its application state, including SQLite’s WAL files if present. Store the backup privately because it can contain credentials. The current SHB backup contract covers only mediaDir; it does not include /var/lib/pinchflat unless that directory is separately covered.

    backup_dir="/var/backups/pinchflat/pre-ngx-$(date -u +%Y%m%dT%H%M%SZ)"
    sudo systemctl stop pinchflat.service && \
    sudo install --directory --mode=0700 "$backup_dir" && \
    readlink -f /run/current-system | sudo tee "$backup_dir/system-path" && \
    sudo tar --create --gzip --file="$backup_dir/state.tar.gz" --directory=/var/lib pinchflat && \
    sudo tar --list --gzip --file="$backup_dir/state.tar.gz"
    
  4. Continue only after the archive succeeds and contains pinchflat/db/pinchflat.db. Keep the existing secret available and retain your media backups. Activate the new configuration using your normal deployment procedure, then inspect journalctl --unit=pinchflat.service for startup failures.

  5. Open Pinchflat’s existing URL. Wait for the migration review’s disk scan, compare its source/profile/download totals with the old library, and resolve inaccessible files before selecting Looks good, continue. The scan checks readability and size, not media checksums. Confirmation releases the migration hold, allowing configured download and retention policies to resume; previously disabled sources stay disabled.

To roll back, stop NGX, restore the complete application-state backup, and activate the retained old generation. Preserve the failed migration’s state for investigation instead of extracting over it. In the same shell, with backup_dir still pointing at the archive above:

sudo systemctl stop pinchflat.service && \
restore_dir="$(sudo mktemp --directory /var/lib/pinchflat-rollback.XXXXXX)" && \
sudo tar --extract --gzip --same-owner --file="$backup_dir/state.tar.gz" --directory="$restore_dir" && \
sudo test -f "$restore_dir/pinchflat/db/pinchflat.db" && \
previous_system="$(sudo cat "$backup_dir/system-path")" && \
test -x "$previous_system/bin/switch-to-configuration" && \
sudo mv /var/lib/pinchflat "$restore_dir/after-ngx" && \
sudo mv "$restore_dir/pinchflat" /var/lib/pinchflat && \
sudo "$previous_system/bin/switch-to-configuration" switch

Check systemctl status pinchflat.service and open the old application before resuming normal operation. Keep media paths consistent with the restored database; downloads or deletions performed after confirming the NGX review are not reversed by restoring application state.

Backup

Backing up Pinchflat using the Restic block is done like so:

shb.restic.instances."pinchflat" = {
  request = config.shb.pinchflat.backup;
  settings = {
    enable = true;
  };
};

The name "pinchflat" in the instances can be anything. The config.shb.pinchflat.backup option provides what directories to backup. You can define any number of Restic instances to backup Pinchflat multiple times.

Application Dashboard

Integration with the dashboard contract is provided by the dashboard option.

For example using the Homepage service:

{
  shb.homepage.servicesGroups.Media.services.Pinchflat = {
    sortOrder = 2;
    dashboard.request = config.shb.pinchflat.dashboard.request;
  };
}

Options Reference

shb.pinchflat.enable

Whether to enable the Pinchflat service…

Type: boolean

Default:

false

Example:

true

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.backup

Backup media directory shb.mediaDir.

Type: submodule

Default:

{ }

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.backup.request

Request part of the backup contract.

Options set by the requester module enforcing how to backup files.

Type: submodule

Default: { user = pinchflat; sourceDirectories = [ config.shb.pinchflat.mediaDir ]; excludePatterns = [ ]; hooks.beforeBackup = [ ]; hooks.afterBackup = [ ]; hooks.beforeRestore = [ ]; hooks.afterRestore = [ ]; };

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.backup.request.afterBackup

Hooks to run after a backup.

Type: list of string

Default:

[ ]

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.backup.request.afterRestore

Hooks to run after a restore.

Type: list of string

Default:

[ ]

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.backup.request.beforeBackup

Hooks to run before a backup.

Type: list of string

Default:

[ ]

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.backup.request.beforeRestore

Hooks to run before a restore.

Type: list of string

Default:

[ ]

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.backup.request.excludePatterns

File patterns to exclude.

Type: list of string

Default:

[ ]

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.backup.request.sourceDirectories

Directories to backup.

Type: non-empty (list of string)

Default: [ config.shb.pinchflat.mediaDir ]

Example:

"/var/lib/vaultwarden"

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.backup.request.user

Unix user doing the backups.

Type: string

Default:

"pinchflat"

Example:

"vaultwarden"

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.backup.result

Result part of the backup contract.

Options set by the provider module that indicates the name of the backup and restore scripts.

Type: submodule

Default:

""

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.backup.result.backupService

Name of service backing up the database.

This script can be ran manually to backup the database:

$ systemctl start backup.service

Type: string

Default:

"backup.service"

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.backup.result.restoreScript

Name of script that can restore the database. One can then list snapshots with:

$ restore snapshots
<snapshot 1> <metadata>
<snapshot 2> <metadata>

And restore the database with:

$ restore restore <snapshot 1>

Type: string

Default:

"restore"

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.dashboard

Dashboard contract consumer

Type: submodule

Default:

{ }

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.dashboard.request

Request part of the dashboard contract.

Type: submodule

Default:

{ }

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.dashboard.request.externalUrl

URL at which the service can be accessed.

This URL should go through the reverse proxy.

Type: string

Default:

"http://\${config.shb.pinchflat.subdomain}.\${config.shb.pinchflat.domain}"

Example:

"https://jellyfin.example.com"

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.dashboard.request.internalUrl

URL at which the service can be accessed directly.

This URL should bypass the reverse proxy. It can be used for example to ping the service and making sure it is up and running correctly.

Type: null or string

Default:

"http://127.0.0.1:8945"

Example:

"http://127.0.0.1:8081"

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.dashboard.result

Result part of the dashboard contract.

No option is provided here.

Type: submodule

Default:

{ }

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.domain

domain under which Pinchflat will be served.

Type: string

Example:

"mydomain.com"

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.ldap

Setup LDAP integration.

Type: submodule

Default:

{ }

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.ldap.enable

Whether to enable LDAP integration…

Type: boolean

Default:

false

Example:

true

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.ldap.userGroup

Group users must belong to be able to login.

Type: string

Default:

"pinchflat_user"

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.mediaDir

Path where videos are stored.

Type: string

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.port

Port Pinchflat listens to incoming requests.

Type: 16 bit unsigned integer; between 0 and 65535 (both inclusive)

Default:

8945

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.secretKeyBase

Used to sign/encrypt cookies and other secrets.

Make sure the secret is at least 64 characters long.

Type: submodule

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.secretKeyBase.request

Request part of the secret contract.

Options set by the requester module enforcing some properties the secret should have.

Type: submodule

Default:

""

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.secretKeyBase.request.group

Linux group owning the secret file.

Type: string

Default:

"root"

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.secretKeyBase.request.mode

Mode of the secret file.

Type: string

Default:

"0400"

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.secretKeyBase.request.owner

Linux user owning the secret file.

Type: string

Default:

"root"

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.secretKeyBase.request.restartUnits

Systemd units to restart after the secret is updated.

Type: list of string

Default:

[
  "pinchflat.service"
]

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.secretKeyBase.result

Result part of the secret contract.

Options set by the provider module that indicates where the secret can be found.

Type: submodule

Default:

{
  path = "/run/secrets/secret";
}

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.secretKeyBase.result.path

Path to the file containing the secret generated out of band.

This path will exist after deploying to a target host, it is not available through the nix store.

Type: absolute path

Default:

"/run/secrets/secret"

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.ssl

Path to SSL files

Type: null or (open submodule of anything)

Default:

null

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.ssl.paths

Paths where the files for the certificate will be located.

This option is the contract output of the shb.certs.certs SSL block.

Type: open submodule of anything

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.ssl.paths.cert

Path to the cert file.

Type: absolute path

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.ssl.paths.key

Path to the key file.

Type: absolute path

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.ssl.systemdService

Systemd oneshot service used to generate the certificate. Ends with the .service suffix.

Use this if downstream services must wait for the certificates to be generated before starting.

Type: string

Example:

"cert-generator.service"

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.sso

Setup SSO integration.

Type: submodule

Default:

{ }

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.sso.enable

Whether to enable SSO integration…

Type: boolean

Default:

false

Example:

true

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.sso.authEndpoint

Endpoint to the SSO provider.

Type: string

Example:

"https://authelia.example.com"

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.sso.authorization_policy

Require one factor (password) or two factor (device) authentication.

Type: one of “one_factor”, “two_factor”

Default:

"one_factor"

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.subdomain

Subdomain under which Pinchflat will be served.

Type: string

Default:

"pinchflat"

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>
shb.pinchflat.timeZone

Timezone of this instance.

Type: string or (submodule)

Example:

"America/Los_Angeles"

Declared by:

<selfhostblocks/modules/services/pinchflat.nix>