diff --git a/README.md b/README.md index de4efa0cd..8ebfddff2 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ A full list of [features](https://docs.paperless-ngx.com/#features) and [screens # 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: diff --git a/docker/compose/docker-compose.env b/docker/compose/docker-compose.env index c4dbb4cce..7563ec069 100644 --- a/docker/compose/docker-compose.env +++ b/docker/compose/docker-compose.env @@ -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 # to your UID and GID on the host so that you have write access to the # consumption directory. #USERMAP_UID=1000 #USERMAP_GID=1000 -# Additional languages to install for text recognition, separated by a -# whitespace. Note that this is -# 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. +# See the documentation linked above for all options. A few commonly adjusted settings +# are provided below. # 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) @@ -30,13 +21,17 @@ # be a very long sequence of random characters. You don't need to remember it. #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 # The default language to use for OCR. Set this to the language most of your # documents are written in. #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 -#PAPERLESS_FORCE_SCRIPT_NAME=/PATHPREFIX -#PAPERLESS_STATIC_URL=/PATHPREFIX/static/ # trailing slash required +# Additional languages to install for text recognition, separated by a whitespace. +# Note that this is 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 diff --git a/docs/setup.md b/docs/setup.md index 25e977130..b16221353 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -2,10 +2,10 @@ You can go multiple routes to setup and run Paperless: -- [Use the easy install docker script](#docker_script) -- [Pull the image from Docker Hub](#docker_hub) +- [Use the script to setup a Docker install](#docker_script) +- [Use the Docker compose templates](#docker) - [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) 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 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 -ask you for a couple configuration options, download and create the -necessary configuration files, pull the docker image, start paperless -and create your user account. This script essentially performs all the -steps described in [Docker setup](#docker_hub) automatically. +Paperless provides an interactive installation script to setup a Docker Compose +installation. The script asks for a couple configuration options, and will then create the +necessary configuration files, pull the docker image, start Paperless-ngx and create your superuser +account. The script essentially automatically performs the steps described in [Docker setup](#docker). -1. Make sure that Docker and Docker Compose are installed. - - !!! tip - - See the Docker installation instructions at https://docs.docker.com/engine/install/ +1. Make sure that Docker and Docker Compose are [installed](https://docs.docker.com/engine/install/){:target="\_blank"}. 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 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 - configuration files and consumption directory. - - ```shell-session - $ mkdir -v ~/paperless-ngx - ``` +1. Make sure that Docker and Docker Compose are [installed](https://docs.docker.com/engine/install/){:target="\_blank"}. 2. Go to the [/docker/compose directory on the project - page](https://github.com/paperless-ngx/paperless-ngx/tree/main/docker/compose) - and download one of the `docker-compose.*.yml` files, - depending on which database backend you want to use. Rename this - file to `docker-compose.yml`. If you want to enable - optional support for Office documents, download a file with - `-tika` in the file name. Download the - `docker-compose.env` file and the `.env` file as well and store them - in the same directory. + page](https://github.com/paperless-ngx/paperless-ngx/tree/main/docker/compose){:target="\_blank"} + and download one of the `docker-compose.*.yml` files, depending on which database backend + you want to use. Place the files in a local directory and rename it `docker-compose.yml`. Download the + `docker-compose.env` file and the `.env` file as well in the same directory. + + If you want to enable optional support for Office and other documents, download a + file with `-tika` in the file name. !!! tip For new installations, it is recommended to use PostgreSQL as the database backend. -3. Install [Docker](https://docs.docker.com/engine/install/) and - [Docker Compose](https://docs.docker.com/compose/install/). - - !!! 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: +3. Modify `docker-compose.yml` as needed. For example, you may want to change the paths to the + consumption, media etc. directories to use 'bind mounts'. + Find the line that specifies where to mount the directory, e.g.: ```yaml - ./consume:/usr/src/paperless/consume ``` - Replace the part BEFORE the colon with a local directory of your - choice: + Replace the part _before_ the colon with a local directory of your choice: ```yaml - /home/jonaswinkler/paperless-inbox:/usr/src/paperless/consume ``` - Don't change the part after the colon or paperless won't find your - documents. - - 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: + You may also want to change the default port that the webserver will + use from the default (8000) to something else, e.g. for port 8010: ```yaml ports: - 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** !!! warning @@ -143,21 +101,16 @@ steps described in [Docker setup](#docker_hub) automatically. > user: > ``` -5. Modify `docker-compose.env`, following the comments in the file. The - most important change is to set `USERMAP_UID` and `USERMAP_GID` to - the uid and gid of your user on the host system. Use `id -u` and - `id -g` to get these. +4. Modify `docker-compose.env` with any configuration options you'd like. + See the [configuration documentation](configuration.md) for all options. - This ensures that both the docker container and you on the host - machine have write access to the consumption directory. If your UID + You may also need to set `USERMAP_UID` and `USERMAP_GID` to + 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 user on most systems), it will work out of the box without any - modifications. `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. + modifications. Run `id "username"` to check. !!! 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 [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: ```shell-session @@ -189,18 +144,13 @@ steps described in [Docker setup](#docker_hub) automatically. $ python3 manage.py createsuperuser ``` - This will prompt you to set a username, an optional e-mail address - and finally a password (at least 8 characters). + This will guide you through the superuser setup. -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 - port - - 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. +8. Congratulations! Your Paperless-ngx instance should now be accessible at `http://127.0.0.1:8000` + (or similar, depending on your configuration). Use the superuser credentials you have + created in the previous step to login. ### Build the Docker image yourself {#docker_build} @@ -234,8 +184,8 @@ steps described in [Docker setup](#docker_hub) automatically. context: . ``` -4. Follow steps 3 to 8 of [Docker Setup](#docker_hub). When asked to run - `docker compose pull` to pull the image, do +4. Follow the [Docker setup](#docker) above except when asked to run + `docker compose pull` to pull the image, run ```shell-session $ 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. 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. 6. [Update paperless.](administration.md#updating)