Docker

Docker usage is facilitated with ClientCal as described in this document.

Table of Contents

• Docker Compose application
  • Utility usage examples
  • Troubleshooting
  • Public deployment warning
• Docker images

Docker Compose application

A Docker Compose application is provided in the ClientCal project. It facilitates a containerized deployment without the need to perform the individual "Installation Steps" other than managing web-users with the user manager utility.

System requirements

• Docker version 18.03 or newer
• Docker Compose version 1.19 or newer

Basic usage prerequisite

On the host system, change to the Docker compose application directory

cd docker/compose/clientcal

All command-line examples in this document should be performed on the host system in the the Docker compose application directory.

Starting the containers

docker-compose build
docker-compose up

Utility usage examples

The ClientCal command-line utilities can be executed using docker-compose exec on the "php-fpm" container and specifying the -u clientcal option.

The -u clientcal option should ALWAYS be specified when running the utilities with exec for safety and to avoid host file permission issues.

For example, to run the user-manager-utility...

docker-compose exec -u clientcal php-fpm /var/www/clientcal/bin/web-user.php

An example of creating a labeled backup of the database...

docker-compose exec -u clientcal php-fpm /var/www/clientcal/bin/db-export.php

An example of saving a backup of the database to an arbitrary path on the host system...

docker-compose exec -u clientcal php-fpm /var/www/clientcal/bin/db-export.php --stdout > ~/my-clientcal-backup.sql

Troubleshooting

• Can't find a suitable configuration...

  If you get an error similar to the following:

  ERROR: 
       Can't find a suitable configuration file in this directory or any
       parent. Are you in the right directory?
  
       Supported filenames: docker-compose.yml, docker-compose.yaml

  It means your current directory is not your deployment's "/docker/compose/clientcal" directory.

  • Solution: Change to the Docker compose application directory, for example...

    $ cd ~/clientcal/docker/compose/clientcal

    (if the ClientCal source was copied to the ~/clientcal path)

Container image updates

Containers can be removed and rebuilt without data loss because the ephemeral data and source code is stored on the host system.

It is always best practice to create a database backup before performing updates (i.e. docker-compose exec -u clientcal php-fpm /var/www/clientcal/bin/db-export.php).

An example of updating the MySQL container (to get the latest version of MariaDB and other system updates)...

docker-compose down mysql
docker-compose rm -f php-fpm
docker-compose build mysql
docker-compose start mysql

An example of updating the MySQL container (to get the latest version of MariaDB and other system updates)...

docker-compose down mysql
docker-compose rm -f php-fpm
docker-compose build mysql
docker-compose start mysql

Details

When the Docker Compose application containers are run (via docker-compose up or docker compose start), the following occurs:

• non-ephemerial MySQL data is mounted on the host system
• the database is initialized if starting the first time using the latest schema dump according to db-schema.json
• php-fpm starts, and is available to nginx
• nginx starts, and the ClientCal application is available on the local system
  • Default Entrypoint URL: http://localhost:8080
• PHP errors are logged to the terminal as they occur (as long as the 'php-fpm' container is attached to your terminal, i.e. docker-compose up)
• nginx errors are logged to the terminal as they occur (as long as the 'nginx' container is attached to your terminal, i.e. docker-compose up)

This configuration uses the /docker/compose/clientcal/docker-compose.yml file.

Public deployment warning

This Docker Compose application IS NOT SUITABLE FOR PUBLIC DEPLOYMENT unless extra steps are taken to provision SSL (https).

Examples of how to accomplish a safe public deployment with Docker:

• deploying a separate public facing HTTP server with SSL that is configured to be a reverse proxy to Docker Compose application's docker network port 8080
• deploying a separate public facing HTTP server with SSL that is configured to use Fast-CGI over the Docker Compose application's docker network port 9000

Docker images

The following images facilitate ClientCal usage with Docker.

• php
• mariadb

PHP docker image

• php/Dockerfile

The "php" Docker image contains all dependencies for running the ClientCal web application. It is suitable for stand-alone use (i.e. docker run ...) or in conjunction with docker-compose (such as configured in the "docker environment" included in this project). It uses alpine linux and the PHP Repositories for Alpine - by CODECASTS for php related packages.

MariaDB docker image

• mariadb/Dockerfile

The "mariadb" Docker image provides a MariaDB service suitable for use with the "docker-compose environment" included in this project. It uses the official mariadb image with some user permissions tweaks to better facilitate executing seed scripts and saving non-ephemerial data to the host.