homefree-documenso

A HomeFree flake plugin that adds Documenso — an open-source DocuSign alternative for digital document signing — as a HomeFree app.

Packaged as a standalone Nix flake so it can be registered through the HomeFree admin panel without forking the HomeFree base repo. You keep receiving upstream HomeFree updates while running Documenso alongside them.

What it adds

Documenso runs as the official documenso/documenso container, backed by HomeFree's system Postgres, reverse-proxied at sign.<your-domain> (and documenso.<your-domain>). Once registered it appears in the admin panel under Services → Documenso with these options:

• enable — turn the service on/off
• public — expose it on the WAN port
• secrets.environment — optional path to an additional env file (typically your NEXT_PRIVATE_SMTP_* block)

Authentication

This plugin runs Documenso with its built-in email/password authentication, not HomeFree's Zitadel SSO.

Documenso v2 has no env knob to disable its email/password login form, and gating it behind Caddy + oauth2-proxy would still leave Documenso unaware of who the user is (it requires its own database session, not a trusted header). Upstream PR documenso/documenso#2857 adds the missing controls — a server-side disable of password sign-in and NEXT_PUBLIC_AUTO_REDIRECT_TO_OIDC — but is unmerged at time of writing. When that ships in a released Documenso version, this plugin can be flipped to native OIDC against Zitadel; the scaffolding (CA-bundle plumbing, OIDC env synthesis) was removed in the interim to keep the deployed config honest.

Users sign up at https://sign.<your-domain>/signup and sign in at /signin with the same credentials.

Auto-generated secrets

On first boot the plugin generates and persists:

• NEXTAUTH_SECRET (session JWT signing — Documenso v2 still reads the env var under its legacy name)
• NEXT_PRIVATE_ENCRYPTION_KEY + _SECONDARY_KEY (at-rest encryption for sensitive Postgres rows)
• NEXT_PRIVATE_SIGNING_PASSPHRASE (PKCS#12 cert passphrase)
• A self-signed PKCS#12 signing certificate (replace by overwriting /var/lib/documenso-podman/certs/cert.p12 with a CA-issued cert protected by the same passphrase)
• The Postgres role's password (rotated into the cluster on every boot)

All of these live in /var/lib/homefree-secrets/documenso/ and that directory is in the plugin's backup.paths, so a HomeFree restore re-materializes the exact same values — critical because rotating NEXT_PRIVATE_ENCRYPTION_KEY would make every existing document unreadable.

How to add it to HomeFree

This plugin is registered through the admin panel — no command line, no editing /etc/nixos by hand.

1. Put this repository on the HomeFree machine (it must be a git repository — a git+file:// flake requires one). Either clone it there, or copy the directory and run git init && git add -A && git commit inside it.
2. Open the HomeFree admin panel and go to Developers → Custom Flakes.
3. Click Add a custom flake and choose the type:
   • Local repository — use the file browser to select this repository's directory on the machine.
   • Remote URL — if you host this repo somewhere, paste its flake reference instead (e.g. github:owner/homefree-documenso).
4. Optionally click Validate to confirm the flake is reachable and exposes a module.
5. Click Register flake.
6. Click Apply Changes in the sidebar to rebuild the system.
7. After the rebuild, open Services, enable Documenso, and Apply Changes again.

To remove it later: delete the entry on the Custom Flakes page and Apply Changes.

SMTP and other overrides

To send signature-request emails Documenso needs SMTP credentials. The plugin doesn't ship a built-in SMTP config — point the secrets → environment option (in the Services page) at an env file outside your source repo containing the NEXT_PRIVATE_SMTP_* variables you want. Same pattern as Linkwarden's secrets.environment. The same file can carry any other NEXT_PRIVATE_* override Documenso supports.

Example:

NEXT_PRIVATE_SMTP_TRANSPORT=smtp-auth
NEXT_PRIVATE_SMTP_HOST=smtp.example.com
NEXT_PRIVATE_SMTP_PORT=587
NEXT_PRIVATE_SMTP_USERNAME=documenso@example.com
NEXT_PRIVATE_SMTP_PASSWORD=...
NEXT_PRIVATE_SMTP_FROM_NAME=Documenso
NEXT_PRIVATE_SMTP_FROM_ADDRESS=documenso@example.com

How it works

flake.nix              # exposes nixosModules.default
apps/documenso/
  default.nix          # the NixOS module — a plain HomeFree app
  icon.svg

flake.nix's nixosModules.default is what HomeFree composes into the system build (the admin panel writes it into /etc/nixos/custom-flakes.nix). apps/documenso/default.nix is an ordinary NixOS module, evaluated with the same config / lib / pkgs as an in-tree HomeFree app — so it declares HomeFree service options, sets up services.postgresql, runs an OCI container as a non-root user (uid 1001, matching upstream's nodejs), and contributes a homefree.service-config entry for reverse proxy, backups, and admin-UI cataloguing.

Two plugin-specific concessions vs. an in-tree HomeFree app:

1. Secrets are written directly to disk under /var/lib/homefree-secrets/documenso/, not through HomeFree's internal lib/secrets-anchor.nix (the plugin tree can't reach that file). The directory is in backup.paths so a restore keeps the same values.
2. No SSO. See the Authentication section above.

Bumping the Documenso version

Edit apps/documenso/default.nix and change version = "v2.11.0"; to the desired Docker Hub tag from documenso/documenso, then Apply Changes from the admin panel. Documenso runs Prisma migrations on container start; check the release notes for any breaking migrations before bumping across multiple minor versions.

Notes

• The self-signed signing cert lets Documenso run out of the box but every signed PDF will report an untrusted signer in viewers that check the chain. Replace /var/lib/documenso-podman/certs/cert.p12 with a CA-issued PKCS#12 protected by the same passphrase (/var/lib/homefree-secrets/documenso/signing-passphrase) to issue publicly-trusted signatures.
• Documenso defaults to storing uploaded PDFs inside Postgres (NEXT_PUBLIC_UPLOAD_TRANSPORT=database). The containerDataPath bind mount is there for any future feature that needs filesystem storage; the daily backup includes both.