Fleio Docker deployment notes

Docker compose services

A vanilla Fleio deployment runs the following services

../_images/fleio-docker-architecture.png

where each box represents a Docker container in a standard Fleio installation. Some details, like Docker volumes (for data storage) or connections to OpenStack, are intentionally left out for simplicity.

web is the only container accessible from the internet (assuming your are not running Fleio in a private network). The rest of the containers are inter-connected in a private Docker network.

You can also see the services and their status by running the fleio status command:

        Name                      Command               State                                          Ports
----------------------------------------------------------------------------------------------------------------------------------------------------
fleio-backend-1        /var/webapps/fleio/env/bin ...   Up      8000/tcp
fleio-celery-1         /var/webapps/fleio/scripts ...   Up
fleio-celerybeat-1     /var/webapps/fleio/scripts ...   Up
fleio-certbot-1        /bin/sh -c trap exit TERM; ...   Up      443/tcp, 80/tcp
fleio-db-1             docker-entrypoint.sh --cha ...   Up      3306/tcp
fleio-fluentd-1        tini -- /bin/entrypoint.sh ...   Up      5140/tcp, 127.0.0.1:24224->24224/tcp, 127.0.0.1:24224->24224/udp
fleio-frontend-1       /docker-entrypoint.sh ngin ...   Up      80/tcp
fleio-incomingmail-1   /var/webapps/fleio/scripts ...   Up
fleio-operations-1     /var/webapps/fleio/scripts ...   Up
fleio-redis-1          docker-entrypoint.sh redis ...   Up      6379/tcp
fleio-updated-1        /var/webapps/fleio/scripts ...   Up
fleio-utils-1          /bin/sleep infinity              Up
fleio-web-1            /docker-entrypoint.sh ngin ...   Up      0.0.0.0:443->4430/tcp,:::443->4430/tcp, 80/tcp, 0.0.0.0:80->8080/tcp,:::80->8080/tcp

Fleio Docker containers

  • web - this is the internet facing service that runs nginx and proxies request to the internal backend and frontend.

  • frontend - contains the static frontend files (.js, .css etc.) and serves them with nginx. This web server is not available on a public IP, but just on the Docker local network.

  • backend - runs uwsgi, which processes the requests in Python with Django and the Django REST Framework

  • db - runs the database server software

  • fluentd - runs the log collection software

  • celery - contains a copy of the backend files and runs Celery, which runs tasks

  • celerybeat - runs Celery beat which is actually similar to Linux cron. It is used for periodic tasks, like “process clients”. Actual tasks are still ran in the celery container, just the scheduling of periodic tasks is handled by celerybeat.

  • operations - handles sequence of tasks that depend on external events by polling the status. For example, on create OpenStack instance with data volume, the volume create task is initiated, and only after the volume is created, the instance is actually created. This solution was chosen instead of having a master Celery task that keeps on running (and wastes a task slot) while polling for complete state of external resources.

  • redis - Redis server used by Celery

  • utils - fleio commands run in this container. It is kept running so that the commands you initiate will run faster.

  • updated - connects to RabbitMQ and processes messages received from OpenStack (like instance created, instance shut off etc.). The “d” historically comes from “daemon”, hence “update daemon”, but you can also say that this container is keeping the Fleio caching database “updated”.

  • incomingmail - just keeps a container running with an infinite loop in bash a script. Each incoming email message (which is usually piped from /etc/aliases) is parsed by a new process created with docker exec in this container.

  • certbot - periodically renews Let’s Encrypt SSL certificate

You can also run docker ps to see running containers and the Docker image name used by each container:

