How to Install Paperless-ngx on an Ubuntu 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.

A popular option is Digital Ocean. Their infrastructure is very reliable, secure, and easy to use. Besides 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.

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.

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.

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:

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

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

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.

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

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

Now, let's switch to the new user:

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

This checks for updates to the installed packages.

For the next steps, you need the created user.

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:

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:

Add the directory to the apt sources:

2. Install Docker packages

To install the latest version, execute this command:

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

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.

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:

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

Simply press ENTER to use the default port 8000.

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

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

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.

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.

Press ENTER to accept the defaults.

Press ENTER to accept the defaults.

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

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.

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.

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

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

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.

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.

You can install Nginx on Ubuntu using apt. First, update your directory index. Then 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:

Now, you can check if Nginx is running.

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:

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.

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:

You can now test your configuration for syntax errors:

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

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

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:

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

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

Next, allow HTTPS traffic with the Nginx Full profile:

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

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

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:

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

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.