mirror of
https://github.com/TheAnachronism/docspell.git
synced 2025-06-23 10:58:26 +00:00
Add documentation about docker setup
This commit is contained in:
eikek
242
website/site/content/docs/install/docker.md
Normal file
242
website/site/content/docs/install/docker.md
Normal file
@ -0,0 +1,242 @@
|
||||
+++
|
||||
title = "Docker"
|
||||
weight = 20
|
||||
+++
|
||||
|
||||
## Docker Images
|
||||
|
||||
The docker images are at
|
||||
[hub.docker.com](https://hub.docker.com/u/docspell). The `latest` tag
|
||||
always points to the latest *release*. The releases are also tagged
|
||||
with their respective version number. Additionally, there are images
|
||||
tagged with `nightly` which are built from the `master` branch.
|
||||
Therefore the `nightly` packages should be used with care, because
|
||||
things might break in between. But they are useful for trying out
|
||||
something.
|
||||
|
||||
There are images for all components that are available from the github
|
||||
release page. The images contain all the necessary
|
||||
[prerequisites](@/docs/install/prereq.md).
|
||||
|
||||
- `docspell-restserver` this images contains the http server
|
||||
- `docspell-joex` this image contains the job executor and all
|
||||
required software (ocrmypdf, unoconv etc) mentioned in
|
||||
[prerequisites](@/docs/install/prereq.md).
|
||||
- `docspell-tools` this image simply contains all the scripts from the
|
||||
`tools/` folder. They are installed into a location in `$PATH`. It
|
||||
doesn't specify a `CMD` or `ENTRYPOINT`, so you must choose which
|
||||
script to run. The scripts are all prefixed by `ds-`. So to run the
|
||||
`consumedir.sh` script, execute `ds-consumedir`.
|
||||
|
||||
### Examples
|
||||
|
||||
These examples use `docker run` to start the restserver and
|
||||
jobexecutor. Both must be connected to the same database. For this
|
||||
example, a shared directory is used and the in-process database H2.
|
||||
For a real setup, using PostgreSQL is recommended.
|
||||
|
||||
This requires to change the default config. This example creates a new
|
||||
config file. Please refer to the [configuration
|
||||
page](@/docs/configure/_index.md) for more details.
|
||||
|
||||
``` bash
|
||||
$ cat > /tmp/docspell.conf <<-"EOF"
|
||||
# common settings
|
||||
db_url = "jdbc:h2:///var/docspell/db;MODE=PostgreSQL;DATABASE_TO_LOWER=TRUE;AUTO_SERVER=TRUE"
|
||||
|
||||
# job executor settings
|
||||
docspell.joex.jdbc.url = ${db_url}
|
||||
docspell.joex.base-url = "http://10.4.3.2:7878"
|
||||
docspell.joex.bind.address = "0.0.0.0"
|
||||
|
||||
# restserver settings
|
||||
docspell.server.backend.jdbc.url = ${db_url}
|
||||
docspell.server.bind.address = "0.0.0.0"
|
||||
docspell.server.integration-endpoint {
|
||||
enabled = true
|
||||
http-header {
|
||||
enabled = true
|
||||
header-value = "test123"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
This sets the db url to the same value for both components; thus we
|
||||
can use the same file for both components. It also sets the bind
|
||||
address to bind the server socket on all interfaces. Another thing to
|
||||
note is the `base-url` setting for joex. This publishes joex by this
|
||||
ip, such that the server component can notify the job executor for new
|
||||
work. The `integration-endpoint` setting is explained later.
|
||||
|
||||
After creating a common network, we start the rest server and joex:
|
||||
```
|
||||
$ docker network create --subnet 10.4.3.0/24 dsnet
|
||||
$ docker run -d --name ds-restserver \
|
||||
--network dsnet --ip 10.4.3.3 \
|
||||
-p 127.0.0.1:7880:7880 \
|
||||
-v /tmp/testdb:/var/docspell \
|
||||
-v /tmp/docspell.conf:/opt/docspell.conf \
|
||||
docspell/restserver:latest /opt/docspell.conf
|
||||
$ docker run -d --name ds-joex \
|
||||
--network dsnet --ip 10.4.3.2 \
|
||||
-v /tmp/testdb:/var/docspell \
|
||||
-v /tmp/docspell.conf:/opt/docspell.conf \
|
||||
docspell/joex:latest /opt/docspell.conf
|
||||
```
|
||||
|
||||
After this `docker ps` should show these two containers. Go to
|
||||
`http://localhost:7880` and sign up/login and start playing around.
|
||||
When signing up, use the same name for collective and user and then
|
||||
login with this name.
|
||||
|
||||
For the last part, we use the `docspell/tools` image to create another
|
||||
container that watches a directory and pushes files to docspell.
|
||||
|
||||
``` bash
|
||||
$ docker run -d --name ds-consume \
|
||||
--network dsnet --ip 10.4.3.4 \
|
||||
-v /tmp/inbox:/var/inbox \
|
||||
docspell/tools:latest ds-consumedir -imdv --iheader "Docspell-Integration:test123" \
|
||||
--path /var/inbox "http://10.4.3.3:7880/api/v1/open/integration/item"
|
||||
```
|
||||
|
||||
This starts the [consumedir](@/docs/tools/consumedir.md) script that
|
||||
watches a directory and uploads arriving files to docspell server.
|
||||
This requires the value from the `integration-endpoint` setting to be
|
||||
allowed to upload files. It also requires you to explicitely enable
|
||||
this: go to *Collective Profile → Settings* and enable the
|
||||
*Integration Endpoint*. Then create a subdirectory in `/tmp/inbox`
|
||||
with the name of the *collective* that you registered and place a file
|
||||
into the `/tmp/inbox/[collective]` directory. The file is pushed to
|
||||
docspell and processed shortly after.
|
||||
|
||||
To see all available options, run the script with the `--help` option:
|
||||
``` bash
|
||||
$ docker run docspell/tools:latest ds-consumedir --help
|
||||
```
|
||||
|
||||
|
||||
Note that this is just an example and is only to demonstrate how to
|
||||
use the docker images. For instance, this setup does not provide
|
||||
fulltext search. For a more sophisticated docker setup, use
|
||||
appropriate tools, for example `docker-compose` which is explained
|
||||
below.
|
||||
|
||||
## Docker Compose
|
||||
|
||||
There is a [docker-compose](https://docs.docker.com/compose/) setup
|
||||
available in the `/docker/docker-compose` folder. This setup is
|
||||
similiar to the example above, adding fulltext search and a PostgreSQL
|
||||
database by using just one command. It's only 3 steps to get started:
|
||||
|
||||
### Start Docspell
|
||||
#### Get the docker-compose files
|
||||
|
||||
Either via cloning the whole repository:
|
||||
|
||||
```bash
|
||||
$ git clone https://github.com/eikek/docspell
|
||||
```
|
||||
|
||||
This downloads all sources. What you need is only one subdirectory. So
|
||||
if you don't have git or don't want to clone the whole repo, use these
|
||||
steps instead:
|
||||
|
||||
``` bash
|
||||
$ mkdir -p docspell/docker/docker-compose
|
||||
$ cd docspell/docker/docker-compose
|
||||
$ wget https://raw.githubusercontent.com/eikek/docspell/master/docker/docker-compose/docker-compose.yml
|
||||
$ wget https://raw.githubusercontent.com/eikek/docspell/master/docker/docker-compose/docspell.conf
|
||||
$ wget https://raw.githubusercontent.com/eikek/docspell/master/docker/docker-compose/.env
|
||||
```
|
||||
|
||||
You can choose any directory instead of
|
||||
`docspell/docker/docker-compose`, of course.
|
||||
|
||||
Change into the new `docker-compose` directory, for example:
|
||||
|
||||
```bash
|
||||
$ cd docspell/docker/docker-compose
|
||||
```
|
||||
|
||||
#### Run `docker-compose up`
|
||||
|
||||
```bash
|
||||
$ export DOCSPELL_HEADER_VALUE="my-secret-123"
|
||||
$ docker-compose up
|
||||
```
|
||||
|
||||
The environment variable defines a secret that is shared between some
|
||||
containers. You can define whatever you like. Please see the
|
||||
[consumedir.sh](@/docs/tools/consumedir.md#docker) docs for additional
|
||||
info.
|
||||
|
||||
Goto `http://localhost:7880`, signup and login. When signing up, you
|
||||
choose the same name for collective and user. Then login with this
|
||||
name and the password.
|
||||
|
||||
(Optional) Create a folder `./docs/<collective-name>` (the name you
|
||||
chose for the collective at registration) and place files in there for
|
||||
importing them.
|
||||
|
||||
The directory contains a file `docspell.conf` that you can
|
||||
[modify](@/docs/configure/_index.md) as needed.
|
||||
|
||||
|
||||
### Override this setup
|
||||
|
||||
If you want to change this setup, you can simply use your own compose
|
||||
file or add a `docker-compose.override.yml` that allows to amend
|
||||
certain configs. Look [here](https://docs.docker.com/compose/extends/)
|
||||
to find more about it.
|
||||
|
||||
As an example, here is a `docker-compose.override.yml`:
|
||||
|
||||
``` yaml
|
||||
version: '3.7'
|
||||
|
||||
services:
|
||||
consumedir:
|
||||
volumes:
|
||||
- importdocs:/opt/docs
|
||||
|
||||
volumes:
|
||||
docspell-postgres_data:
|
||||
driver: local
|
||||
driver_opts:
|
||||
type: nfs4
|
||||
o: addr=192.168.x.y,rw,noatime,rsize=8192,wsize=8192,tcp,timeo=14
|
||||
device: ":/mnt/FreeNas/docker_vol1/docspell/postgres_data"
|
||||
|
||||
docspell-solr_data:
|
||||
driver: local
|
||||
driver_opts:
|
||||
type: nfs4
|
||||
o: addr=192.168.x.y,rw,noatime,rsize=8192,wsize=8192,tcp,timeo=14
|
||||
device: ":/mnt/FreeNas/docker_vol1/docspell/solr_data"
|
||||
|
||||
importdocs:
|
||||
driver: local
|
||||
driver_opts:
|
||||
type: nfs4
|
||||
o: addr=192.168.x.y,rw,noatime,rsize=8192,wsize=8192,tcp,timeo=14
|
||||
device: ":/mnt/FreeNas/archiv/gescannt/output"
|
||||
```
|
||||
|
||||
|
||||
### Upgrading
|
||||
|
||||
Since [downgrading](@/docs/install/downgrading.md) is not supported,
|
||||
it is recommended to backup your database before upgrading. Should
|
||||
something not work as expected, restore the database backup and go
|
||||
back to the previous version.
|
||||
|
||||
The latest release is always tagged with `latest`. Should you use this
|
||||
tag, then run these commands to upgrade to newer images:
|
||||
|
||||
``` bash
|
||||
$ docker-compose down
|
||||
$ docker-compose pull
|
||||
$ docker-compose up --force-recreate --build -d
|
||||
```
|
||||
Reference in New Issue
Block a user