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: Oct 3, 2024
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:
This guide explains how to install Paperless-ngx on a virtual private server (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. The result can be seen here:
You can consider under which subdomain you want to deploy Paperless-ngx (e.g., paperless.your-company.com). Alternatively, after installation, you can access the software using the IP address of your 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.
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). 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.
Afterwards, 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.your-company.de) 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:
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 tobias
Output
Adding user `tobias' ...
Adding new group `tobias' (1001) ...
Adding new user `tobias' (1001) with group `tobias' ...
Creating home directory `/home/tobias' ...
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 it blank by pressing ENTER
.
Output
passwd: password updated successfully
Changing the user information for tobias
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 tobias
Output
uid=1001(tobias) gid=1001(tobias) groups=1001(tobias)
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 tobias
Now, let's switch to the new user:
su -l tobias
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.
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.
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.your-company.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, 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/tobias/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/tobias/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. We 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. We 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. We 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 [tobias@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.your-company.com:8000/). Paperless-ngx should start, and you can log in.
Currently, specifying the port is still mandatory. In the next step, we 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.
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.your-company.com
Insert this code block into your file and replace paperless.your-company.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.your-company.com www.paperless.your-company.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
.
Afterwards, 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.your-company.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.
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.your-company.com -d www.paperless.your-company.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.your-company.com/fullchain.pem
Key is saved at: /etc/letsencrypt/live/paperless.your-company.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.your-company.com to /etc/nginx/sites-enabled/paperless.your-company.com
Successfully deployed certificate for www.paperless.your-company.com /etc/nginx/sites-enabled/paperless.your-company.com
Congratulations! You have successfully enabled HTTPS on https://paperless.your-company.com and https://www.paperless.your-company.com
. . .
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 additional users and your workflow.
🛠️ Paperless-ngx IT Support 🛠️
Need help with the installation or configuration of Paperless-ngx? I'm happy to assist! Just send me an email at: info@paperlesszone.com
Keep reading
Discover the latest trends in the automation industry and how they can impact your business.
View moreYour email address won't be published.