* Replaces references to docker-compose (the v1 executable) with docker compose (the v2 plugin) as well as fixing up some referenes between the tool vs the command
* Update docs/setup.md
Co-authored-by: shamoon <4887959+shamoon@users.noreply.github.com>
* Replaces references to docker-compose (the v1 executable) with docker compose (the v2 plugin) as well as fixing up some referenes between the tool vs the command
---------
Co-authored-by: shamoon <4887959+shamoon@users.noreply.github.com>
# 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 GitHub Packages.
-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:
```bash
bash -c "$(curl -L https://raw.githubusercontent.com/paperless-ngx/paperless-ngx/main/install-paperless-ngx.sh)"
-# docker-compose file for running paperless testing with actual gotenberg
+# Docker Compose file for running paperless testing with actual gotenberg
# and Tika containers for a more end to end test of the Tika related functionality
# Can be used locally or by the CI to start the nessecary containers with the
# correct networking for the tests
-# docker-compose file for running paperless from the Docker Hub.
+# docker compose file for running paperless from the Docker Hub.
# This file contains everything paperless needs to run.
# Paperless supports amd64, arm and arm64 hardware.
#
# as this file and mounted to the correct folders inside the container.
# - Paperless listens on port 8000.
#
-# In addition to that, this docker-compose file adds the following optional
+# In addition to that, this Docker Compose file adds the following optional
# configurations:
#
# - Instead of SQLite (default), MariaDB is used as the database server.
#
# - Copy this file as 'docker-compose.yml' and the files 'docker-compose.env'
# and '.env' into a folder.
-# - Run 'docker-compose pull'.
-# - Run 'docker-compose run --rm webserver createsuperuser' to create a user.
-# - Run 'docker-compose up -d'.
+# - Run 'docker compose pull'.
+# - Run 'docker compose run --rm webserver createsuperuser' to create a user.
+# - Run 'docker compose up -d'.
#
# For more extensive installation and update instructions, refer to the
# documentation.
-# docker-compose file for running paperless from the Docker Hub.
+# Docker Compose file for running paperless from the Docker Hub.
# This file contains everything paperless needs to run.
# Paperless supports amd64, arm and arm64 hardware.
#
# as this file and mounted to the correct folders inside the container.
# - Paperless listens on port 8000.
#
-# In addition to that, this docker-compose file adds the following optional
+# In addition to that, this Docker Compose file adds the following optional
# configurations:
#
# - Instead of SQLite (default), MariaDB is used as the database server.
#
# - Copy this file as 'docker-compose.yml' and the files 'docker-compose.env'
# and '.env' into a folder.
-# - Run 'docker-compose pull'.
-# - Run 'docker-compose run --rm webserver createsuperuser' to create a user.
-# - Run 'docker-compose up -d'.
+# - Run 'docker compose pull'.
+# - Run 'docker compose run --rm webserver createsuperuser' to create a user.
+# - Run 'docker compose up -d'.
#
# For more extensive installation and update instructions, refer to the
# documentation.
-# docker-compose file for running paperless from the Docker Hub.
+# Docker Compose file for running paperless from the Docker Hub.
# This file contains everything paperless needs to run.
# Paperless supports amd64, arm and arm64 hardware.
#
# as this file and mounted to the correct folders inside the container.
# - Paperless listens on port 8010.
#
-# In addition to that, this docker-compose file adds the following optional
+# In addition to that, this Docker Compose file adds the following optional
# configurations:
#
# - Instead of SQLite (default), PostgreSQL is used as the database server.
-# docker-compose file for running paperless from the docker container registry.
+# Docker Compose file for running paperless from the docker container registry.
# This file contains everything paperless needs to run.
# Paperless supports amd64, arm and arm64 hardware.
#
# as this file and mounted to the correct folders inside the container.
# - Paperless listens on port 8000.
#
-# In addition to that, this docker-compose file adds the following optional
+# In addition to that, this Docker Compose file adds the following optional
# configurations:
#
# - Instead of SQLite (default), PostgreSQL is used as the database server.
#
# - Copy this file as 'docker-compose.yml' and the files 'docker-compose.env'
# and '.env' into a folder.
-# - Run 'docker-compose pull'.
-# - Run 'docker-compose run --rm webserver createsuperuser' to create a user.
-# - Run 'docker-compose up -d'.
+# - Run 'docker compose pull'.
+# - Run 'docker compose run --rm webserver createsuperuser' to create a user.
+# - Run 'docker compose up -d'.
#
# For more extensive installation and update instructions, refer to the
# documentation.
-# docker-compose file for running paperless from the Docker Hub.
+# Docker Compose file for running paperless from the Docker Hub.
# This file contains everything paperless needs to run.
# Paperless supports amd64, arm and arm64 hardware.
#
# as this file and mounted to the correct folders inside the container.
# - Paperless listens on port 8000.
#
-# In addition to that, this docker-compose file adds the following optional
+# In addition to that, this Docker Compose file adds the following optional
# configurations:
#
# - Instead of SQLite (default), PostgreSQL is used as the database server.
#
# - Copy this file as 'docker-compose.yml' and the files 'docker-compose.env'
# and '.env' into a folder.
-# - Run 'docker-compose pull'.
-# - Run 'docker-compose run --rm webserver createsuperuser' to create a user.
-# - Run 'docker-compose up -d'.
+# - Run 'docker compose pull'.
+# - Run 'docker compose run --rm webserver createsuperuser' to create a user.
+# - Run 'docker compose up -d'.
#
# For more extensive installation and update instructions, refer to the
# documentation.
-# docker-compose file for running paperless from the docker container registry.
+# Docker Compose file for running paperless from the docker container registry.
# This file contains everything paperless needs to run.
# Paperless supports amd64, arm and arm64 hardware.
# All compose files of paperless configure paperless in the following way:
#
# SQLite is used as the database. The SQLite file is stored in the data volume.
#
-# In addition to that, this docker-compose file adds the following optional
+# In addition to that, this Docker Compose file adds the following optional
# configurations:
#
# - Apache Tika and Gotenberg servers are started with paperless and paperless
#
# - Copy this file as 'docker-compose.yml' and the files 'docker-compose.env'
# and '.env' into a folder.
-# - Run 'docker-compose pull'.
-# - Run 'docker-compose run --rm webserver createsuperuser' to create a user.
-# - Run 'docker-compose up -d'.
+# - Run 'docker compose pull'.
+# - Run 'docker compose run --rm webserver createsuperuser' to create a user.
+# - Run 'docker compose up -d'.
#
# For more extensive installation and update instructions, refer to the
# documentation.
-# docker-compose file for running paperless from the Docker Hub.
+# Docker Compose file for running paperless from the Docker Hub.
# This file contains everything paperless needs to run.
# Paperless supports amd64, arm and arm64 hardware.
#
#
# - Copy this file as 'docker-compose.yml' and the files 'docker-compose.env'
# and '.env' into a folder.
-# - Run 'docker-compose pull'.
-# - Run 'docker-compose run --rm webserver createsuperuser' to create a user.
-# - Run 'docker-compose up -d'.
+# - Run 'docker compose pull'.
+# - Run 'docker compose run --rm webserver createsuperuser' to create a user.
+# - Run 'docker compose up -d'.
#
# For more extensive installation and update instructions, refer to the
# documentation.
```shell-session
$ cd /path/to/paperless
-$ docker-compose down
+$ docker compose down
```
After that, [make a backup](#backup).
1. If you pull the image from the docker hub, all you need to do is:
```shell-session
- $ docker-compose pull
- $ docker-compose up
+ $ docker compose pull
+ $ docker compose up
```
- The docker-compose files refer to the `latest` version, which is
+ The Docker Compose files refer to the `latest` version, which is
always the latest stable release.
1. If you built the image yourself, do the following:
```shell-session
$ git pull
- $ docker-compose build
- $ docker-compose up
+ $ docker compose build
+ $ docker compose up
```
-Running `docker-compose up` will also apply any new database migrations.
+Running `docker compose up` will also apply any new database migrations.
If you see everything working, press CTRL+C once to gracefully stop
paperless. Then you can start paperless-ngx with `-d` to have it run in
the background.
!!! note
In version 0.9.14, the update process was changed. In 0.9.13 and
- earlier, the docker-compose files specified exact versions and pull
+ earlier, the Docker Compose files specified exact versions and pull
won't automatically update to newer versions. In order to enable
updates as described above, either get the new `docker-compose.yml`
file from
maintenance tasks on your paperless instance. You can invoke these
commands in the following way:
-With docker-compose, while paperless is running:
+With Docker Compose, while paperless is running:
```shell-session
$ cd /path/to/paperless
-$ docker-compose exec webserver <command> <arguments>
+$ docker compose exec webserver <command> <arguments>
```
With docker, while paperless is running:
If you use the document exporter within a cronjob to backup your data
you might use the `-T` flag behind exec to suppress "The input device
is not a TTY" errors. For example:
-`docker-compose exec -T webserver document_exporter ../export`
+`docker compose exec -T webserver document_exporter ../export`
```
document_exporter target [-c] [-d] [-f] [-na] [-nt] [-p] [-sm] [-z]
Troubleshooting:
-- Monitor the docker-compose log
- `cd ~/paperless-ngx; docker-compose logs -f`
+- Monitor the Docker Compose log
+ `cd ~/paperless-ngx; docker compose logs -f`
- Check your script's permission e.g. in case of permission error
`sudo chmod 755 post-consumption-example.sh`
- Pipe your scripts's output to a log file e.g.
Defaults to "<http://localhost:3000>".
If you run paperless on docker, you can add those services to the
-docker-compose file (see the provided
+Docker Compose file (see the provided
[`docker-compose.sqlite-tika.yml`](https://github.com/paperless-ngx/paperless-ngx/blob/main/docker/compose/docker-compose.sqlite-tika.yml)
file for reference).
## _How do I install paperless-ngx on Raspberry Pi?_
**A:** Docker images are available for arm64 hardware, so just
-follow the [docker-compose instructions](https://docs.paperless-ngx.com/setup/#installation). Apart from more required disk
+follow the [Docker Compose instructions](https://docs.paperless-ngx.com/setup/#installation). Apart from more required disk
space compared to a bare metal installation, docker comes with close to
zero overhead, even on Raspberry Pi.
and create your user account. This script essentially performs all the
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.
+
+ !!! tip
+ See the Docker installation instructions at https://docs.docker.com/engine/install/
2. Download and run the installation script:
For new installations, it is recommended to use PostgreSQL as the
database backend.
-3. Install [Docker](https://www.docker.com/) and
- [docker-compose](https://docs.docker.com/compose/install/).
+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 **1.17.0**. To check do: `docker-compose -v` or `docker -v`
+ need to have at least Docker version **17.09.0** and Docker Compose
+ version **v2**. To check do: `docker compose -v` 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
+ 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
[`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.
+6. Run `docker compose pull`. This will pull the image.
7. To be able to login, you will need a super user. To create it,
execute the following command:
```shell-session
- $ docker-compose run --rm webserver createsuperuser
+ $ docker compose run --rm webserver createsuperuser
```
or using docker exec from within the container:
This will prompt you to set a username, an optional e-mail address
and finally a password (at least 8 characters).
-8. Run `docker-compose up -d`. This will create and start the necessary containers.
+8. 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
root as well.
3. In the `docker-compose.yml` file, find the line that instructs
- docker-compose to pull the paperless image from Docker Hub:
+ Docker Compose to pull the paperless image from Docker Hub:
```yaml
webserver:
image: ghcr.io/paperless-ngx/paperless-ngx:latest
```
- and replace it with a line that instructs docker-compose to build
+ and replace it with a line that instructs Docker Compose to build
the image from the current working directory instead:
```yaml
```
4. Follow steps 3 to 8 of [Docker Setup](#docker_hub). When asked to run
- `docker-compose pull` to pull the image, do
+ `docker compose pull` to pull the image, do
```shell-session
- $ docker-compose build
+ $ docker compose build
```
instead to build the image.
image: ghcr.io/paperless-ngx/paperless-ngx:latest
```
-and then run `docker-compose up -d` which will pull the new image
+and then run `docker compose up -d` which will pull the new image
recreate the container. That's it!
Users who installed with the bare-metal route should also update their
- The task scheduler of paperless, which is used to execute periodic
tasks such as email checking and maintenance, requires a
[redis](https://redis.io/) message broker instance. The
- docker-compose route takes care of that.
+ Docker Compose route takes care of that.
- The layout of the folder structure for your documents and data
remains the same, so you can just plug your old docker volumes into
paperless-ngx and expect it to find everything where it should be.
```bash
$ cd /path/to/current/paperless
- $ docker-compose down
+ $ docker compose down
```
2. Do a backup for two purposes: If something goes wrong, you still
switch back to paperless.
3. Download the latest release of paperless-ngx. You can either go with
- the docker-compose files from
+ the Docker Compose files from
[here](https://github.com/paperless-ngx/paperless-ngx/tree/main/docker/compose)
or clone the repository to build the image yourself (see
[above](#docker_build)). You can
the search index:
```shell-session
- $ docker-compose run --rm webserver document_index reindex
+ $ docker compose run --rm webserver document_index reindex
```
This will migrate your database and create the search index. After
8. Start paperless-ngx.
```bash
- $ docker-compose up -d
+ $ docker compose up -d
```
This will run paperless in the background and automatically start it
8. Modify the `image:` to point to
`ghcr.io/paperless-ngx/paperless-ngx:latest` or a specific version
if preferred.
-9. Start the containers as before, using `docker-compose`.
+9. Start the containers as before, using `docker compose`.
## Moving data from SQLite to PostgreSQL or MySQL/MariaDB {#sqlite_to_psql}
``` shell-session
$ cd /path/to/paperless
- $ docker-compose run --rm webserver /bin/bash
+ $ docker compose run --rm webserver /bin/bash
```
This will launch the container and initialize the PostgreSQL
```shell-session
$ cd /path/to/paperless
-$ docker-compose run --rm webserver migrate documents 0023
+$ docker compose run --rm webserver migrate documents 0023
```
Or without docker:
- Ensure that the directory you're putting your documents in is the
folder paperless is watching. With docker, this setting is performed
- in the `docker-compose.yml` file. Without docker, look at the
+ in the `docker-compose.yml` file. Without Docker, look at the
`CONSUMPTION_DIR` setting. Don't adjust this setting if you're
using docker.
You can increase the timeout by configuring a command flag for Gotenberg
(see also [here](https://gotenberg.dev/docs/modules/api#properties)). If
-using docker-compose, this is achieved by the following configuration
+using Docker Compose, this is achieved by the following configuration
change in the `docker-compose.yml` file:
```yaml
exit 1
fi
-DOCKER_COMPOSE_CMD="docker-compose"
-if ! command -v ${DOCKER_COMPOSE_CMD} &> /dev/null ; then
- if docker compose version &> /dev/null ; then
- DOCKER_COMPOSE_CMD="docker compose"
- else
- echo "docker-compose executable not found. Is docker-compose installed?"
- exit 1
- fi
+if ! command -v docker compose &> /dev/null ; then
+ echo "docker compose executable not found. Is docker compose installed?"
+ exit 1
fi
# Check if user has permissions to run Docker by trying to get the status of Docker (docker status).
fi
-${DOCKER_COMPOSE_CMD} pull
+docker compose pull
if [ "$DATABASE_BACKEND" == "postgres" ] || [ "$DATABASE_BACKEND" == "mariadb" ] ; then
echo "Starting DB first for initilzation"
- ${DOCKER_COMPOSE_CMD} up --detach db
+ docker compose up --detach db
# hopefully enough time for even the slower systems
sleep 15
- ${DOCKER_COMPOSE_CMD} stop
+ docker compose stop
fi
-${DOCKER_COMPOSE_CMD} run --rm -e DJANGO_SUPERUSER_PASSWORD="$PASSWORD" webserver createsuperuser --noinput --username "$USERNAME" --email "$EMAIL"
+docker compose run --rm -e DJANGO_SUPERUSER_PASSWORD="$PASSWORD" webserver createsuperuser --noinput --username "$USERNAME" --email "$EMAIL"
-${DOCKER_COMPOSE_CMD} up --detach
+docker compose up --detach