Simplicité on Docker

Simplicité® instances can easily be deployed on the Docker engine.

Prerequisites

Configure a Linux server with Docker (e.g. with recent Linux distributions this is straightforward as Docker is part of the distributions) or get an account at a cloud provider allowing Docker images deployments.

Take a look at the Docker documentation for details.

Run a Simplicité® platform container

Introduction

To run a Simplicité® platform container you can either use one of our pre-built images as is or build a custom image that fits your custom needs.

Use the pre-built platform images

Pre-built platform images including the latest Simplicité® intances are available and can be run as is.

This is the best/normal approach if you don't have specific needs.

These images are private on our DockerHub registry, please contact us to get access to these images.

Build a custom image from the server image

If, for some good reasons, you can't use one of the above pre-built images as is you can build your own custom image:

or (not recommended except for very specific requirements and reserved to Simplicité experts only):

Note: if your server has no access to DockerHub you can still get the image manually by saving it on a server which has access (docker save simplicite/<server|platform[:<tag>]> > simplicite-<server|platform>[-<tag>].tar), then transfer it to yor target server, then load it on this server's local docker images registry (docker load < simplicite-<server|platform>[-<tag>].tar)

Basic procedure on CentOS 7

On an "out of the box" CentOS 7 server you can start a clean & fresh Simplicité® sandbox instance with the folowing commands in only few seconds:

First, install the standard Docker service:

sudo yum update
sudo yum install docker
sudo systemctl enable docker
sudo systemctl start docker

Note: by default Docker is allowed to change the firewall rules to open exposed ports. To disable this behavior you need to edit /usr/lib/systemd/system/docker.service cartridge file and add --iptables=false to the ExecStart command.

Then pull the platform image and run an ephemeral container from this image:

sudo docker login
sudo docker pull simplicite/platform
sudo docker run -it --rm -name <myapp> -p 80:8080 simplicite/platform[:<tag>]

Note: to make the docker container running permanently (and restarting at reboot) use -d --restart=always instead of -it --rm

The instance is then available on http://<your server IP address or hostname>

Basic procedure on Debian 9

On an "out of the box" Debian 9 server you can start a clean & fresh Simplicit√©® sandbox instance with the folowing commands in only few seconds:

Install the up-to-date Docker-CE service:

sudo apt-get update
sudo apt-get -y remove docker docker-engine docker.io
sudo apt-get install -y apt-transport-https ca-certificates wget software-properties-common
wget https://download.docker.com/linux/debian/gpg
sudo apt-key add gpg
echo "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | sudo tee -a /etc/apt/sources.list.d/docker.list
sudo apt-get update
sudo apt-get -y install docker-ce
sudo systemctl start docker
sudo systemctl enable docker

Pull the platform image and run an ephemeral container:

sudo docker login
sudo docker pull simplicite/platform
sudo docker run -it --rm -name <myapp> -p 80:8080 simplicite/platform[:<tag>]

Note: to make the docker container running permanently (and restarting at reboot) use -d --restart=always instead of -it --rm

The instance is then available on http://<your server IP address or hostname>

Procedure on managed cloud platforms

Please refer to your cloud provider's documentation to learn how to deploy containers on their specific infrastructures.

Tags

There are several variants of the prebuilt images: simplicite/platform[:<tag>].

See our private DockerHub registry for details.

Exposed ports

The prebuilt images are configured to exposes the following ports for different usage:

Run variants

See DockerHub for run instructions of the standard pre-built iamges.

Run with an embedded HSQLDB database

