How to Install Paperless-ngx on an Ubuntu VPS

In this guide, you will learn how to install Paperless-ngx on a Virtual Private Server (VPS) and expose it on a subdomain.

Last updated: Nov 16, 2024

15 mins read

Author

Tobias Wupperfeld

Tobias is a seasoned software engineer and the founder of PaperlessZone.

Topics

Introduction

Paperless-ngx is a popular software for managing and digitizing documents of various types. The tool excels, especially with OCR text recognition, intelligent search functionality, and innovative document structuring.

In conjunction with a suitable scanner, documents can be easily digitized, stored, and retrieved. There are various ways to install Paperless-ngx, such as:

On your own hardware and infrastructure: A physical server like a network attached storage (NAS) or a regular computer
On a cloud hosted server: A shared or dedicated virtual private server (VPS)

This guide explains how to install Paperless-ngx on a VPS and expose it on a subdomain. This allows you to access your archive via the web from any device.

The advantage of using a VPS lies in its cost-effectiveness (you can rent a VPS monthly from various providers). In comparison, a NAS can cost around 600 dollars. A VPS is a good way to start inexpensively and test the Paperless workflow.

We installed Paperless-ngx following this guide. You can test our hosted demo here:

paperless.paperlesszone.com

You can consider under which subdomain you want to deploy Paperless-ngx (e.g., paperless.domain.com). Alternatively, after installation, you can access the software using the IP address of your VPS.

Step 1: Order and Set Up a VPS

First, you need a VPS.

I recommend choosing a Linux server with an Ubuntu version of 20.04 or higher. At some providers, you can select to pre-install Docker so that you won’t have to install this software later.

One of the best VPS providers is Digital Ocean. Their infrastructure is very reliable, secure and easy to use. Besides of that they offer $200 of free credits for new customers. It expires after 60 days which is more than enough time to try out Paperless-ngx or any other setup for free.

Order a so called droplet that has a minimum of 2 GB of RAM and ideally 2 cores or more. Select the data center that is closest to your location for maximum speed.

After ordering a package, you will receive the access details via email. For the installation, you will need the IP address of your VPS and the root password.

Step 2: Set Up a Subdomain

You create a subdomain with your domain provider (usually where your website is hosted, e.g. at namecheap). You can choose any name that precedes your top-level domain (e.g., paperless.your-top-level-domain.com). You will later access the Paperless-ngx installation at this address.

Next, you need to adjust the DNS settings for your domain. The new subdomain must point to the IP address of your VPS. You can find the DNS settings with the provider where you registered your domain.

When accessing the settings, create an A-record with the name of your subdomain (e.g. paperless). In the IP field, enter the IP address of your VPS, which you received during the order.

Afterward, create a second A-record with the syntax www.Your-Subdomain (e.g. www.paperless) and the same IP address as before. This ensures that your domain points to your VPS both with and without entering www. in the browser.

Add an A-record with www for your subdomain

Finally, save the DNS settings. It may take up to 48 hours for the DNS settings to be globally propagated.

You can check if your settings have been adopted on websites like dnschecker. Enter your subdomain in the input field (e.g. paperless.domain.com) and select A-Record.

Your VPS should then be accessible through your browser.

Step 3: Log In to VPS and Create a User

In this step, log in to your VPS and create a new user with admin rights. We will install Paperless-ngx using this user, and we recommend not using the root user.

Open a terminal and log in to your VPS via SSH using the root user. Replace the IP address with the IP of your VPS:

ssh root@185.209.228.63

Afterwards, you will be prompted for a password. Enter the password you chose during the ordering process of your VPS.

root@185.209.228.63's password:

Now, you can create a new user with any name:

sudo adduser demo

Output

Adding user `demo' ...

Adding new group `demo' (1001) ...

Adding new user `demo' (1001) with group `demo' ...

Creating home directory `/home/demo' ...

Copying files from `/etc/skel' ...

New password:

Assign a secure password. After that, you will be asked for information about the user. You can either enter values or leave them blank by pressing ENTER.

Output

passwd: password updated successfully

