Fleio docker deployment notes¶
docker-compose services¶
A vanilla Fleio deployment runs the following services
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_db_1 docker-entrypoint.sh --cha ... Up 3306/tcp
fleio_frontend_1 /docker-entrypoint.sh ngin ... Up 80/tcp
fleio_incomingmail_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_web_1 /docker-entrypoint.sh ngin ... Up 80/tcp, 0.0.0.0:80->8080/tcp
And these services are using the following docker images:
docker images¶
web
- this is the internet facing service that runs nginx and proxies request to the internalbackend
andfrontend
.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
- runsuwsgi
, which processes the requests in Python with Django and the Django REST Frameworkdb
- runs the database softwarecelery
- contains a copy of the backend files and runs Celery, which runs taskscelerybeat
- runs Celery beat which is actually similar to Linux cron. It is used for periodic tasks, like “process clients”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 withdocker exec
in this container.
The full name of these images container the Fleio docker registry host and the Fleio version, e.g.
hub.fleio.com/fleio_backend-2020-11:0
. The image prefix is the constant hub.fleio.com/fleio_
and the suffix
depends on the Fleio version and is formed based on this convention: -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
installs
docker-compose
checks if minimum RAM storage space requirements are met
checks if
curl
andsudo
are installedcreates or makes sure that the
fleio
user (UID 625) and thefleio
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.comcopies
/home/fleio/bin/fleio
andinstall
scripts from the backend imagegenerates 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
sets Fleio license
creates a Fleio administrator user based on environment variables or user input
starts services with
docker-compose up -d
If you created new files needed to run the docker-compose services, these should be placed 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
(with sudo -i -u fleio
), if it is not already running as
fleio
.
Automatic / unttended 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_USERNAME="john@doe.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_USERNAME="john@doe.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 succeed only 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_USERNAME="john@doe.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_USERNAME="<<the Fleio admin username>>"
FLEIO_ADMIN_PASSWORD="<<Fleio admin password>>"
FLEIO_ADMIN_FIRSTNAME="Demoadmin"
FLEIO_ADMIN_LASTNAME="Demoadmin"
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 is the fleio
command at /usr/bin/fleio
, which is actually a symlink to /home/fleio/bin/file
.
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