Docker

Installation

Docker ComposeDocker CLI

Docker Compose is the recommended way to run Enclave and an Enclave container should be configured to run in one of two modes: Host or Service networking.

Host network mode allows the Enclave container to share the IP address of the operating system which is running the Enclave container. This is useful when running Enclave on hypervisor hosts which have multiple containerised, and non-containerised applications that need to be made shared with other connected systems running Enclave.

Service network mode on the other hand, isolates the Enclave container from the Docker host, instead causing it to share a private network stack only with one or more other containers. The Service networking mode allows administrators to run containers that are isolated from the LAN, and can only be reached using Enclave. Use this mode to microsegment access to specific containers.

Host Network ModeService Network Mode

If you use the Host network mode for an Enclave container, that container's network stack isn't isolated from the Docker host (the container shares the host's networking namespace), and the container doesn't get its own LAN IP-address. For example, any application that binds to the host's IP address can be made available to other connected systems running Enclave, even if they are not containerised applications.

Note that since Host mode containers do not have their own IP-addresses, port-mapping isn't required, and doesn't take effect if used.

1. Create a docker-compose.yml file:

   version: "3.8"
   
   services:
     enclave:
       container_name: enclave
       image: enclavenetworks/enclave
       network_mode: host
       cap_add:
         - NET_ADMIN
       devices:
         - /dev/net/tun
       environment:
         ENCLAVE_ENROLMENT_KEY: ${ENCLAVE_ENROLMENT_KEY}
       volumes:
         - enclave-config:/etc/enclave/profiles
         - enclave-logs:/var/log/enclave
   
   volumes:
     enclave-config:
     enclave-logs:
   

2. Define the ENCLAVE_ENROLMENT_KEY environment variable for your docker compose file using a suitable Enrolment Key from the Enclave Portal.

   $ export ENCLAVE_ENROLMENT_KEY=XXXXX-XXXXX-XXXXX-XXXXX-XXXXX
   

   Production Use

   Enclave Enrolment Keys are secret values. Be sure to inject the Enrolment Key into your docker compose file safely using environment variables or secrets management tooling.

3. Bring the container up using

   $ docker compose up -d
   

The service network mode (specified using the network_mode: directive) allows the Enclave container to share the network stack with one or more other containers, rather than the host.

This means the Enclave container does not have its own network namespace and instead shares an IP address and network interface with other containers. Unlike host network mode, which shares the network stack with the host, this mode shares it with another service, allowing the containers to communicate directly over localhost while maintaining isolation from the host's network.

This mode allows private access to specific and individual containers via Enclave without exposing any ports on the host.

1. Create a docker-compose.yml file

   version: "3.8"
   
   services:
     example-webserver:
       image: nginxdemos/hello
   
     enclave:
       container_name: enclave
       image: enclavenetworks/enclave
       network_mode: service:example-webserver
       cap_add:
         - NET_ADMIN
       devices:
         - /dev/net/tun
       environment:
         ENCLAVE_ENROLMENT_KEY: ${ENCLAVE_ENROLMENT_KEY}
       volumes:
         - enclave-config:/etc/enclave/profiles
         - enclave-logs:/var/log/enclave
   
   volumes:
     enclave-config:
     enclave-logs:
   

2. Replace example-webserver service and container with your own.

   Detail

   Notice the two services, example-webserver and enclave. Also notice that network_mode, which is set in the enclave container, refers to service:example-webserver. This is the directive which binds the network stack of the two services together. Enclave should always be the service which has the network_mode configured, in reference to the service you wish to make available via Enclave.

3. Define the ENCLAVE_ENROLMENT_KEY environment variable for your docker compose file using a suitable Enrolment Key from the Enclave Portal.

   $ export ENCLAVE_ENROLMENT_KEY=XXXXX-XXXXX-XXXXX-XXXXX-XXXXX
   

   Production Use

   Enclave Enrolment Keys are secret values. Be sure to inject the Enrolment Key into your docker compose file safely using environment variables or secrets management tooling.

4. Bring the container up using

   $ docker compose up -d
   

Enclave can be started using the docker CLI:

1. Define the ENCLAVE_ENROLMENT_KEY environment variable for your docker compose file using a suitable Enrolment Key from the Enclave Portal.

   $ export ENCLAVE_ENROLMENT_KEY='XXXXX-XXXXX-XXXXX-XXXXX-XXXXX'
   

   Production Use

   Enclave Enrolment Keys are secret values. Be sure to inject the Enrolment Key into your docker compose file safely using environment variables or secrets management tooling.

2. Ensure you have the latest version, and use docker run to bring the container up in detached mode:

   $ docker pull enclavenetworks/enclave:latest
   
   $ docker run -d \
                --name enclave \
                --cap-add NET_ADMIN \
                --device /dev/net/tun \
                -e ENCLAVE_ENROLMENT_KEY \
                -v enclave-config:/etc/enclave/profiles \
                -v enclave-logs:/var/log/enclave \
                --network host \
                enclavenetworks/enclave
   

3. Inspect the CLI output from the container

   $ docker logs -f enclave
   

What to do if the install fails

For troubleshooting and errors, use the site search or visit our troubleshooting section to look for information about common error messages. If your installation fails and you are unable to resolve the problem by retrying, please contact support@enclave.io.

Staying up to date

The Enclave software and associated SaaS platform are updated together in tandem. Containers are immutable so any customers running Enclave inside a container may encounter a situation where our control plane and SaaS platform services are updated with new versions, but the version of Enclave running in their Docker containers remains outdated.

This is a situation we'd recommend our customers try to avoid by automatically, or manually establishing a process to ensure they're always running the latest version of Enclave inside a docker container.

Production Use

We recommend using software like Watchtower to ensure Enclave is automatically updated when new versions are released.

You may also consider using Diun, a CLI application to receive notifications when the Enclave image is updated on a Docker registry and manually pull the latest version.