How to Install Paperless-ngx on macOS

Paperless-ngx is a web-based document management system that allows users to capture and organize digital documents in a secure and efficient manner. In this tutorial, we will describe how to install Paperless-ngx on macOS.

Prerequisites

Before you begin, make sure you have the following prerequisites:

  • macOS (version 10.10 or newer)
  • Homebrew package manager
  • Python 3.6 or later
  • pip package manager
  • Git

Step 1: Install Homebrew

Homebrew is a package manager that simplifies the installation of software on macOS. To install Homebrew, open the Terminal app and enter the following command:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

This command will download and install Homebrew on your machine.

Step 2: Install Python 3 and pip

Python 3 and pip are required to run Paperless-ngx. To install these packages, run the following command in the Terminal:

brew install python3

This command will install Python 3 and pip on your machine.

Step 3: Install Git

Git is a version control system used to manage the source code of software. Paperless-ngx is hosted on GitHub, so you will need Git to clone the repository. To install Git, enter the following command in the Terminal:

brew install git

This command will install Git on your machine.

Step 4: Clone the Paperless-ngx repository

To clone the Paperless-ngx repository, navigate to the directory where you want to store the source code and enter the following command in the Terminal:

git clone https://github.com/paperless-ng/paperless.git

This command will clone the repository in the current directory.

Step 5: Install Paperless-ngx dependencies

Navigate to the directory where the Paperless-ngx source code was cloned and create a virtual environment using the following command:

cd paperless
python3 -m venv venv

Activate the virtual environment:

source venv/bin/activate

Install the dependencies using the following command:

pip install -r requirements.txt

This command will install all the libraries and dependencies required to run Paperless-ngx.

Step 6: Configure Paperless-ngx

Paperless-ngx requires some basic configuration before it can be run. Set up the configuration file by running the following command:

cp contrib/env-sample .env

Edit the .env file and set the following options:

  • DATABASE_URL: The path to the database file (sqlite:////path/to/your/database/file)
  • SECRET_KEY: A long, secure key for cryptographic operations
  • ALLOWED_HOSTS: A comma-separated list of allowed hostnames or IP addresses

Step 7: Create the database and run the migrations

To create the database and run the migrations, run the following command:

flask db upgrade

This command will create the database tables and populate them with the required data.

Step 8: Start Paperless-ngx

To start Paperless-ngx, navigate to the directory where the source code was cloned and activate the virtual environment:

cd paperless
source venv/bin/activate

Start the server using the following command:

./run.sh

This command will start the server and make Paperless-ngx available at http://localhost:8000/.

Conclusion

In this tutorial, we described how to install Paperless-ngx on macOS. Paperless-ngx is a powerful tool that can help you manage your digital documents in a secure and efficient manner. With Paperless-ngx, you can easily store, organize, and retrieve your documents from anywhere.