CONTAINER ID   IMAGE                                          COMMAND                  CREATED       STATUS        PORTS                                                                                    NAMES
39d485e29ef6   hub.fleio.com/fleio_webletsencrypt-2023-02:1   "/docker-entrypoint.…"   2 weeks ago   Up 2 weeks    80/tcp, 0.0.0.0:443->4430/tcp, :::443->4430/tcp, 0.0.0.0:80->8080/tcp, :::80->8080/tcp   fleio-web-1
0add0bcbded9   hub.fleio.com/fleio_backend-2023-02:1          "/var/webapps/fleio/…"   2 weeks ago   Up 2 weeks    8000/tcp                                                                                 fleio-backend-1
c6d69849ad30   hub.fleio.com/fleio_celery-2023-02:1           "/var/webapps/fleio/…"   2 weeks ago   Up 15 hours                                                                                            fleio-celery-1
c9da77c9aa07   hub.fleio.com/fleio_celerybeat-2023-02:1       "/var/webapps/fleio/…"   2 weeks ago   Up 2 weeks                                                                                             fleio-celerybeat-1
8993574e457a   hub.fleio.com/fleio_updated-2023-02:1          "/var/webapps/fleio/…"   2 weeks ago   Up 2 weeks                                                                                             fleio-updated-1
23677e46ba29   hub.fleio.com/fleio_operations-2023-02:1       "/var/webapps/fleio/…"   2 weeks ago   Up 2 weeks                                                                                             fleio-operations-1
38713b12d635   hub.fleio.com/fleio_incomingmail-2023-02:1     "/var/webapps/fleio/…"   2 weeks ago   Up 2 weeks                                                                                             fleio-incomingmail-1
bd03dd348579   hub.fleio.com/fleio_frontend-2023-02:1         "/docker-entrypoint.…"   2 weeks ago   Up 2 weeks    80/tcp                                                                                   fleio-frontend-1
9195447cd233   hub.fleio.com/fleio_utils-2023-02:1            "/bin/sleep infinity"    2 weeks ago   Up 2 weeks                                                                                             fleio-utils-1
dfea54b07fab   hub.fleio.com/fleio_fluentd-2023-02:1          "tini -- /bin/entryp…"   2 weeks ago   Up 15 hours   5140/tcp, 127.0.0.1:24224->24224/tcp, 127.0.0.1:24224->24224/udp                         fleio-fluentd-1
29c44e7da8ec   mariadb:10.9.4-jammy                           "docker-entrypoint.s…"   3 weeks ago   Up 2 weeks    3306/tcp                                                                                 fleio-db-1
8a5711fc458f   redis:7.0.7-alpine                             "docker-entrypoint.s…"   6 weeks ago   Up 2 weeks    6379/tcp                                                                                 fleio-redis-1
93a3bc805332   certbot/certbot:v1.32.2                        "/bin/sh -c 'trap ex…"   6 weeks ago   Up 2 weeks    80/tcp, 443/tcp                                                                          fleio-certbot-1

A Fleio Docker image name, like hub.fleio.com/fleio_backend-2022-11:0, is constructed from the Docker hub that hosts our images (hub.fleio.com/), followed by the name of the service (fleio_backend) and a suffix that shows the Fleio version -2022-11:0. The version suffix convention we use is: -MAJORVERSION-MINORVERSION:PATCH

If you want to add or change files in the Fleio Docker images make sure you don’t go against the Docker philosophy and that your changes are not overwritten on Fleio upgrades.

Fleio Docker install script

The Docker install script performs the following operations:

  • installs Docker

  • checks if minimum RAM storage space requirements are met

  • checks if curl and sudo are installed

  • creates or makes sure that the fleio user (UID 625) and the fleio group (GID 625) are already created. Fleio cannot run if user ID is assigned to another user or if the group ID is assigned to another group.

  • reads the Fleio license, saves it to /home/fleio/.fleio_license and authenticates on hub.fleio.com

  • copies /home/fleio/bin/fleio from the backend image

  • generates random MariaDB password and places it in /home/fleio/compose/secrets/.db_password

  • creates the compose files in /home/fleio/compose

  • pulls Docker images from hub.fleio.com

  • creates settings files (these are all stored in volumes, see /home/fleio/compose/docker-compose.yml for a list of volumes)

  • sets the license

  • creates a Fleio administrator user based on environment variables or user input

  • starts services with docker compose up -d

If you add some files to customize your installation, and the files are needed by the docker compose command, you should place your files in a subdirectory in /home/fleio/compose and you must make sure that they are owned by ``fleio:fleio`` (fleio user and fleio group).

The fleio command auto-runs itself as fleio user (with sudo -i -u fleio), if it is not already running as fleio.

Automatic / unattended installation

Here are some examples of how to run the installation script without any human input. Environment variables are explained below, after the examples.

Install Fleio without a SSL certificate:

curl -s -o install https://fleio.com/install && \
sudo \
FLEIO_LICENSE_ID="aioe3d3dd300wooq" \
FLEIO_LICENSE_KEY="CKOJE93JDCOSJDKWLJDWKDCENJ3OJDCWEKD3ICKWHCDEJCEKCKJCEKCIEH=" \
FLEIO_FRONTEND_URL="http://fleiourl.com" \
FLEIO_TIMEZONE="UTC" \
FLEIO_ADMIN_EMAIL="demoadmin@demoadmin.com" \
FLEIO_ADMIN_PASSWORD="ZE_PASSWORD" \
FLEIO_ADMIN_FIRSTNAME="John" \
FLEIO_ADMIN_LASTNAME="Doe" \
bash install

Install Fleio with a self-signed SSL certificate (you can configure your own SSL after install):

