How to Install Paperless-Ngx on Ubuntu: 7 Easy Steps

Paperless-ngx is a widely used document management system that helps digitize and organize various types of documents efficiently. With its powerful OCR text recognition, intelligent search features, and advanced document structuring, Paperless-ngx enhances document accessibility and workflow automation. It is a highly recommended tool for businesses, professionals, and individuals looking to streamline document storage and retrieval while maintaining an organized and searchable database.

For those wondering how to install Paperless-ngx on Ubuntu, there are multiple options available depending on the infrastructure and use case:

On Personal Hardware and Infrastructure

This could be a physical server such as a Network Attached Storage (NAS) device or a standalone computer. These setups offer direct control over data security and storage management but may require higher initial costs and maintenance.

On a Cloud-Hosted VPS

A Virtual Private Server (VPS) allows remote access, scalability, and ease of setup. VPS solutions eliminate the need for physical hardware, making them a cost-effective and flexible alternative.

This guide focuses on how to install Paperless-ngx on Ubuntu using a VPS while configuring a subdomain for easy web-based access. This approach provides a cost-effective solution compared to setting up a NAS, which can be more expensive and complex for users who do not have prior experience managing network storage systems.

How to Install Paperless-Ngx on Ubuntu

Step 1: Order and Set Up a VPS

To begin, you need to acquire a VPS. It is recommended to choose a Linux-based server running Ubuntu 20.04 or later. Some providers offer pre-installed Docker, simplifying the setup process. VPS solutions provide reliable uptime, remote management, and an easy way to deploy applications without worrying about hardware maintenance.

A reliable VPS provider such as DigitalOcean offers a user-friendly interface and stable infrastructure. Other options include Linode, Vultr, and AWS Lightsail. New users often receive free credits, making it cost-effective to test Paperless-ngx before committing to long-term usage.

After selecting a VPS plan with a minimum of 2GB RAM and preferably two CPU cores, you will receive an email with your login credentials, including the IP address and root password. It is advisable to use SSH keys for added security instead of relying solely on password authentication.

Step 2: Set Up a Subdomain

Setting up a subdomain is necessary to access Paperless-ngx via a web browser. A subdomain makes it easier to navigate and securely manage document storage without needing to remember an IP address.

1. Create a subdomain: Choose a name like paperless.yourdomain.com to make access more intuitive.
2. Configure DNS settings: Add an A-record pointing to your VPS IP address in your domain provider’s DNS settings.
3. Verify DNS propagation: Use tools like dnschecker.org to confirm DNS updates and ensure proper resolution before proceeding.

Step 3: Log In to the VPS and Create a New User

Access your VPS via SSH using the root credentials:

ssh root@your-server-ip

Create a new user and assign administrative privileges to enhance security:

sudo adduser paperless
sudo usermod -aG sudo paperless

Switch to the new user and update the system to ensure all software packages are up-to-date:

su -l paperless
sudo apt update && sudo apt upgrade -y

Step 4: Install Docker

Check if Docker is already installed:

docker -v

If Docker is not installed, follow these steps to install it properly:

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 Docker repository and install Docker:

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
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Verify installation by running a test container:

sudo docker run hello-world

Step 5: Install Paperless-ngx

Now, it’s time to install Paperless-ngx on your VPS. We will use the official installation script provided by Paperless-ngx. You can check out additional installation options in the Paperless-ngx documentation.

Run the following command to initiate the installation:

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

#############################################
###   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 full address of your subdomain through which you want to access Paperless-ngx:

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

Output

The port on which the paperless webserver will listen for incoming connections.

Port [8000]:

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: Asia/Kolkata
See here for a list: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones

Current time zone []:

Now, specify your time zone. To find a correct identifier for time zone refer to the 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 we need to choose the database. We recommend using PostgreSQL. To go with postgres, simply press ENTER to confirm.

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]:

If you plan to upload Office documents, enable Apache Tika. By default, Paperless-ngx supports permanent file formats like PDFs.

Apache Tika converts Office documents into PDFs for seamless processing. If required, 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 essential for setting the document language, ensuring the OCR search function operates correctly. For instance, to enable English and German, enter “eng+deu”—the exact language code is crucial.

A complete list of language codes is available 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]:

Select the folder where Paperless-ngx should be installed. Press ENTER to use the default location.

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 modify the path of the consume folder. This is where your scanner must place files to ensure proper import.

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 need to specify the storage path for the media folder, where imported documents will be stored.

By default, Docker manages this folder, but it’s recommended to set it to ./media for easier access 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. It’s recommended to set it to ./data for easier access.

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 setting it to ./database for easier access.

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]:

Set a username and password. The email is not required but can be set.

After this, a summary of your configurations will be displayed. Press any key to confirm and start the installation.

Paperless-ngx is now running on port 8000. Open your browser and visit your subdomain with the specified port (e.g., http://paperless.domain.com:8000/). You should see the Paperless-ngx login page.

In the next step, we will configure Paperless-ngx for access without specifying the port.

Follow the prompts, setting the domain URL, time zone, database backend (PostgreSQL recommended), and other preferences for optimized performance.

Step 6: Configure Nginx as a Reverse Proxy

Install Nginx to serve as a reverse proxy and manage HTTP requests efficiently:

sudo apt update
sudo apt install nginx

Allow Nginx in the firewall to permit external access:

sudo ufw allow 'Nginx HTTP'

Create a new Nginx configuration file to handle requests for the subdomain:

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

Add the following configuration to ensure proper routing:

server {
    listen 80;
    server_name 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_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;
    }
}

Enable the configuration and restart Nginx:

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

Step 7: Secure Paperless-ngx with SSL

Install Certbot for SSL certificates:

sudo apt install snapd
sudo snap install --classic certbot
sudo ln -s /snap/bin/certbot /usr/bin/certbot

Obtain an SSL certificate and apply it to the Nginx configuration:

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

Verify auto-renewal to ensure the certificate remains valid:

sudo certbot renew --dry-run

Conclusion

After completing these steps, your Paperless-ngx installation should be accessible securely at https://paperless.domain.com. This guide provides a comprehensive approach for those looking to understand how to install Paperless-ngx on Ubuntu efficiently. With a properly configured setup, users can enjoy seamless document management, automated OCR recognition, and a self-hosted, scalable system tailored to their needs.