How to interact with Docker

❗️

Interacting with Docker requires authentication, see How to authenticate to the API.

Introduction

This how-to guide shows all the relevant endpoints to start an nginx Docker container exposed on TCP port 8080 on the SecureEdge.

The steps below assume that there is at least one image present in the SecureEdge's Docker registry. Furthermore, the steps assume your SecureEdge's IP address is 192.168.140.1 and your Docker image is nginx:latest. Substitute where necessary in the commands below if your values differ.

See Running custom Docker applications on the SecureEdge Pro for a detailed guide, but as a quick summary the following should get you up and running:

1. Make sure your Docker daemon is configured correctly to push Docker images to an insecure registry. This only needs to be done once. Assuming your SecureEdge's IP address is 192.168.140.1, add the following to /etc/docker/daemon.json:

{
    "insecure-registries": [
      "192.168.140.1:5000"
    ]
}

2. Push the nginx image to the SecureEdge:

# Pull the latest `nginx` image for the `linux/arm64/v8` platform.
docker pull nginx --platform linux/arm64/v8
# Tag the `nginx` image and push it to the <<secure-edge-name>>'s Docker registry.
docker tag nginx 192.168.140.1:5000/nginx
docker push 192.168.140.1:5000/nginx

List all Docker images

To verify that the push was successful, use the /api/v1/docker/images endpoint:

curl --request GET \
     --url 'http://192.168.140.1:80/api/v1/docker/images' \
     --cookie 'session.jar'

[
    {
        "name": "nginx",
        "tag": "latest"
    }
]

Retrieve the details of a Docker image

Use the /api/v1/docker/images/<image_name>/<image_tag>/details endpoint to gain some extra information about the image, where:

• <image_name> corresponds to your Docker image, e.g. nginx
• <image_tag> corresponds to your Docker tag, e.g. latest

curl --request GET \
     --url 'http://192.168.140.1:80/api/v1/docker/images/nginx/latest/details' \
     --cookie 'session.jar'

{
    "size": 69622746,
    "platforms": [
        "linux/arm64/v8"
    ],
    "error": null
}

Create a Docker container

Now that we have an image on the SecureEdge's Docker registry, we can use the /api/v1/docker/containers endpoint to create the container, where:

• container and image are mandatory
• ports, volumes, and networks are optional and may be empty []

Note that this only creates a container, but does not start it yet.

curl --request POST \
     --url 'http://192.168.140.1:80/api/v1/docker/containers' \
     --cookie 'session.jar' \
     --header 'Content-Type: application/json' \
     --data '
     {
         "container": {
             "name": "nginx"
         },
         "image": {
             "name": "nginx",
             "tag": "latest"
         },
         "ports": [
             {
                 "source": 80,
                 "destination": 8080,
                 "protocol": "tcp"
             }
         ],
         "volumes": [],
         "networks": [
             {
                 "name": "machine-builder"
             }
         ],
         "environment_variables": []
     }'

Each port allows the same values as you'd expect from the docker command line's publish option, e.g. the above example would correspond to --publish 80:8080/tcp.

Each network is automatically created when the first container that uses it is created, and automatically removed when the last container that uses it is removed.

The web interface of the <<secure-edge-name>> automatically creates each container with the machine-builder network. All containers in the same network are allowed to communicate with each other using the container name as host name.

📘

Network Isolation

If you would like to isolate container A from containers B and C, where A is not allowed to communicate with either B or C, but B and C are allowed to communicate with each other, then create container A with e.g. network a (or no network at all), and create container B and C with e.g. network b-and-c.

🚧

Response Code

Creating a container can take a long time when its the first container that uses a certain image, because that image needs to be copied from the SecureEdge's container registry to Docker's own image cache. If the Docker image is very large we expect a 504: Gateway Timeout because creation will not finish before the HTTP request times out. The container creation will continue in the background and listing all Docker containers after a short while should show the container.

On subsequent container creations the image is already in Docker's own cache, so the creation is fast and we expected a 200: OK.

❗️

You cannot PATCH a created container. If you would like to modify your container, you will need to remove and recreate it with the options you want.

List all Docker containers

To verify that our container was correctly created, use the /api/v1/docker/containers endpoint:

curl --request GET \
     --url 'http://192.168.140.1:80/api/v1/docker/containers' \
     --cookie 'session.jar'

[
    {
        "name": "nginx"
    }
]

Retrieve the status of a Docker container

To verify that our container is currently in the created state, use the /api/v1/docker/containers/<container_name>/status endpoint, where:

• container_name corresponds to your Docker container name, e.g. nginx

curl --request GET \
     --url 'http://192.168.140.1:80/api/v1/docker/containers/nginx/status' \
     --cookie 'session.jar'

{
    "running_state": "created"
}

Retrieve the configuration of a Docker container

To verify that our container has the configuration we want, use the /api/v1/docker/containers/<container_name>/configuration endpoint, where:

• container_name corresponds to your Docker container name, e.g. nginx

curl --request GET \
     --url 'http://192.168.140.1:80/api/v1/docker/containers/nginx/configuration' \
     --cookie 'session.jar'

{
    "container": {
        "name": "nginx"
    },
    "image": {
        "name": "nginx",
        "tag": "latest"
    },
    "ports": [
        {
            "source": 80,
            "destination": 8080,
            "protocol": "tcp"
        }
    ],
    "volumes": [],
    "networks": [
        {
            "name": "bridge"
        },
        {
            "name": "machine-builder"
        }
    ],
    "environment_variables": [
        {
            "key": "PATH",
            "value": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
        },
        {
            "key": "NGINX_VERSION",
            "value": "1.27.3"
        },
        {
            "key": "NJS_VERSION",
            "value": "0.8.7"
        },
        {
            "key": "NJS_RELEASE",
            "value": "1~bookworm"
        },
        {
            "key": "PKG_RELEASE",
            "value": "1~bookworm"
        },
        {
            "key": "DYNPKG_RELEASE",
            "value": "1~bookworm"
        }
    ]
}

Start a Docker container

If everything looks good, we can start the container using the /api/v1/docker/containers/<container_name>/start endpoint, where:

• container_name corresponds to your Docker container name, e.g. nginx

curl --request POST \
     --url 'http://192.168.140.1:80/api/v1/docker/containers/nginx/start' \
     --cookie 'session.jar'

Stop a Docker container

Before we can remove a Docker container, we first need to stop it using the /api/v1/docker/containers/<container_name>/stop endpoint, where:

• container_name corresponds to your Docker container name, e.g. nginx

curl --request POST \
     --url 'http://192.168.140.1:80/api/v1/docker/containers/nginx/stop' \
     --cookie 'session.jar'

Remove a Docker container

Now that the Docker container is stopped, we we can remove it using the /api/v1/docker/containers/<container_name> endpoint, where:

• container_name corresponds to your Docker container name, e.g. nginx

curl --request DELETE \
     --url 'http://192.168.140.1:80/api/v1/docker/containers/nginx' \
     --cookie 'session.jar'