PdfDing

Web-based selfhosted PDF manager, viewer and editor

Declared in: projects/PdfDing/default.nix

Try the service in a VM

  1. Install Nix
    Bash
    $ apt install --yes curl git jq nix
    Bash
    $ apt install --yes curl git jq nix
    Bash
    $ pacman --sync --refresh --noconfirm curl git jq nix
  2. Download a configuration file 
    # default.nix
{
  ngipkgs ? import (fetchTarball "https://github.com/ngi-nix/ngipkgs/tarball/main") { },
}:
ngipkgs.demo-vm (
  { pkgs, ... }:
  {
    services.pdfding = {
      enable = true;
      openFirewall = true;
      # NOTE: this is just for demo purposes
      # you shoud not use this in production, use a secret management tool like sops-nix instead.
      # see https://wiki.nixos.org/wiki/Comparison_of_secret_managing_schemes for other alternatives.
      secretKeyFile = pkgs.writeText "django_secret" "foobarbaz";
      consume.enable = true; # allows bulk importing pdf files
      consume.schedule = "*/1 * * * *"; # once every minute
    };
  }
)
    Download
  3. Enable binary substituters
    Bash
    $ export NIX_CONFIG='substituters = https://cache.nixos.org/ https://ngi.cachix.org/
trusted-public-keys = cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY= ngi.cachix.org-1:n+CAL72ROC3qQuLxIHpV+Tw5t42WhXmMhprAGkRSrOw='
  4. Build and run a virtual machine
    Bash
    $ nix-build ./default.nix && ./result
    Bash
    $ nix-build ./default.nix && ./result
    Bash
    $ rev=$(nix-instantiate --eval --attr sources.nixpkgs.rev https://github.com/ngi-nix/ngipkgs/archive/master.tar.gz | jq --raw-output)
    $ nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/$rev.tar.gz --packages nix --run "nix-build ./default.nix && ./result"
    Bash
    $ nix-build ./default.nix && ./result
  5. Usage Instructions

    1. Visit http://127.0.0.1:8000 in your browser

    2. An admin account has already been created inside the demo, so you can sign in with the following credentials:

      • email: admin@localhost
      • password: admin

    3. An example file will be available inside the demo, but it might take a minute for it to appear. You can upload more PDFs, click ➕ icon (top right corner).

      For example:

Options

services.pdfding
services.pdfding.allowedHosts

Domains where PdfDing is allowed to run

Type:
list of string
Default:
[ "127.0.0.1" "localhost" ]
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.backup.enable

Automatic backup of important data to a MinIO instance.

When enabled and properly configured via environment variables, important data is periodically uploaded to the specified MinIO instance via cronjob.

Type:
boolean
Default:
false
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.backup.endpoint

The Minio endpoint for backups

Type:
null or string
Default:
null
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.backup.schedule

The cron schedule for the consume task to trigger. The format is "minute hour day month day_of_week" Read

  • https://github.com/mrmn2/PdfDing/blob/d0f21ec2f9fbee4b1a2f6b7e0e6c7ea7784ab1bc/pdfding/base/task_helpers.py#L5
  • https://huey.readthedocs.io/en/latest/api.html#crontab
Type:
string
Default:
"0 2 * * *"
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.consume.enable

Bulk PDF import from consume directory.

When enabled, administrators can create per-user directories like /var/lib/pdfding/consume/<user_id> with permissions allowing the pdfding user to read and write. PDFs placed in these directories are automatically imported into user accounts.

PDFs are imported periodically via cronjob and successfully imported files are automatically deleted from the consume directory.

Type:
boolean
Default:
false
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.consume.schedule

The cron schedule for the consume task to trigger. The format is "minute hour day month day_of_week" Read

  • https://github.com/mrmn2/PdfDing/blob/d0f21ec2f9fbee4b1a2f6b7e0e6c7ea7784ab1bc/pdfding/base/task_helpers.py#L5
  • https://huey.readthedocs.io/en/latest/api.html#crontab
Type:
string
Default:
"*/5 * * * *"
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.database.createLocally

Whether to create a local PostgreSQL database automatically

Type:
boolean
Default:
false
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.database.host

PostgreSQL host

Type:
string
Default:
""
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.database.name

PostgreSQL database name

Type:
string
Default:
"pdfding"
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.database.passwordFile

File containing POSTGRES_PASSWORD. Consider using a secret managing scheme such as agenix or sops-nix to generate this file.

Type:
null or absolute path
Default:
null
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.database.port

PostgreSQL port

Type:
16 bit unsigned integer; between 0 and 65535 (both inclusive)
Default:
5432
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.database.type

Database type to use

Type:
one of "sqlite", "postgres"
Default:
"sqlite"
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.database.user

PostgreSQL user

Type:
string
Default:
"pdfding"
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.enable

Whether to enable pdfding.

To use the management CLI (pdfding-manage), add your user to the pdfding group: users.users..extraGroups = [ "pdfding" ];

Type:
boolean
Default:
false
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.envFiles

Environment variable files

Type:
list of absolute path
Default:
[ ]
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.extraEnvironment

Additional environment variables

Type:
attribute set of string
Default:
{ CSRF_COOKIE_SECURE = "FALSE"; DEFAULT_THEME = "dark"; DEFAULT_THEME_COLOR = "green"; SESSION_COOKIE_SECURE = "FALSE"; }
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.group

Group under which PdfDing runs

Type:
string
Default:
"pdfding"
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.gunicorn.extraArgs

Command line arguments passed to Gunicorn server.

Type:
list of string
Default:
[ "--workers=4" "--max-requests=1200" "--max-requests-jitter=50" "--log-level=error" ]
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.hostName

Listen adress for PdfDing

Type:
string
Default:
"0.0.0.0"
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.installWrapper

This will add pdfding-manage django admin cli with proper credentials configured to environment.systemPackages

Type:
boolean
Default:
false
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.openFirewall

Open ports in the firewall for the PdfDing web interface.

Type:
boolean
Default:
false
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.package

The pdfding package to use.

Type:
package
Default:
pkgs.pdfding
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.port

Port on which PdfDing listens

Type:
16 bit unsigned integer; between 0 and 65535 (both inclusive)
Default:
8000
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.secretKeyFile

File containing the Django SECRET_KEY. Consider using a secret managing scheme such as agenix or sops-nix to generate this file.

Type:
absolute path
Default:
null
Declared in:
projects/PdfDing/services/pdfding/module.nix
services.pdfding.user

User account under which PdfDing runs

Type:
string
Default:
"pdfding"
Declared in:
projects/PdfDing/services/pdfding/module.nix

Examples

basic 
{ config, ... }:
{
  services.pdfding = {
    enable = true;
    secretKeyFile = config.sops.secrets."pdfding/django/secret_key".path;
  };

  # Secrets management
  # See <https://github.com/Mic92/sops-nix>
  sops = {
    age.keyFile = "/dev/null"; # For a production configuration, set this option.
    defaultSopsFile = "/dev/null"; # For a production configuration, set this option.
    validateSopsFiles = false; # For a production configuration, remove this line.
    secrets."pdfding/django/secret_key" = {
      owner = config.services.pdfding.user;
      group = config.services.pdfding.group;
    };
  };
}

Declared in: projects/PdfDing/services/pdfding/examples/basic.nix

minio 
{ config, ... }:
{
  services.pdfding = {
    enable = true;
    secretKeyFile = config.sops.secrets."pdfding/django/secret_key".path;
    backup.enable = true;
    backup.schedule = "*/1 * * * *";
    backup.endpoint = "127.0.0.1:9000";
    envFiles = [ config.sops.templates."pdfding-minio-keys".path ];
    # adds pdfding-manage django admin executable to path
    installWrapper = true;
  };

  # Setup a local minio service for the backup feature
  services.minio = {
    enable = true;
    rootCredentialsFile = config.sops.templates."minio-creds".path;
    listenAddress = "127.0.0.1:9000";
    consoleAddress = "127.0.0.1:9001";
  };

  # Secrets management
  # See <https://github.com/Mic92/sops-nix>
  sops = {
    age.keyFile = "/dev/null"; # For a production configuration, set this option.
    defaultSopsFile = "/dev/null"; # For a production configuration, set this option.
    validateSopsFiles = false; # For a production configuration, remove this line.

    secrets."pdfding/minio/user" = { };
    secrets."pdfding/minio/password" = { };

    templates."minio-creds" = {
      content = ''
        MINIO_ROOT_USER=${config.sops.placeholder."pdfding/minio/user"}
        MINIO_ROOT_PASSWORD=${config.sops.placeholder."pdfding/minio/password"}
      '';
      owner = "minio";
      group = "minio";
    };

    templates."pdfding-minio-keys" = {
      content = ''
        BACKUP_ACCESS_KEY=${config.sops.placeholder."pdfding/minio/user"}
        BACKUP_SECRET_KEY=${config.sops.placeholder."pdfding/minio/password"}
      '';
      owner = config.services.pdfding.user;
      group = config.services.pdfding.group;
    };

    secrets."pdfding/django/secret_key" = {
      owner = config.services.pdfding.user;
      group = config.services.pdfding.group;
    };
  };
}

Declared in: projects/PdfDing/services/pdfding/examples/minio.nix

postgres 
{ config, ... }:
{
  services.pdfding = {
    enable = true;
    secretKeyFile = config.sops.secrets."pdfding/django/secret_key".path;
    database.createLocally = true;
    database.type = "postgres";
    consume.enable = true; # allows bulk importing pdf files from the backend
    consume.schedule = "*/1 * * * *"; # once every minute
  };

  # Secrets management
  # See <https://github.com/Mic92/sops-nix>
  sops = {
    age.keyFile = "/dev/null"; # For a production configuration, set this option.
    defaultSopsFile = "/dev/null"; # For a production configuration, set this option.
    validateSopsFiles = false; # For a production configuration, remove this line.
    secrets."pdfding/django/secret_key" = {
      owner = config.services.pdfding.user;
      group = config.services.pdfding.group;
    };
  };
}

Declared in: projects/PdfDing/services/pdfding/examples/postgres.nix

Metadata

This project is funded by NLnet through these subgrants:

Commons
PdfDing

Related links: