Skip to main content

Deploy FlexIt

This repository provides everything needed to deploy FlexIt using Docker.

On Windows, see Docker on Windows

Prerequisites​

An Ubuntu server with sudo access. The install script installs Docker and the Docker Compose plugin if they aren't already present. On other Linux distributions, install Docker and Docker Compose first.

Deployment Options​

The deployment runs two containers: FlexIt Analytics (flexit-analytics) and its PostgreSQL 15 content database (flexit-content-database). For https, you can optionally add:

  • Nginx as a reverse proxy, with your own certificates or certificates managed automatically through Let's Encrypt
  • A self-signed certificate, for testing

Without Nginx, FlexIt is exposed directly on FLEXIT_PORT.

Installation Instructions​

1. Clone the Repository​

git clone https://github.com/flexanalytics/flexit-docker-linux.git
cd flexit-docker-linux

2. Configure Environment Variables​

Copy the .env.template file to .env and update the following. The .env file must exist before you install.

FlexIt and the content database:

## -- frontend app setup -- ##
FLEXIT_PORT=3030
FLEXIT_VERSION=latest

## -- backend db setup -- ##
CONTENT_DB_VERSION=latest
DB_USER='flexit'
DB_PASSWORD='secure-password'
DB_NAME='flexit'
DB_PORT=5432

Encryption of stored passwords and keys. Generate a key with openssl rand -hex 16, and keep it: if it is lost or changed, saved secrets can't be decrypted.

## -- credential encryption -- ##
FLEXIT_ENCRYPTION_KEY=

Optional https setup:

## -- [optional] nginx setup -- ##
USE_NGINX=false
CERT_PATH='/opt/nginx/certs'
PUBLIC_DNS='a.example.com'
NGINX_HTTPS_PORT=443
NGINX_HTTP_PORT=80

## -- [optional] automatic certificate management -- ##
AUTO_MANAGE_CERTS=false
CERT_EMAIL='email@site.com'

## -- [optional] use local self-signed cert -- ##
USE_SELF_SIGNED_CERT=false

The template also has optional settings for automatic deployment.

Installation and Setup​

Installing for the first time​

Run:

sudo ./install.sh

This command installs Docker if needed, builds the images, and starts the containers.

Access FlexIt​

Visit the application at:

Managing the Docker Containers​

Stopping the Application​

To stop the application:

./scripts/stop_server.sh

Starting the Application​

To start the application:

./scripts/start_server.sh

Restarting the Application​

To pull the latest changes from an upstream repo and restart the application:

./scripts/restart_server.sh

Deploying the Application​

To deploy the application with custom files in the volumes directory, including pulling changes and restarting, run:

./scripts/deploy_server.sh

Automatic Deployment​

scripts/auto_deploy_server.sh runs a deployment when one is requested from FlexIt, or when a new commit is pushed to the branch set in GIT_DEPLOY_BRANCH. Schedule it with cron; scripts/crontab.example has a ready-made entry that checks every minute. To request deploys from FlexIt, see Server Deploys. Related .env settings:

## -- [optional] auto-deploy cron -- ##
AUTO_DEPLOY_FAIL_BEHAVIOR=retry
AUTO_DEPLOY_MAX_ATTEMPTS=5

## -- [optional] certificate renewal -- ##
CERT_RENEW_MAX_FAILURES=3

## -- [optional] git deploy trigger -- ##
GIT_DEPLOY_BRANCH=
AUTO_DEPLOY_STATE_DIR=/var/lib/flexit

Cleaning up artifacts to free up space​

This section provides commands to clean up Docker artifacts, including containers and images.

stop all containers​

sudo docker stop $(sudo docker ps -aq)

This command will stop all running containers in your local Docker environment. Be cautious, as this will stop all containers, including those not related to this project.

delete all containers​

sudo docker rm $(sudo docker ps -aq)

This command will remove all containers from your local Docker environment. Be cautious, as this will delete all containers, including those not related to this project.

delete all images​

sudo docker rmi $(sudo docker images -q)

This command will remove all images from your local Docker environment. Be cautious, as this will delete all images, including those not related to this project.

prune to clear up space​

sudo docker system prune -af

This command will remove all stopped containers, unused networks, dangling images, and build cache.

To remove only unused images:

sudo docker image prune -a

To remove unused containers:

sudo docker container prune

To remove unused networks:

sudo docker network prune

To remove unused build cache:

sudo docker builder prune

Working with Volumes​

The docker-compose.yml file uses named volumes to persist data. These volumes are created automatically when you run the application and will persist between container restarts.

For example:

volumes:
  - flexit_webcontent:/opt/flexit/webcontent

This creates a named volume called flexit_webcontent that is used by the flexit-analytics service and is mapped to the /opt/flexit/webcontent directory in the container. Other named volumes hold FlexIt's config, datasets, deployments, and logs, and the content database data. These volumes are owned by root and is not accessible by the user running the container. If you need to access or modify the data in this volume, you can use the docker cp command to copy files to the container from your local machine (or vice/versa). Further documentation from Docker here

For example, to copy a file.txt file from your local machine to the flexit_webcontent volume in the flexit-analytics container:

sudo docker cp file.txt flexit-analytics:/opt/flexit/webcontent/file.txt

You can also get into the container's shell directly to move around the filesystem if needed:

run bash from within the container (linux):

sudo docker exec -it flexit-analytics /bin/bash

To view the volumes:

sudo docker volume ls

To inspect a specific volume:

sudo docker volume inspect <volume_name>

Additional Notes​

Viewing Logs​

To view logs for FlexIt:

sudo docker logs flexit-analytics

Troubleshooting​

1. PostgreSQL Connection Issues​

  • Ensure the DB_USER, DB_PASSWORD, and DB_NAME in .env match the values expected by the PostgreSQL server.

2. Nginx Not Forwarding Requests​

  • Check that the PUBLIC_DNS in .env matches your actual DNS or hostname.
  • Ensure no other service is using the Nginx ports (NGINX_HTTP_PORT and NGINX_HTTPS_PORT, default 80 and 443).

3. FlexIt Not Starting​

  • Review logs:

    sudo docker logs flexit-analytics

  • If the log shows an encryption key error, FLEXIT_ENCRYPTION_KEY must be exactly 32 characters.