Skip to main content

Starting a Docker container using the API

Prerequisites​

To start a custom Docker container, you will need to have the following:

  • The project ID of an existing project (how to create a project), in which the container hosting feature is available
  • A container image that you want to start. This image may be available in any public or private registry; however, the registry must be reachable from the internet and not hidden behind a firewall.

Defining a private registry (optional)​

If your container image should be loaded from a private registry, you first need to define this registry for the respective project.

You can use the following API operations to manage container registries:

For example, use the POST/v2/projects/{projectId}/registries/ operation to define this new registry:

POST /v2/projects/{projectId}/registries HTTP/1.1
Host: api.mittwald.de
Content-Type: application/json

{
  "credentials": {
    "password": "password",
    "username": "username"
  },
  "description": "My registry",
  "uri": "my-registry.example"
}
See full request reference at: POST/v2/projects/{projectId}/registries/

After a container registry is configured for a project, you can simply use it within that project by prefixing the image name, just as you would with a docker run command.

Starting a container in the default stack​

Containers are run as part of a container stack. A container stack is a collection of containers and volumes that are run together. You can use the following API operations to manage container stacks:

Identify the default stack​

Before starting a container in the default stack, you need to determine the ID of the default stack. For this, list the available stacks in your project by calling the GET/v2/projects/{projectId}/stacks/ endpoint. The default stack will we named default.

Defining the container stack​

When you have identified the default stack, you can define the container stack that you want to start. The following example shows an example request that starts a container with a volume:

PUT /v2/stacks/{stackId} HTTP/1.1
Host: api.mittwald.de
Content-Type: application/json

{
  "services": {
    "mycontainer": {
      "image": "my-registry/my-container:v1.0.1",
      "volumes": [
        "myvolume:/var/www"
      ],
      "command": [
        "command"
      ],
      "entrypoint": [
        "/entrypoint.sh"
      ],
      "environment": {
        "FOO": "bar"
      }
    }
  },
  "volumes": {
    "myvolume": {}
  }
}
See full request reference at: PUT/v2/stacks/{stackId}/

See the documentation on container workloads for more information on how containers, volumes and networks are defined.

Starting a new container stack (planned)​

Starting new container stacks next to the default stack is not supported at the moment.

Connecting domains to containers​

To connect a domain to a running container, you can specify the container as target of an ingress resource. Use the following API operation to create an ingress connected to a container:

Operational tasks​

To manage a container stack's lifecycle, you can use the following API operations: