Install with Docker

How to install Kresus with Docker?

Install with Docker

Warning: read before running any docker image

By default docker exposes the port 9876 to 0.0.0.0, which will make your Kresus instance exposed to the whole world. If you are behind a reverse-proxy such as nginx or apache, prefer -p 127.0.0.1:9876:9876 to make it visible to your reverse-proxy only. This documentation will however use -p 9876:9876 in all examples below, to remain generic.

Run a pre-built image

The Docker images already bundles all the required dependencies, including the full Woob install. At each boot, Woob will try to update; if you have any problem with modules you should then try to simply restart the image.

This pre-built image exposes several data volumes. It is not mandatory to mount them, but it would let you persist your personal data across reboots of the Docker image.

/home/user/data stores all data used by Kresus. It is recommended to mount this volume, to avoid losing data at each restart of the image (for instance after an update).
/woob stores the local Woob clone, set up at startup. It is not mandatory to expose it to the local filesystem, but this would allow you to
- share Woob installation folders across scripts and Kresus instances, resulting in less disk space being used.
- set some crontab on the host machine to regularly update Woob completely (with a git pull in the Woob folder from the host).
/opt/config.ini is a configuration file. You can find more information about the configuration file. You should at least edit the database configuration.

Note: if you clone Woob, it is suggested to use the master (development) branch, which is more likely to be up to date than the stable branch.

The following environment variable can be used:

LOCAL_USER_ID selects the UID of the user inside the Docker image (for preventing Kresus from running as root).

Here is an example of command line to run to start Kresus in production in a Docker image, with the same UNIX user as current:

mkdir -p /opt/kresus/data
mkdir -p /opt/kresus/woob
touch /opt/kresus/config.ini
# Edit /opt/kresus/config.ini to fill database items (see the administration documentation "With a config.ini file")
git clone https://gitlab.com/woob/woob.git /opt/kresus/woob

docker run -p 9876:9876 \
    -e LOCAL_USER_ID=`id -u` \
    --restart unless-stopped \
    -v /opt/kresus/data:/home/user/data \
    -v /opt/kresus/woob:/woob \
    -v /opt/kresus/config.ini:/opt/config.ini \
    -v /etc/localtime:/etc/localtime \
    --name kresus \
    -ti -d bnjbvr/kresus

Use docker-compose

The docker-compose directory contains all elements to easily run kresus:

a reverse proxy (traefik)
a postfix server to send mails
kresus

Functionalities:

automatic SSL encryption with letsencrypt.
login/password access to kresus.

Prerequisites:

a public server, with a fully qualified domain name, having ports 80 and 443 open (no running apache or nginx).
docker-compose must be installed (version >= 1.19).

Method

create a password with htpasswd :

htpasswd -bn my_user my_password | awk -F':' '{print $2}'

rename the docker-compose-example.env file to .env (it must be in the docker-compose directory).
edit .env file, replacing all vars:
- MY_DOMAIN : server fully qualified domain name (for instance: myserver.mydomain.net).
- MAIL_ADDRESS : mail address to receive letsencrypt alerts.
- MY_USERNAME : username for authentication.
- MY_PASSWD : username for authentication, the one you got on the first step.
rename the docker-compose.example.yml to docker-compose.yml.
Then launch docker-compose :
```
 docker-compose up -d
```

Build the Docker image

Stable image

The image for the latest stable version of Kresus can be downloaded through the Docker hub. This is the image called bnjbvr/kresus.

You can also build it yourself. You will need nodejs (preferably LTS version or later) and npm to build the image from scratch.

git clone https://framagit.org/kresusapp/kresus && cd kresus
docker build -t myself/kresus -f support/docker/Dockerfile-stable support/docker/.

You can then use it:

docker run -p 9876:9876 -v /opt/kresus/data:/home/user/data -ti -d myself/kresus

Nightly image

There is also a nightly image, with the latest updates, which is built every night from the Git repository. Be warned that this image is experimental and can contain a lot of bugs or corrupt your data, as the main branch can be instable from time to time. This image will fetch the latest sources from the online Git repository and will not use any local sources.

To build a Nightly image built for a use in production (after version 0.16):

./scripts/docker/nightly.sh

Or before version 0.16:

make docker-nightly

This command will build an image named bnjbvr/kresus-nightly.

Then, to start it, you can use the same docker run command as before, with the correct image name:

docker run -p 9876:9876 \
    -e LOCAL_USER_ID=`id -u` \
    --restart unless-stopped \
    -v /opt/kresus/data:/home/user/data \
    -v /opt/kresus/woob:/woob \
    -v /opt/kresus/config.ini:/opt/config.ini \
    -v /etc/localtime:/etc/localtime \
    --name kresus \
    -ti -d bnjbvr/kresus-nightly