Table of contents

Docker Configuration

This guide describes how to prepare your server for the installation of AtroCore Application. Please make sure your user can use sudo command.

Our docker-compose stack comes with a preconfigured Traefik and Let's Encrypt SSL certificate provider. You need just to set some configuration variables to have a ready to work system.

Installing Docker Engine

To install Docker, your server must meet prerequisites (check official docs). Usually, a server with the fresh installation of Ubuntu 20.04 (and newer) should work well.

To be sure your system does not have any conflicting packages, you need to uninstall them using the next command:

for pkg in docker.io docker-doc docker-compose docker-compose-v2 podman-docker containerd runc; do sudo apt-get remove $pkg; done

In this guide we will set up apt repository to install Docker Engine. If you need more details, please follow official instructions.

Lets setup Docker's apt repository:

sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update

And install the latest version of Docker:

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

To check if everything works well, you can start hello-world container:

sudo docker run hello-world

Configuring Docker Compose services

Downloading Docker Compose configuration

Configuration is hosted on our GitLab repository: https://gitlab.atrocore.com/atrocore/docker

You can choose any directory your user have access. You can use git to clone repository locally:

git clone https://gitlab.atrocore.com/atrocore/docker.git <my-atrocore-project>

<my-atrocore-project> is your project name

Or, you can download a zip archive from repository and unpack it into a suitable directory if you don't want to use git.

Configuring Traefik reverse proxy

Our Docker Compose stack come with preconfigured Traefik and enabled by default Let's Encrypt SSL certificate provider. If you already have Traefik on your server, delete services section from the docker-compose.override.yaml file.

If you need to disable SSL, you should perform the following steps:

  1. Remove these SSL labels from web service in docker-compose-override.yaml:

    # Enable SSL for main AtroPIM instance
- "traefik.http.routers.${PROXY_PRODUCTION_ROUTER}.tls=true"
- "traefik.http.routers.${PROXY_PRODUCTION_ROUTER}.tls.certresolver=letencrypt"

....

# Enable SSL for testing AtroPIM instance
- "traefik.http.routers.${PROXY_TESTING_ROUTER}.tls=true"
- "traefik.http.routers.${PROXY_TESTING_ROUTER}.tls.certresolver=letencrypt"

  2. Replace websecure with web in labels of web service in docker-compose-override.yaml:

    - "traefik.http.routers.${PROXY_PRODUCTION_ROUTER}.entrypoints=websecure" # Replace 'websecure' with 'web' if you don't need SSL

....

- "traefik.http.routers.${PROXY_TESTING_ROUTER}.entrypoints=websecure" # Replace 'websecure' with 'web' if you don't need SSL

  3. Remove Let's Encrypt init command from reverse-proxy service in docker-compose-override.yaml:

    # Remove if you don't need SSL from Lets Encrypt
command:
  - --certificatesResolvers.letencrypt.acme.email=${LETS_ENCRYPT_EMAIL}

  4. Remove 443 port exposure from reverse-proxy service in docker-compose-override.yaml:

    ports:
  - "80:80"
 # Remove if you don't need SSL
  - "443:443"

  5. Remove http to https redirect and Let's Encrypt certificate resolver from traefik.yml:

    # Comment section below if you don't need an SSL or you want to disable automatic redirect to HTTPS
http:
  redirections:
    entryPoint:
      to: websecure
      scheme: https

.....

# Remove if you don't need Lets Encrypt SSL
certificatesResolvers:
  letencrypt:
    acme:
      storage: /certs/acme.json
      caServer: https://acme-v02.api.letsencrypt.org/directory
      httpChallenge:
        entryPoint: web

Configuring environment variables

Create your own environment configuration from example:

cp .env.example .env

Production instance

Following variables in .env file are required to have a working AtroPIM instance:

  • SKELETON_VARIANT (pim-no-demo, atrocore are allowed variants). Default is pim-no-demo
  • PRODUCTION_DOMAIN — domain of your main AtroPIM instance
  • PRODUCTION_STABILITY (stable, rc) — stability branch of your AtroPIM instance. Default value is stable
  • POSTGRES_PASSWORD — password of the postgres user of database, should not be used to install AtroPIM
  • POSTGRES_PIM_USER, POSTGRES_PIM_PASSWORD, and POSTGRES_PIM_DB — database credentials (user, password, DB name) used to install production AtroPIM instance.

Testing instance

If you need to have a testing AtroPIM instance, define the next environmental variables:

  • TESTING_DOMAIN, TESTING_STABILITY — the same meaning as PRODUCTION_DOMAIN, PRODUCTION_STABILITY, but it's for testing instance
  • POSTGRES_PIM_USER, POSTGRES_PIM_PASSWORD, and POSTGRES_PIM_DB — database credentials (user, password, DB name) used to install testing AtroPIM instance.

Traefik-specific variables

If you decide to use our Traefik service, you need to set the next variables:

  • PROXY_PRODUCTION_ROUTER – identifier of Traefik router for main AtroPIM instance. Do not use dots in the value
  • PROXY_TESTING_ROUTER – the same meaning as PROXY_PRODUCTION_ROUTER, but for testing instance
  • LETS_ENCRYPT_EMAIL – your email, required by Lets Encrypt (if you decide to use their SSL certificate)

Please note that PROXY_PRODUCTION_ROUTER and PROXY_TESTING_ROUTER should be unique if you have multiple copies of current docker-compose environment on the same server, or you have your own configured Traefik instance.

Deployment

After all configurations, start your containers with command:

sudo docker compose up -d

You will need to wait until build process for web container is finished. When all container are up and running, open your AtroPIM in browser and finish the WEB installation. Make sure that you've selected PostgreSQL database on Database configuration step.

Additional Tips

  1. For local installation with custom domains don't forget to add them to the hosts file (/etc/hosts for Linux, C:\Windows\System32\drivers\etc\hosts for Windows). For example, for the domain pim.local you need to add the next line to the hosts file:

    127.0.0.1   pim.local

  2. On installing AtroPIM, you need to enter db as a database host on the Database Configuration page.

  3. It's highly recommended of using volumes to store data, since you can remove your containers and recreate them without risk of losing data. By default, volumes are already configured. Follow Docker Documentation for instructions to back up your data inside volumes.

  4. If you need to run additional scripts to configure database, copy your scripts to the .docker/postgres/scripts directory. Find more information in the postgres docs in the Initialization scripts section.

  5. After every change in .env file you need to rebuild your web container: docker compose build web --no-cache. Then you should delete your containers (docker compose down) and recreate them with a new version of image ( docker compose up -d).

  6. By default, HTTP requests automatically redirected by Traefik to HTTPS. You can disable this behaviour by deleting entryPoints.web.http.redirections configuration in traefik.yml file. Don't forget to restart Traefik container.

  7. If you need to store all files on the host directory, not inside the volume, please uncomment marked lines in docker-compose-override.yaml file inside volumes: section:

    # Uncomment if you want to store AtroCore and DB files in data/ folder
volumes:
  web-data:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: ./data/web/
  db-data:
    driver: local
    driver_opts:
      type: none
      o: bind
      device: ./data/db/

  8. After the update to AtroCore 2.0, container configuration needs to be changed. Inside a directory with docker-compose run git pull to download the new migration script ( or download it manually and place right to the docker-compose.yaml file) and run it with command sudo ./migrate-config.sh.