sudo docker run\
    [-it --rm | -d [--restart=always]]\
    -name <myapp>\
    -p <public port, e.g. 8080>:8080\
    [-p <secured HTTP port, e.g. 8443>:8443]\
    [-e SSL=true -p <SSL port, e.g. 8444>:8444 [--mount=type=bind,source=<host folder in which is myserver.jks>,target=/usr/local/tomcat/cert -e KEYSTORE_FILE=/usr/local/tomcat/cert/myserver.jks [-e KEYSTORE_PASSWORD=<my keystore password, defaults to "password">]]]\
    [-e AJP=true -p [127.0.0.1:]<AJP port, e.g. 8009>:8009]\
    [-e JPDA=true -p [127.0.0.1:]<JPDA port, e.g. 8000>:8000]\
    [-e JMX=true -p [127.0.0.1:]<JMX port, e.g. 8555>:8555]\
    [-e CORS=true]\
    [-e API_EXTRA_PATTERNS=<comma-separated list of extra URI patterns to be considered as services URI, e.g. "myapis/myservice1,myotherapi/myservice2">]
    [-p [127.0.0.1:]<admin port, e.g. 8005>:8005]\
    simplicite/platform[:tag]

The database files and the dociments are stored on the file system within the container, if you do nothing in particular this embedded data is thus ephemereal (it won't survive if you replace the container when upgrading the platform for instance) this is not what you want in most cases.

If you want the embedded data to persist you must map the folders containing the database files and the documents as named volumes.

You first need to create these named volumes (prior to first start of the container), this has to be done only once:

sudo docker volume create <myapp>_db
sudo docker volume create <myapp>_dbdoc

Then you need to run your container with the appropriate -v volumes mappings, e.g:

sudo docker run\
    (...)\
    -v <myapp>_db:/usr/local/tomcat/webapps/ROOT/WEB-INF/db\
    -v <myapp>_dbdoc:/usr/local/tomcat/webapps/ROOT/WEB-INF/dbdoc\
    simplicite/platform[:tag]

Note: you can also use this volume strategy with dbdoc only along with an external database not configured to store documents as BLOBs. This approach is only suitable for very particular needs (e.g. if you want to have a file system access to your documents, etc.)

Run with an external database

Both the server and prebuilt images allows you to start a container using an external database using the following DB_* environment variables:

sudo docker run\
    (...)\
    -e DB_SETUP=<setup database if empty = true|false>\
    -e DB_VENDOR=<database vendor = mysql|postgresql|oracle|mssql>\
    -e DB_HOST=<hostname or IP address>\
    -e DB_PORT=<port, defaults to 3306 for mysql, 5432 for postgresql, 1521 for oracle or 1433 for mssql>\
    -e DB_USER=<database username>\
    -e DB_PASSWORD=<database username's password>\
    -e DB_NAME=<database name>\
    simplicite/platform[:tag]

Note If you plan to use a database server running on the host machine you need to get the appropriate IP address to pass as DB_HOST environment variable (using 127.0.0.1 will not work unless you use --net=host which only makes sense in particular cases).

To get this adress run the following command:

ip -4 addr show docker0 | grep -Po 'inet \K[\d.]+'

The result is usually 172.17.0.1 but it may vary.

Also make sure your database is configured to allow connections on this IP and its port and that the firewall considers the docker0 interface as trusted, this can be ensured by:

sudo firewall-cmd --permanent --zone=trusted --add-interface=docker0
sudo firewall-cmd --reload

Using an external database is the typical approach if you use prebuilt images (for which upgrading means starting a new container).

The DOC_DIR system parameter is by default set to BLOB for external databases (this means documents are stored in the database as BLOBs). This is required otherwise the documents will be stored on the ephemeral local filesystem of the container and will thus be potentially lost (unless you have mapped the folder containing the documents as a named volume. see bellow, this is not recommended unless you have to handle huge volumes of documents).

Run with volumes for server and platform logs

The logs folders of both the server and the platform are stored on the file system within the container, if you do nothing in particular these folders are thus ephemereal (they won't survive if you replace the container when upgrading the platform for instance).

If you want the log folders to persist you must map the 2 log folders as a named volumes.

You first need to create these named volumes (prior to first start of the container), this has to be done only once:

sudo docker volume create <myapp>_server_logs
sudo docker volume create <myapp>_platform_logs

Then you need to run your container with the appropriate -v volumes mapping, e.g:

sudo docker run (...) -name <myapp>\
    -v <myapp>_server_logs:/usr/local/tomcat/logs\
    -v <myapp>_platform_logs:/usr/local/tomcat/webapps/ROOT/WEB-INF/log\
    simplicite/platform[:tag]

Run with a volume for modules' Git repository

The Git repository of the modules are stored on the file system within the container, if you do nothing in particular these Git repository are thus ephemereal (they won't survive if you replace the container when upgrading the platform for instance).

If you want your modules' Git repository to persist you must map the Git base folder as a named volume.

You first need to create this named volume (prior to first start of the container), this has to be done only once:

sudo docker volume create <myapp>_git

Then you need to run your container with the appropriate -v volume mapping, e.g:

sudo docker run (...) -name <myapp>\
    -v <myapp>_git:/usr/local/tomcat/webapps/ROOT/WEB-INF/git\
    simplicite/platform[:tag]

Run on a specific time zone

It is also possible to specify in which timezone Tomcat will run by using -e TOMCAT_TIMEZONE=<time zone string e.g. Europe/Paris>.

If not specified it will run in the UTC time zone.

Run with custom JVM options

It is also possible to pass custom options to the JVM by using -e JAVA_OPTS=<java options>

E.g. content of JAVA_OPTS:

Run behind a reverse proxy

the exposed HTTP ports 8080/8443 are designed to be used with an HTTP/HTTPS reverse proxy such as NGINX, Apache, Lighttpd, Traefik, ...:

Warning: If you use the 8080 port with an HTTPS endpoint or the 8443 port with an HTTP endpoint it will not work as expected.

The exposed AJP port 8009 is designed to be used with a Apache reverse proxy (for both HTTP and HTTPS endpoints).

So depending on the reverse proxy you plan to use you have to use either -p <local port e.g. 8080>:8080 -p <local port e.g. 8443>:8443 or -p <local AJP port, e.g. 8009>:8009 in you docker run command.

Run with an external platform Git URL within the container for self-upgrading

The server container can be bound to an external platform instance template's Git repository URL (using the GIT_URL environment variable) which an be local (typically a local clone path mounted as a read only volume) or remote (typically the default URL of our Git repository: https://<your username>:<your password>@platform.git.simplicite.io/template-<version>.git).

When configured like this any change on the repository is automatically applied to the deployed instance within the container when restarting it.

warning: dont use this feature when using an embedded HSQLDB database

Run with Docker Compose tool

You can use the Docker Compose tool to start an database container and a Simplicité® instace container.

Prerequisites

The only packages you need are Docker and the Docker Compose tool:

sudo yum install docker docker-compose

Then you can enable and start the Docker daeamon and login to DockerHub with an account allowed to pull the private pre-built images simplicite/platform[:<tag>]:

sudo systemctl enable docker
sudo systemctl start docker
sudo docker login

HSQLDB

Create the following docker-compose.yml file:

version: "3"
services:
  web:
    image: simplicite/platform[:<tag, e.g. latest>]
    restart: always
    container_name: <myapp>
    ports:
      - 80:8080
    volumes:
      - <myapp>-db:/usr/local/tomcat/webapps/ROOT/WEB-INF/db
      - <myapp>-dbdoc:/usr/local/tomcat/webapps/ROOT/WEB-INF/dbdoc
      - <myapp>-git:/usr/local/tomcat/webapps/ROOT/WEB-INF/git
volumes:
  <myapp>-db:
  <myapp>-dbdoc:
  <myapp>-git:

Start the containers by:

sudo docker-compose up [-d]

Note: if you want to enable SSL you need to add items in the service's ports, environment and volumes sections:

version: "3"
services:
  web:
    image: simplicite/platform[:<tag, e.g. latest>]
    restart: always
    container_name: <myapp>
    ports:
      - 80:8080
      - 443:8444
    environment:
      SSL: "true"
      KEYSTORE_FILE: "/usr/local/tomcat/cert/myapp.jks"
      KEYSTORE_PASSWORD: "mypassword"
    volumes:
      - <myapp>-db:/usr/local/tomcat/webapps/ROOT/WEB-INF/db
      - <myapp>-dbdoc:/usr/local/tomcat/webapps/ROOT/WEB-INF/dbdoc
      - <myapp>-git:/usr/local/tomcat/webapps/ROOT/WEB-INF/git
      - /etc/ssl:/usr/local/tomcat/cert:ro
volumes:
  <myapp>-db:
  <myapp>-dbdoc:
  <myapp>-git:

In the above example the server certificate's keystore file as located as /etc/ssl/myapp.jks on the host machine and its password is mypassword. See this document to learn how to build such a keystore file.

MySQL/MariaDB

Create the following docker-compose.yml file:

version: "3"
services:
  db:
    image: mysql:latest
    # or image: mariadb:latest (if you prefer MariaDB)
    restart: always
    container_name: <myapp>-database
    command: --default-authentication-plugin=mysql_native_password
    environment:
      MYSQL_ROOT_PASSWORD: "simplicite"
      MYSQL_DATABASE: "simplicite"
      MYSQL_USER: "simplicite"
      MYSQL_PASSWORD: "simplicite"
    #Uncomment this if you want to access the database from the local host
    #ports:
    #- 127.0.0.1:3306:3306
    volumes:
    - <myapp>-db:/var/lib/mysql
  web:
    image: simplicite/platform[:<tag, e.g. latest>]
    restart: always
    container_name: <myapp>-webapp
    environment:
      DB_SETUP: "true"
      DB_VENDOR: "mysql"
      DB_HOST: db
      DB_USER: "simplicite"
      DB_PASSWORD: "simplicite"
      DB_NAME: "simplicite"
      DB_WAIT: 10
    ports:
     - 80:8080
    volumes:
    - <myapp>-git:/usr/local/tomcat/webapps/ROOT/WEB-INF/git
    depends_on:
    - db
volumes:
  <myapp>-db:
  <myapp>-git:

Start the containers by:

sudo docker-compose up [-d]

Note: if you want to enable SSL see above.

PostgreSQL

Create the following docker-compose.yml file:

version: "3"
services:
  db:
    image: postgres:latest
    restart: always
    container_name: <myapp>-database
    environment:
      POSTGRES_USER: "simplicite"
      POSTGRES_PASSWORD: "simplicite"
      POSTGRES_DB: "simplicite"
    #Uncomment this if you want to access the database from the local host
    #ports:
    #- 127.0.0.1:5432:5432
    volumes:
    - <myapp>-db:/var/lib/postgresql/data
  web:
    image: simplicite/platform[:<tag, e.g. latest>]
    restart: always
    container_name: <myapp>-webapp
    environment:
      DB_SETUP: "true"
      DB_VENDOR: "postgresql"
      DB_HOST: db
      DB_USER: "simplicite"
      DB_PASSWORD: "simplicite"
      DB_NAME: "simplicite"
      DB_WAIT: 10
    ports:
     - 80:8080
    volumes:
    - <myapp>-git:/usr/local/tomcat/webapps/ROOT/WEB-INF/git
    depends_on:
    - db
volumes:
  <myapp>-db:
  <myapp>-git:

Start the containers by:

sudo docker-compose up [-d]

Note: if you want to enable SSL see above.

Upgrade containers

The commands to upgrade containers managed by Docker Compose tool are:

sudo docker-compose pull
sudo docker-compose up [-d]
sudo docker image prune -a -f

Run on a Kubernetes cluster

See this document.

Troubleshooting

If you experience network issues within your container it may be a DNS configuration issue that you can solve by adding an explict DNS serveur IP address e.g. --dns=8.8.8.8