Changing the user information for demo

Enter the new value, or press ENTER for the default

Full Name []:

Room Number []:

Work Phone []:

Home Phone []:

Other []:

Is the information correct? [Y/n] y

Your new user is now created. If you have done everything correctly, you should see the following output when entering this command:

id demo

Output

uid=1001(demo) gid=1001(demo) groups=1001(demo)

The user currently has default privileges. In the next step, we will give administrative rights to the user so that we can install software:

sudo usermod -a -G sudo demo

Now, let’s switch to the new user:

su -l demo

The following command is now executable; enter the password you chose for the new user earlier:

sudo apt update

This checks for updates to the installed packages.

For the next steps, you need the created user.

Step 4: Install Docker

You can skip this step if you selected Docker during the order of your VPS. You can check if Docker is already installed by entering the following command and getting a version in return:

docker -v

Output

Docker version 24.0.7, build afdd53b

If Docker is not installed, you can refer to the Docker documentation for the essential steps, which we will go through below.

1. Create the Docker apt directory.

Add Docker’s official GPG key:

sudo apt-get update

sudo apt-get install ca-certificates curl gnupg

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

sudo chmod a+r /etc/apt/keyrings/docker.gpg

Add the directory to the apt sources:

echo \

  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \

$(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \

sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update

2. Install Docker packages

To install the latest version, execute this command:

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

3. Verify that Docker has been successfully installed by running the hello-world image:

sudo docker run hello-world

This command downloads a test image and runs it in a container. Once the container is started, a confirmation will be displayed, and then the container will exit.

Step 5: Install Paperless-ngx

Now you are ready to install Paperless-ngx on your VPS. We will use the installation script provided by Paperless-ngx. You can explore additional installation options in the Paperless-ngx documentation.

Execute the following command to start the installation:

bash -c "$(curl --location --silent --show-error https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"

Output

#############################################

### paperless-ngx docker installation ###

#############################################

This script will download, configure and start paperless-ngx.

1. Application configuration

============================

The URL paperless will be available at. This is required if the

installation will be accessible via the web, otherwise can be left blank.

Example: https://paperless.example.com

URL []:

Now, enter the complete address of your subdomain through which you want to access Paperless-ngx:

URL []: https://paperless.domain.com

Output

The port on which the paperless webserver will listen for incoming

connections.

Port [8000]:

Simply press ENTER to use the default port 8000.

Output

Paperless requires you to configure the current time zone correctly.

Otherwise, the dates of your documents may appear off by one day,

depending on where you are on earth.

Example: Europe/Berlin

See here for a list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

Current time zone []:

Here, specify your time zone. You can find the correct identifier on the provided Wikipedia page.

Output

Database backend: PostgreSQL, MariaDB, and SQLite are available. Use PostgreSQL

if unsure. If you're running on a low-power device such as Raspberry

Pi, use SQLite to save resources.

Database backend (postgres sqlite mariadb) [postgres]:

Here, choose a database. We recommend PostgreSQL. For postgres, simply press ENTER.

Output

Paperless is able to use Apache Tika to support Office documents such as

Word, Excel, Powerpoint, and Libreoffice equivalents. This feature

requires more resources due to the required services.

Enable Apache Tika? (yes no) [no]:

In this step, choose whether you want to use Apache Tika. If you plan to upload Office documents to Paperless-ngx later, you should enable this option.

The background is that Paperless-ngx only accepts permanent file formats (such as PDF). Uploading Office documents like Word, Excel, and PowerPoint does not work by default.

Apache Tika reads the documents and creates PDFs that Paperless-ngx can process seamlessly. If you want to enable Apache Tika, type yes.

Output

Specify the default language that most of your documents are written in.

Use ISO 639-2, (T) variant language codes:

https://www.loc.gov/standards/iso639-2/php/code_list.php

Common values: eng (English) deu (German) nld (Dutch) fra (French)

This can be a combination of multiple languages such as deu+eng

OCR language [eng]:

This step is important to set the language of your documents so that the OCR search function works correctly later. For example, if you want to enable English and German, enter eng+deu. The exact country code is crucial.

You can find a list of all country codes at the provided link.

Output

Specify the user id and group id you wish to run paperless as.

Paperless will also change ownership on the data, media and consume

folder to the specified values, so it's a good idea to supply the user id

and group id of your unix user account.

If unsure, leave default.

User ID [501]:

Press ENTER to accept the defaults.

Output

Group ID [20]:

Press ENTER to accept the defaults.

Output

2. Folder configuration

=======================

The target folder is used to store the configuration files of

paperless. You can move this folder around after installing paperless.

You will need this folder whenever you want to start, stop, update or

maintain your paperless instance.

Target folder [/home/demo/paperless-ngx]:

Here, choose the folder where Paperless-ngx should be installed. Press ENTER to accept the defaults.

Output

The consume folder is where paperless will search for new documents.

Point this to a folder where your scanner is able to put your scanned

documents.

CAUTION: You must specify an absolute path starting with / or a relative

path starting with ./ here. Examples:

/mnt/consume

./consume

Consume folder [/home/demo/paperless-ngx/consume]:

In this step, you can change the path of the consume folder. This is the folder where your scanner must place the files for the import to work correctly.

Output

The media folder is where paperless stores your documents.

Leave empty and docker will manage this folder for you.

Docker usually stores managed folders in /var/lib/docker/volumes.

CAUTION: If specified, you must specify an absolute path starting with /

or a relative path starting with ./ here.

Media folder []:

In this step, you will be asked for the storage path of the media folder. This folder is where your imported documents will be stored.

By default, Docker manages this folder. I recommend setting it to ./media so that you can easily access it later.

Output

The data folder is where paperless stores other data, such as your

search index and other data.

As with the media folder, leave empty to have this managed by docker.

CAUTION: If specified, you must specify an absolute path starting with /

or a relative path starting with ./ here.

Data folder []:

The same applies to the data folder. I recommend setting it to ./data.

Output

The database folder, where your database stores its data.

Leave empty to have this managed by docker.

CAUTION: If specified, you must specify an absolute path starting with /

or a relative path starting with ./ here.

Database folder []:

The same recommendation applies to the database folder. I suggest specifying ./database here.

Output

3. Login credentials

====================

Specify initial login credentials. You can change these later.

A mail address is required, however it is not used in paperless. You don't

need to provide an actual mail address.

Paperless username [tobias]:

Paperless password:

Paperless password (again):

Email [demo@localhost]:

Now, set a username and password. You will need this for the login. A valid email address is not necessary but can be set.

Afterward, you will see a summary of your initial configurations. Press any key to confirm the configuration and install Paperless-ngx.

Paperless-ngx is now running on port 8000. Open your browser and navigate to your subdomain specifying the port (e.g. http://paperless.domain.com:8000/). Paperless-ngx should start, and you can log in.

Currently, specifying the port is still mandatory. In the next step, I will show you how to access Paperless-ngx without specifying the port.

Step 6: Configure Nginx as a Reverse Proxy

A reverse proxy is the recommended method for making an application server accessible on the internet. Nginx is a popular web server and a widely used reverse proxy solution.

1. Install Nginx

You can install Nginx on Ubuntu using apt. First, update your directory index. Then install Nginx:

sudo apt update

sudo apt install nginx

Press Y to proceed with the installation. If asked whether to restart the service, press ENTER to accept the defaults.

You need to grant access to Nginx in your firewall. To do this, add the following rule:

sudo ufw allow 'Nginx HTTP'

Now, you can check if Nginx is running.

systemctl status nginx

Output

● nginx.service - A high performance web server and a reverse proxy server

Loaded: loaded (/lib/systemd/system/nginx.service; enabled; vendor preset: enabled)

Active: active (running) since Tue 2024-01-25 06:52:46 UTC; 39min ago

Docs: man:nginx(8)

Main PID: 9919 (nginx)

Tasks: 2 (limit: 2327)

Memory: 2.9M

CPU: 50ms

CGroup: /system.slice/nginx.service

├─9919 "nginx: master process /usr/sbin/nginx -g daemon on; master_process on;"

└─9920 "nginx: worker process

2. Configure Server Block

It is recommended to create a separate configuration file instead of directly editing the default configuration. Create and open a new Nginx configuration using nano or any other text editor:

sudo nano /etc/nginx/sites-available/paperless.domain.com

Insert this code block into your file and replace paperless.domain.com with your domain. client_max_body_size defines the maximum file size you can upload. Modify the value if you want to upload larger files to Paperless. The parameters after proxy_pass are necessary for websockets to work in Paperless.

client_max_body_size 10M;

server {

listen 80;

listen [::]:80;

server_name paperless.domain.com www.paperless.domain.com;

location / {

proxy_pass http://localhost:8000;

proxy_http_version 1.1;

proxy_set_header Upgrade $http_upgrade;

proxy_set_header Connection "upgrade";

proxy_redirect off;

proxy_set_header Host $host;

proxy_set_header X-Real-IP $remote_addr;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_set_header X-Forwarded-Host $server_name;

}

Save and exit nano by pressing CTRL+X. Then confirm with Y and press ENTER.

Afterward, activate the configuration. Create a link from the configuration to the sites-enabled directory, which Nginx reads during startup:

sudo ln -s /etc/nginx/sites-available/paperless.domain.com /etc/nginx/sites-enabled/

You can now test your configuration for syntax errors:

sudo nginx -t

If no issues are reported, restart Nginx to apply the changes:

sudo systemctl restart nginx

Nginx is now configured as a reverse proxy for your application server. You can access Paperless-ngx through the browser without specifying the port.

Step 7: Secure Paperless-ngx With a SSL Certificate

You may have noticed that when accessing your domain, it starts with http:// instead of https://. This represents an insecure connection.

First, install snap on Ubuntu:

sudo apt install snapd

Secure your application with Let’s Encrypt by entering the following command:

sudo snap install --classic certbot

Link the certbot command from the snap installation directory to your path, so you can run certbot directly:

sudo ln -s /snap/bin/certbot /usr/bin/certbot

Next, allow HTTPS traffic with the Nginx Full profile:

sudo ufw allow 'Nginx Full'

Delete the Nginx HTTP profile, which we no longer need:

sudo ufw delete allow 'Nginx HTTP'

Now, use certbot with your domain name to obtain the certificate:

sudo certbot --nginx -d paperless.domain.com -d www.paperless.domain.com

You will be prompted to enter an email address and agree to the Terms of Service. You can also decide whether to subscribe to an email list or not. Afterwards, you will receive a message stating that the process was successful, and the certificate has been issued:

Output

. . .

Successfully received certificate.

Certificate is saved at: /etc/letsencrypt/live/paperless.domain.com/fullchain.pem

Key is saved at: /etc/letsencrypt/live/paperless.domain.com/privkey.pem

This certificate expires on 2024-04-01.

These files will be updated when the certificate renews.

Certbot has set up a scheduled task to automatically renew this certificate in the background.

Deploying certificate

Successfully deployed certificate for paperless.domain.com to /etc/nginx/sites-enabled/paperless.domain.com

Successfully deployed certificate for www.paperless.domain.com /etc/nginx/sites-enabled/paperless.domain.com

Congratulations! You have successfully enabled HTTPS on https://paperless.domain.com and https://www.paperless.domain.com

. . .

Navigate to your domain. You will be automatically redirected to https://.

Paperless-ngx is secured by TSL certificate and running under HTTPS

Conclusion

In this guide, you have set up your VPS, configured a subdomain pointing to your VPS, created a user, installed Docker and Paperless-ngx. Finally, you configured Nginx as a reverse proxy and secured your domain with an SSL certificate.

Paperless-ngx should now be accessible via your subdomain and automatically redirect to https. You can now close the terminal. In the event of a server restart, Docker will automatically restart Paperless-ngx.

Log in and continue setting up your workflow. If you want to add another layer of protection, check out my article about setting up a two-factor authentication for Paperless-ngx.