curl -s -o install https://fleio.com/install && \
sudo \
FLEIO_LICENSE_ID="aioe3d3dd300wooq" \
FLEIO_LICENSE_KEY="CKOJE93JDCOSJDKWLJDWKDCENJ3OJDCWEKD3ICKWHCDEJCEKCKJCEKCIEH=" \
FLEIO_FRONTEND_URL="https://fleiourl.com" \
FLEIO_TIMEZONE="UTC" \
FLEIO_SSL_OPTION="own_ssl" \
FLEIO_ADMIN_EMAIL="demoadmin@demoadmin.com" \
FLEIO_ADMIN_PASSWORD="ZE_PASSWORD" \
FLEIO_ADMIN_FIRSTNAME="John" \
FLEIO_ADMIN_LASTNAME="Doe" \
bash install

Install Fleio with a Let’s Encrypt SSL certificate. The certificate issuing will only succeed if the domain is pointing to the IP address on the local machine. If the Let’s Encrypt certificate validation fails, the install will fall back to self-signed SSL and this way you’ll have a working Fleio installation. Post-install, after you update the DNS record to have the domain pointing to the local IP, you can run the fleio issue letsencrypt command to issue a valid Let’s Encrypt to certificate.

curl -s -o install https://fleio.com/install && \
sudo \
FLEIO_LICENSE_ID="aioe3d3dd300wooq" \
FLEIO_LICENSE_KEY="CKOJE93JDCOSJDKWLJDWKDCENJ3OJDCWEKD3ICKWHCDEJCEKCKJCEKCIEH=" \
FLEIO_FRONTEND_URL="https://fleiourl.com" \
FLEIO_TIMEZONE="UTC" \
FLEIO_SSL_OPTION="lets_encrypt" \
FLEIO_LETSENCRYPT_AGREE="y" \
FLEIO_SSL_EMAIL="nam@domain.com" \
FLEIO_ADMIN_EMAIL="demoadmin@demoadmin.com" \
FLEIO_ADMIN_PASSWORD="ZE_PASSWORD" \
FLEIO_ADMIN_FIRSTNAME="John" \
FLEIO_ADMIN_LASTNAME="Doe" \
bash install

The following environment variables are available. If a variable is set, the install script will not ask for user input. This way you can create a fully unattended installation, if all required variables are set.

Here are the system environment variables with some example values:

FLEIO_LICENSE_ID="<<16 chars license key>>"
FLEIO_LICENSE_KEY="<<the long license key>>"
FLEIO_FRONTEND_URL="http://myfleio.org"  # note that if the URL does not start with https://, the SSL vars are ignored
FLEIO_TIMEZONE="UTC"
FLEIO_ADMIN_EMAIL="demoadmin@demoadmin.com"
FLEIO_ADMIN_PASSWORD="<<Fleio admin password>>"
FLEIO_ADMIN_FIRSTNAME="Demoadmin"
FLEIO_ADMIN_LASTNAME="Demoadmin"
# FLEIO_DJANGO_SECRET_KEY is useful if you later want to import a database from another Fleio installation that used the key.
# Some fields in the database (like OpenStack admin password) are encrypted using FLEIO_DJANGO_SECRET_KEY.
# If FLEIO_DJANGO_SECRET_KEY is not specified, a random key is generated on install
FLEIO_DJANGO_SECRET_KEY="<<Django secret key>>"
FLEIO_SSL_OPTION="lets_encrypt" # "own_ssl" / "no_ssl" equivalent to ""
FLEIO_LETSENCRYPT_AGREE="y"  # must be "y", only used if FLEIO_SSL_OPTION="lets_encrypt"
FLEIO_SSL_EMAIL="nam@domain.com" # "-"  # only used for Let's Encrypt (FLEIO_SSL_OPTION="lets_encrypt"), if "-" no email will be set on the certificate

The install script installs the latest stable version by default.

Run install --include-beta to install the latest beta version (it will still install a stable version if it’s newer than any beta) or specify a version number: install 2020.11.0.

Docker installation file permissions

All Fleio Docker deployment related files are placed under the /home/fleio directory. The only host files outside this path are the fleio command at /usr/bin/fleio, symlink to /home/fleio/bin/file, and /etc/bash_completion.d/fleio-completion.bash, symlink to /home/fleio/bin/fleio-completion.bash. The Docker files, including data volumes are placed in standard Docker paths (not in the /home/fleio directory!).

You will often use the fleio command to check for fleio status, fleio updates or to fleio upgrade your installation.

When you run the fleio command it checks if it is already running as the fleio user, if not, it will re-run itself with sudo -i -u fleio.

For this reason, all files and directories under the /home/fleio path should be owned by the fleio user.

If you encounter any permissions errors, you can run anytime:

sudo chown -R fleio:fleio /home/fleio