ESCTL provides a containerized deployment path using Docker and Docker Compose, allowing you to quickly spin up the entire software stack including the controller, database, and identity provider.

Architecture

The following diagram illustrates how the Docker containers interact with each other and the physical hardware nodes.

graph TD subgraph "Docker Host" C[Controller Container] D[(MariaDB Container)] L[OpenLDAP Container] A[phpLDAPadmin Container] end subgraph "Hardware" N1[Door Controller 1] N2[Door Controller 2] end C --- D C --- L A --- L N1 --- C N2 --- C style C fill:#0f6e56,color:#fff

Component Overview

The Docker environment consists of several interconnected services:

  • Controller (esctl/controller): The main controller servicing esctl nodes.
  • Database (mariadb): Stores system logs and access events.
  • Identity Provider (esctl/openldap): Manages users, groups, and security tokens.
  • LDAP Admin (phpldapadmin): A web-based interface for managing the LDAP directory.

Getting Started

The Docker orchestration files are located in server/trunk/docker/esctl/.

1. Configuration

Before starting the services, you must create a .env file from the provided template:

cd server/trunk/docker/esctl/
cp .env.template .env

Edit the .env file to set your specific passwords, domain names, and database names.

2. Launching the Stack

Use Docker Compose to build (if necessary) and start all containers in the background:

docker-compose up -d

Environment Variables

The controller image is highly configurable via environment variables. Key variables include:

Variable Description Default
ESCTL_DB_HOST Hostname of the database container. db
ESCTL_DB_NAME Name of the MySQL database. esctl
ESCTL_LDAP_SERVER URL of the LDAP server. ldap://ldap/
ESCTL_LDAP_BASE_DN Base Distinguished Name for searches. dc=example,dc=hosted...
ESCTL_TOKEN_HASH_SECRET Secret key for hashing security tokens. MyTopS3cr3t...

Advanced Building

If you are building the controller image from source, the Dockerfile supports multi-stage builds and requires git credentials to perform a sparse checkout of the repository:

# Build with custom git credentials
docker-compose build --build-arg BUILD_GIT_USERNAME=myuser --build-arg BUILD_GIT_PASSWORD=mypass

Monitoring & Logs

You can monitor the output of the controller and other services using standard Docker commands:

docker-compose logs -f controller

The controller also redirects error logs to /var/log/esctl_errors inside the container by default.