selfhostblocks/modules/services/vaultwarden/docs/default.md

Vaultwarden Service

Defined in /modules/services/vaultwarden.nix.

This NixOS module is a service that sets up a Vaultwarden Server.

Features

• Access through subdomain using reverse proxy.
• Access through HTTPS using reverse proxy.
• Automatic setup of Redis database for caching.
• Backup of the data directory through the backup contract.
• Integration Tests
  • Tests /admin can only be accessed when authenticated with SSO.
• Access to advanced options not exposed here thanks to how NixOS modules work.

Usage

Initial Configuration

The following snippet enables Vaultwarden and makes it available under the vaultwarden.example.com endpoint.

shb.vaultwarden = {
  enable = true;
  domain = "example.com";
  subdomain = "vaultwarden";

  port = 8222;

  databasePassword.result = config.shb.sops.secret."vaultwarden/db".result;

  smtp = {
    host = "smtp.eu.mailgun.org";
    port = 587;
    username = "postmaster@mg.${domain}";
    from_address = "authelia@${domain}";
    passwordFile = config.sops.secrets."vaultwarden/smtp".path;
  };
};

shb.sops.secret."vaultwarden/db".request = config.shb.vaultwarden.databasePassword.request;
shb.sops.secret."vaultwarden/smtp".request = config.shb.vaultwarden.smtp.password.request;

This assumes secrets are setup with SOPS as mentioned in the secrets setup section of the manual. Secrets can be randomly generated with nix run nixpkgs#openssl -- rand -hex 64.

The SMTP configuration is needed to invite users to Vaultwarden.

HTTPS

If the shb.ssl block is used (see manual on how to set it up), the instance will be reachable at https://vaultwarden.example.com.

Here is an example with Let's Encrypt certificates, validated using the HTTP method:

shb.certs.certs.letsencrypt."example.com" = {
  domain = "example.com";
  group = "nginx";
  reloadServices = [ "nginx.service" ];
  adminEmail = "myemail@mydomain.com";
};

Then you can tell Vaultwarden to use those certificates.

shb.certs.certs.letsencrypt."example.com".extraDomains = [ "vaultwarden.example.com" ];

shb.forgejo = {
  ssl = config.shb.certs.certs.letsencrypt."example.com";
};

SSO

To protect the /admin endpoint and avoid needing a secret passphrase for it, we can use SSO.

We will use the SSO block provided by Self Host Blocks. Assuming it has been set already, add the following configuration:

shb.vaultwarden.authEndpoint = "https://${config.shb.authelia.subdomain}.${config.shb.authelia.domain}";

Now, go to the LDAP server at https://ldap.example.com, create the vaultwarden_admin group and add a user to that group. When that's done, go back to the Vaultwarden server at https://vaultwarden.example.com/admin and login with that user.

ZFS

Integration with the ZFS block allows to automatically create the relevant datasets.

shb.zfs.datasets."vaultwarden" = config.shb.vaultwarden.mount;
shb.zfs.datasets."postgresql".path = "/var/lib/postgresql";

Backup

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

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

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

Maintenance

No command-line tool is provided to administer Vaultwarden.

Instead, the admin section can be found at the /admin endpoint.

Debug

In case of an issue, check the logs of the vaultwarden.service systemd service.

Enable verbose logging by setting the shb.vaultwarden.debug boolean to true.

Access the database with sudo -u vaultwarden psql.

Options Reference

id-prefix: services-vaultwarden-options-
list-id: selfhostblocks-vaultwarden-options
source: @OPTIONS_JSON@