paradizelost/paperless-ngx
1
0
Fork 0
mirror of https://github.com/paperless-ngx/paperless-ngx.git synced 2025-03-31 13:35:08 -05:00
Code Issues Packages Projects Releases Wiki Activity

Documentation: documentation updates

Browse Source
This commit is contained in:
shamoon 2024-11-24 14:20:20 -08:00
parent ceb834bdef
commit fcf532f13e
3 changed files with 60 additions and 115 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -55,7 +55,7 @@ A full list of [features](https://docs.paperless-ngx.com/#features) and [screens
# Getting started # Getting started
The easiest way to deploy paperless is `docker compose`. The files in the [`/docker/compose` directory](https://github.com/paperless-ngx/paperless-ngx/tree/main/docker/compose) are configured to pull the image from GitHub Packages. The easiest way to deploy paperless is `docker compose`. The files in the [`/docker/compose` directory](https://github.com/paperless-ngx/paperless-ngx/tree/main/docker/compose) are configured to pull the image from the GitHub container registry.
If you'd like to jump right in, you can configure a `docker compose` environment with our install script: If you'd like to jump right in, you can configure a `docker compose` environment with our install script:

37
docker/compose/docker-compose.env
View File

@ -1,26 +1,17 @@
###############################################################################
# Paperless-ngx settings #
###############################################################################
# See http://docs.paperless-ngx.com/configuration/ for all available options.
# The UID and GID of the user used to run paperless in the container. Set this # The UID and GID of the user used to run paperless in the container. Set this
# to your UID and GID on the host so that you have write access to the # to your UID and GID on the host so that you have write access to the
# consumption directory. # consumption directory.
#USERMAP_UID=1000 #USERMAP_UID=1000
#USERMAP_GID=1000 #USERMAP_GID=1000
# Additional languages to install for text recognition, separated by a # See the documentation linked above for all options. A few commonly adjusted settings
# whitespace. Note that this is # are provided below.
# different from PAPERLESS_OCR_LANGUAGE (default=eng), which defines the
# language used for OCR.
# The container installs English, German, Italian, Spanish and French by
# default.
# See https://packages.debian.org/search?keywords=tesseract-ocr-&searchon=names&suite=buster
# for available languages.
#PAPERLESS_OCR_LANGUAGES=tur ces
###############################################################################
# Paperless-specific settings #
###############################################################################
# All settings defined in the paperless.conf.example can be used here. The
# Docker setup does not use the configuration file.
# A few commonly adjusted settings are provided below.
# This is required if you will be exposing Paperless-ngx on a public domain # This is required if you will be exposing Paperless-ngx on a public domain
# (if doing so please consider security measures such as reverse proxy) # (if doing so please consider security measures such as reverse proxy)
@ -30,13 +21,17 @@
# be a very long sequence of random characters. You don't need to remember it. # be a very long sequence of random characters. You don't need to remember it.
#PAPERLESS_SECRET_KEY=change-me #PAPERLESS_SECRET_KEY=change-me
# Use this variable to set a timezone for the Paperless Docker containers. If not specified, defaults to UTC. # Use this variable to set a timezone for the Paperless Docker containers. Defaults to UTC.
#PAPERLESS_TIME_ZONE=America/Los_Angeles #PAPERLESS_TIME_ZONE=America/Los_Angeles
# The default language to use for OCR. Set this to the language most of your # The default language to use for OCR. Set this to the language most of your
# documents are written in. # documents are written in.
#PAPERLESS_OCR_LANGUAGE=eng #PAPERLESS_OCR_LANGUAGE=eng
# Set if accessing paperless via a domain subpath e.g. https://domain.com/PATHPREFIX and using a reverse-proxy like traefik or nginx # Additional languages to install for text recognition, separated by a whitespace.
#PAPERLESS_FORCE_SCRIPT_NAME=/PATHPREFIX # Note that this is different from PAPERLESS_OCR_LANGUAGE (default=eng), which defines
#PAPERLESS_STATIC_URL=/PATHPREFIX/static/ # trailing slash required # the language used for OCR.
# The container installs English, German, Italian, Spanish and French by default.
# See https://packages.debian.org/search?keywords=tesseract-ocr-&searchon=names&suite=buster
# for available languages.
#PAPERLESS_OCR_LANGUAGES=tur ces

136
docs/setup.md
View File

@ -2,10 +2,10 @@
You can go multiple routes to setup and run Paperless: You can go multiple routes to setup and run Paperless:
- [Use the easy install docker script](#docker_script) - [Use the script to setup a Docker install](#docker_script)
- [Pull the image from Docker Hub](#docker_hub) - [Use the Docker compose templates](#docker)
- [Build the Docker image yourself](#docker_build) - [Build the Docker image yourself](#docker_build)
- [Install Paperless directly on your system manually (bare metal)](#bare_metal) - [Install Paperless-ngx directly on your system manually ("bare metal")](#bare_metal)
- A user-maintained list of commercial hosting providers can be found [in the wiki](https://github.com/paperless-ngx/paperless-ngx/wiki/Related-Projects) - A user-maintained list of commercial hosting providers can be found [in the wiki](https://github.com/paperless-ngx/paperless-ngx/wiki/Related-Projects)
The Docker routes are quick & easy. These are the recommended routes. The Docker routes are quick & easy. These are the recommended routes.
@ -18,19 +18,14 @@ The bare metal route is complicated to setup but makes it easier should
you want to contribute some code back. You need to configure and run the you want to contribute some code back. You need to configure and run the
above mentioned components yourself. above mentioned components yourself.
### Docker using the Installation Script {#docker_script} ### Use the Installation Script {#docker_script}
Paperless provides an interactive installation script. This script will Paperless provides an interactive installation script to setup a Docker Compose
ask you for a couple configuration options, download and create the installation. The script asks for a couple configuration options, and will then create the
necessary configuration files, pull the docker image, start paperless necessary configuration files, pull the docker image, start Paperless-ngx and create your superuser
and create your user account. This script essentially performs all the account. The script essentially automatically performs the steps described in [Docker setup](#docker).
steps described in [Docker setup](#docker_hub) automatically.
1. Make sure that Docker and Docker Compose are installed. 1. Make sure that Docker and Docker Compose are [installed](https://docs.docker.com/engine/install/){:target="\_blank"}.
!!! tip
See the Docker installation instructions at https://docs.docker.com/engine/install/
2. Download and run the installation script: 2. Download and run the installation script:
@ -43,83 +38,46 @@ steps described in [Docker setup](#docker_hub) automatically.
macOS users will need to install e.g. [gnu-sed](https://formulae.brew.sh/formula/gnu-sed) with support macOS users will need to install e.g. [gnu-sed](https://formulae.brew.sh/formula/gnu-sed) with support
for running as `sed`. for running as `sed`.
### From GHCR / Docker Hub {#docker_hub} ### Use Docker Compose {#docker}
1. Login with your user and create a folder in your home-directory to have a place for your 1. Make sure that Docker and Docker Compose are [installed](https://docs.docker.com/engine/install/){:target="\_blank"}.
configuration files and consumption directory.
```shell-session
$ mkdir -v ~/paperless-ngx
```
2. Go to the [/docker/compose directory on the project 2. Go to the [/docker/compose directory on the project
page](https://github.com/paperless-ngx/paperless-ngx/tree/main/docker/compose) page](https://github.com/paperless-ngx/paperless-ngx/tree/main/docker/compose){:target="\_blank"}
and download one of the `docker-compose.*.yml` files, and download one of the `docker-compose.*.yml` files, depending on which database backend
depending on which database backend you want to use. Rename this you want to use. Place the files in a local directory and rename it `docker-compose.yml`. Download the
file to `docker-compose.yml`. If you want to enable `docker-compose.env` file and the `.env` file as well in the same directory.
optional support for Office documents, download a file with
`-tika` in the file name. Download the If you want to enable optional support for Office and other documents, download a
`docker-compose.env` file and the `.env` file as well and store them file with `-tika` in the file name.
in the same directory.
!!! tip !!! tip
For new installations, it is recommended to use PostgreSQL as the For new installations, it is recommended to use PostgreSQL as the
database backend. database backend.
3. Install [Docker](https://docs.docker.com/engine/install/) and 3. Modify `docker-compose.yml` as needed. For example, you may want to change the paths to the
[Docker Compose](https://docs.docker.com/compose/install/). consumption, media etc. directories to use 'bind mounts'.
Find the line that specifies where to mount the directory, e.g.:
!!! warning
If you want to use the included `docker-compose.*.yml` file, you
need to have at least Docker version **17.09.0** and Docker Compose
version **v2**. To check do: `docker compose version` or `docker -v`
See the [Docker installation guide](https://docs.docker.com/engine/install/) on how to install the current
version of Docker for your operating system or Linux distribution of
choice. To get the latest version of Docker Compose, follow the
[Docker Compose installation guide](https://docs.docker.com/compose/install/linux/) if your package repository
doesn't include it.
4. Modify `docker-compose.yml` to your preferences. You may want to
change the path to the consumption directory. Find the line that
specifies where to mount the consumption directory:
```yaml ```yaml
- ./consume:/usr/src/paperless/consume - ./consume:/usr/src/paperless/consume
``` ```
Replace the part BEFORE the colon with a local directory of your Replace the part _before_ the colon with a local directory of your choice:
choice:
```yaml ```yaml
- /home/jonaswinkler/paperless-inbox:/usr/src/paperless/consume - /home/jonaswinkler/paperless-inbox:/usr/src/paperless/consume
``` ```
Don't change the part after the colon or paperless won't find your You may also want to change the default port that the webserver will
documents. use from the default (8000) to something else, e.g. for port 8010:
You may also need to change the default port that the webserver will
use from the default (8000):
```yaml
ports:
- 8000:8000
```
Replace the part BEFORE the colon with a port of your choice:
```yaml ```yaml
ports: ports:
- 8010:8000 - 8010:8000
``` ```
Don't change the part after the colon or edit other lines that
refer to port 8000. Modifying the part before the colon will map
requests on another port to the webserver running on the default
port.
**Rootless** **Rootless**
!!! warning !!! warning
@ -143,21 +101,16 @@ steps described in [Docker setup](#docker_hub) automatically.
> user: <user_id> > user: <user_id>
> ``` > ```
5. Modify `docker-compose.env`, following the comments in the file. The 4. Modify `docker-compose.env` with any configuration options you'd like.
most important change is to set `USERMAP_UID` and `USERMAP_GID` to See the [configuration documentation](configuration.md) for all options.
the uid and gid of your user on the host system. Use `id -u` and
`id -g` to get these.
This ensures that both the docker container and you on the host You may also need to set `USERMAP_UID` and `USERMAP_GID` to
machine have write access to the consumption directory. If your UID the uid and gid of your user on the host system. Use `id -u` and
`id -g` to get these. This ensures that both the container and the host
user have write access to the consumption directory. If your UID
and GID on the host system is 1000 (the default for the first normal and GID on the host system is 1000 (the default for the first normal
user on most systems), it will work out of the box without any user on most systems), it will work out of the box without any
modifications. `id "username"` to check. modifications. Run `id "username"` to check.
!!! note
You can copy any setting from the file `paperless.conf.example` and
paste it here. Have a look at [configuration](configuration.md) to see what's available.
!!! note !!! note
@ -174,9 +127,11 @@ steps described in [Docker setup](#docker_hub) automatically.
[`PAPERLESS_CONSUMER_POLLING`](configuration.md#PAPERLESS_CONSUMER_POLLING), which will disable inotify. See [`PAPERLESS_CONSUMER_POLLING`](configuration.md#PAPERLESS_CONSUMER_POLLING), which will disable inotify. See
[here](configuration.md#polling). [here](configuration.md#polling).
6. Run `docker compose pull`. This will pull the image. 5. Run `docker compose pull`. This will pull the image from the GitHub container registry
by default but you can change the image to pull from Docker Hub by changing the `image`
line to `image: paperless-ngx/paperless-ngx:latest`.
7. To be able to login, you will need a super user. To create it, 6. To be able to login, you will need a "superuser". To create it,
execute the following command: execute the following command:
```shell-session ```shell-session
@ -189,18 +144,13 @@ steps described in [Docker setup](#docker_hub) automatically.
$ python3 manage.py createsuperuser $ python3 manage.py createsuperuser
``` ```
This will prompt you to set a username, an optional e-mail address This will guide you through the superuser setup.
and finally a password (at least 8 characters).
8. Run `docker compose up -d`. This will create and start the necessary containers. 7. Run `docker compose up -d`. This will create and start the necessary containers.
9. The default `docker-compose.yml` exports the webserver on your local 8. Congratulations! Your Paperless-ngx instance should now be accessible at `http://127.0.0.1:8000`
port (or similar, depending on your configuration). Use the superuser credentials you have
created in the previous step to login.
8000\. If you did not change this, you should now be able to visit
your Paperless instance at `http://127.0.0.1:8000` or your servers
IP-Address:8000. Use the login credentials you have created with the
previous step.
### Build the Docker image yourself {#docker_build} ### Build the Docker image yourself {#docker_build}
@ -234,8 +184,8 @@ steps described in [Docker setup](#docker_hub) automatically.
context: . context: .
``` ```
4. Follow steps 3 to 8 of [Docker Setup](#docker_hub). When asked to run 4. Follow the [Docker setup](#docker) above except when asked to run
`docker compose pull` to pull the image, do `docker compose pull` to pull the image, run
```shell-session ```shell-session
$ docker compose build $ docker compose build
@ -643,7 +593,7 @@ Migration to paperless-ngx is then performed in a few simple steps:
after you migrated your existing SQLite database. after you migrated your existing SQLite database.
5. Adjust `docker-compose.yml` and `docker-compose.env` to your needs. 5. Adjust `docker-compose.yml` and `docker-compose.env` to your needs.
See [Docker setup](#docker_hub) details on See [Docker setup](#docker) details on
which edits are advised. which edits are advised.
6. [Update paperless.](administration.md#updating) 6. [Update paperless.](administration.md#updating)