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:
-
Remove these SSL labels from
web
service indocker-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"
-
Replace
websecure
withweb
in labels ofweb
service indocker-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
-
Remove Let's Encrypt init command from
reverse-proxy
service indocker-compose-override.yaml
:# Remove if you don't need SSL from Lets Encrypt command: - --certificatesResolvers.letencrypt.acme.email=${LETS_ENCRYPT_EMAIL}
-
Remove 443 port exposure from
reverse-proxy
service indocker-compose-override.yaml
:ports: - "80:80" # Remove if you don't need SSL - "443:443"
-
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 ispim-no-demo
PRODUCTION_DOMAIN
— domain of your main AtroPIM instancePRODUCTION_STABILITY
(stable
,rc
) — stability branch of your AtroPIM instance. Default value isstable
POSTGRES_PASSWORD
— password of thepostgres
user of database, should not be used to install AtroPIMPOSTGRES_PIM_USER
,POSTGRES_PIM_PASSWORD
, andPOSTGRES_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 asPRODUCTION_DOMAIN
,PRODUCTION_STABILITY
, but it's for testing instancePOSTGRES_PIM_USER
,POSTGRES_PIM_PASSWORD
, andPOSTGRES_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 valuePROXY_TESTING_ROUTER
– the same meaning asPROXY_PRODUCTION_ROUTER
, but for testing instanceLETS_ENCRYPT_EMAIL
– your email, required by Lets Encrypt (if you decide to use their SSL certificate)
Please note that
PROXY_PRODUCTION_ROUTER
andPROXY_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
-
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 domainpim.local
you need to add the next line to thehosts
file:127.0.0.1 pim.local
-
On installing AtroPIM, you need to enter
db
as a database host on theDatabase Configuration
page. -
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.
-
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 theInitialization scripts
section. -
After every change in
.env
file you need to rebuild yourweb
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
). -
By default, HTTP requests automatically redirected by Traefik to HTTPS. You can disable this behaviour by deleting
entryPoints.web.http.redirections
configuration intraefik.yml
file. Don't forget to restart Traefik container. -
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 insidevolumes:
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/
-
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 thedocker-compose.yaml
file) and run it with commandsudo ./migrate-config.sh
.