6. Docker Containerization

This document describes how the VPL Jail System supports Docker containerization and how to configure it.

6.1. Docker Support

New in version 4.0.0.

The VPL Jail System introduces support for running within Docker containers starting from version 4.0.0. This feature provides a flexible way to deploy and manage VPL Jail Servers in isolated, reproducible environments, suitable for both development and production.

6.1.1. Key Features

  • Containerized Operation: VPL Jail Server can run seamlessly inside Docker containers, supporting both privileged and non-privileged modes. By default, the non-privileged mode is used for improved security.
  • Auto-detection: The server automatically detects when it is running inside a container and adjusts behavior accordingly.
  • Multiple Docker Configurations: Several Dockerfiles and Compose files are provided to support various deployment scenarios, including HTTP-only, HTTPS, and automatic certificate management using Let’s Encrypt.

6.1.2. Dockerfiles and Compose Files

The following Dockerfiles are included in the project root:

  • Dockerfile.no_https Provides HTTP support only (no HTTPS).
  • Dockerfile Enables both HTTP and HTTPS support. Requires providing your own certificates or using self-signed certificates.
  • Dockerfile.letsencrypt Enables HTTP and HTTPS support with automatic certificate generation via Let’s Encrypt.

For each Dockerfile, there is a corresponding Docker Compose file to simplify setup:

  • compose.no_https.yaml
  • compose.yaml
  • compose.letsencrypt.yaml

These files are located in the project root and provide example configurations for deploying the VPL Jail System under different scenarios.

6.1.3. Docker Images

Pre-built Docker images of the VPL Jail System are available on Docker Hub under the jcrodriguezvpl account. Images are provided for different operating systems, each including a full suite of development software. For example, jail-fedora-full provides a Fedora-based image with all supported development tools.

Note

It is recommended to use the provided Compose files as a starting point for your deployments. You may further customize the configuration as needed.

6.1.4. Deployment Scenarios

  • Privileged Mode: Use this mode when you want the VPL Jail Service to take responsibility for security within the container.
  • Non-Privileged Mode (Default): Suitable for most scenarios. The VPL Jail System operates with restricted privileges.
  • HTTPS with Let’s Encrypt: The Dockerfile.letsencrypt and compose.letsencrypt.yaml enable automated certificate provisioning. Use the CERTBOT_WEBROOT_PATH configuration parameter to support challenge-based certificate validation.

6.1.5. Environment Variable Configuration

All VPL Jail System configuration parameters can be set using environment variables, which take precedence over values in the configuration file. Prefix environment variables with VPL_JAIL_ and use the corresponding configuration parameter name.

Example:

export VPL_JAIL_PORT=8000

This will set the server port to 8000.

6.1.6. Getting Started with Docker

  1. Clone the repository:

    git clone https://github.com/jcrodriguez-dis/vpl-jail-system
cd vpl-jail-system

  2. Choose your Dockerfile and Compose file: Select the Dockerfile and Compose file matching your deployment scenario.

  3. Build and Run with Docker Compose: For example, to deploy with HTTPS and Let’s Encrypt:

    docker compose -f compose.letsencrypt.yaml up --build

    Or for HTTP only:

    docker compose -f compose.no_https.yaml up --build

  4. Configure Environment Variables: Set any desired configuration parameters before starting the container, either in an .env file or directly in your Compose file.

  5. Default Build Options

    The default build options are set in the Dockerfile and can be overridden by environment variables or in the Compose file.

    The default build options include the following settings:

    VPL_JAIL_PORT=80
VPL_JAIL_SECURE_PORT=443
VPL_JAIL_JAILPATH=/
VPL_CERTIFICATES_DIR=/etc/vpl/ssl
VPL_JAIL_SSL_CERT_FILE=/etc/vpl/ssl/fullchain.pem
VPL_JAIL_SSL_KEY_FILE=/etc/vpl/ssl/privkey.pem

  6. Creating the Container

    To disable HTTPS, set VPL_JAIL_SECURE_PORT=0. Otherwise, you must provide the SSL public certificate and private key files to the container by setting fullchain.pem and privkey.pem in the volume /etc/vpl/ssl. You can use the docker cp command to upload the certificates to your container. Other important parameters include VPL_JAIL_URLPATH=/yoursecret and VPL_JAIL_TASK_ONLY_FROM=your_Moodle_IP.

Example of a container with HTTPS using Ubuntu full:

docker volume create certs
export VPL_JAIL_URLPATH=/secret
docker run -d --restart always \
    --name vpl-jail \
    -p 443:443 \
    -e VPL_JAIL_URLPATH \
    -v certs:/etc/vpl/ssl \
    jcrodriguezvpl/jail-ubuntu-full

docker cp privkey.pem vpl-jail:/etc/vpl/ssl
docker cp fullchain.pem vpl-jail:/etc/vpl/ssl
docker restart vpl-jail