Using a Private Docker Registry

As of Marathon 1.5, you can upload your private Docker registry credentials to a secret store, then reference them in your app or pod definition. This functionality is only available if you are using the Mesos containerizer. If you are using the Docker containerizer, follow these instructions to use a private Docker registry. If you want to learn how to configure credentials to pull images from the Amazon Elastic Container Registry (AWS ECR) please refer to this blog post.

Step 1: Create a Credentials File

Log in to your private registry manually. This will create a ~/.docker directory and a ~/.docker/config.json file.
```
$ docker login some.docker.host.com
Username: foo
Password:
Email: foo@bar.com
```
Check that you have the ~/.docker/config.json file.
```
$ ls ~/.docker
config.json
```
Your config.json file should look like this, where value of auth is a based64-encoded username:password string. You can generate it using echo -n 'username:password' | base64.
```
{
  "auths": {
      "https://index.docker.io/v1/": {
          "auth": "XXXXX",
          "email": "<your-email>"
      }
  }
}
```
Add the config.json file to a secret store. If you are using Enterprise DC/OS, follow these instructions to add the file to the DC/OS secret store.

Step 2: Add the Secret to your App or Pod Definition

For an Application

Add the following two parameters to your app definition.

A location for the secret in the secrets parameter:

"secrets": {
  "pullConfigSecret": {
    "source": "/mesos-docker/pullConfig"
  }
}

A reference to the secret in the docker.pullConfig parameter:
```
"docker": {
  "image": "mesosphere/inky",
  "pullConfig": {
    "secret": "pullConfigSecret"
  }
}
```
Note: This functionality is only supported with the Mesos containerizer: container.type must be MESOS.

A complete example:

{
  "id": "/mesos-docker",
  "container": {
    "docker": {
      "image": "your/private/image",
      "pullConfig": {
        "secret": "pullConfigSecret"
      }
    },
    "type": "MESOS"
  },
  "secrets": {
    "pullConfigSecret": {
      "source": "/mesos-docker/pullConfig"
    }
  },
  "args": ["hello"],
  "cpus": 0.2,
  "mem": 16.0,
  "instances": 1
}

The Docker image will now pull using the provided security credentials given.

For a Pod

Add the following two parameters to your pod definition.

A location for the secret in the secrets parameter:

"secrets": {
  "pullConfigSecret": {
    "source": "/pod/pullConfig"
  }
}

A reference to the secret in the containers.image.pullConfig parameter:

"containers": [
  {
    "image": {
      "id": "nginx",
      "pullConfig": {
        "secret": "pullConfigSecret"
      },
      "kind": "DOCKER"
    }
  }
]

Note: This functionality is only supported if image.kind is set to DOCKER.

A complete example:

{
  "id": "/pod",
  "scaling": { "kind": "fixed", "instances": 1 },
  "containers": [
    {
      "name": "sleep1",
      "exec": { "command": { "shell": "sleep 1000" } },
      "resources": { "cpus": 0.1, "mem": 32 },
      "image": {
        "id": "nginx",
        "pullConfig": {
          "secret": "pullConfigSecret"
        },
        "kind": "DOCKER"
      },
      "endpoints": [ { "name": "web", "containerPort": 80, "protocol": [ "http" ] } ],
      "healthCheck": { "http": { "endpoint": "web", "path": "/ping" } }
    }
  ],
  "networks": [ { "mode": "container", "name": "my-virtual-network-name" } ],
  "secrets": { "pullConfigSecret": { "source": "/pod/pullConfig" } }
}

Use a Private Docker Registry with the Docker Containerizer

Registry 1.0 - Docker pre 1.6

To supply credentials to pull from a private registry, add a .dockercfg to the uris field of your app. The $HOME environment variable will then be set to the same value as $MESOS_SANDBOX so Docker can automatically pick up the config file.

Registry 2.0 - Docker 1.6 and up

To supply credentials to pull from a private registry, add a docker.tar.gz file to the uris field of your app. The docker.tar.gz file should include the .docker directory and the contained .docker/config.json

Step 1: Compress Docker credentials

Log in to the private registry manually. Login creates a ~/.docker directory and a ~/.docker/config.json file in your home directory.

Info: Executing docker login will append credentials to the file and won't replace the old ones. Credentialas will be stored unencrypted.
```
$ docker login some.docker.host.com
  Username: foo
  Password:
  Email: foo@bar.com
```
Also note that by default, the credentials are not stored in the file, but rather in key store managed by the OS (e.g. oskeychain for OSX, pass for Linux). Make sure the credentials are stored in the file. The new authentication should look like this:
```
"https://some.docker.host.com": {
    "auth": "XXXXX",
    "email": "<your-email>"
}
```
Where value of auth is a based64-encoded username:password string. You can generate it using echo -n 'username:password' | base64.
Compress the ~/.docker directory and its contents.
```
$ cd ~
$ tar -czf docker.tar.gz .docker
```

Verify that both files are in the archive.

$ tar -tvf ~/docker.tar.gz

  drwx------ root/root         0 2015-07-28 02:54 .docker/
  -rw------- root/root       114 2015-07-28 01:31 .docker/config.json

Put the archive file in a location that is accessible to your application definition.
```
$ cp docker.tar.gz /etc/
```
Note: The URI must be accessible by all nodes that will start your application. You can distribute the file to the local filesystem of all nodes, for example via RSYNC/SCP, or store it on a shared network drive like Google Cloud Storage or Amazon S3. Consider the security implications of your chosen approach carefully.

Careful: If you run these commands locally with already installed docker, the resulting tar archive might contain credentials to other registries.

Step 2: Add URI path to app definition

Add the path to the archive file login credentials to the fetch parameter of your app definition.
```
"fetch": [
  {
    "uri": "file:///etc/docker.tar.gz"
  }
]
```

For example:

{  
  "id": "/some/name/or/id",
  "cpus": 1,
  "mem": 1024,
  "instances": 1,
  "container": {
    "type": "DOCKER",
    "docker": {
      "image": "some.docker.host.com/namespace/repo",
      "network": "HOST"
    }
  },
  "fetch": [
    {
      "uri": "file:///etc/docker.tar.gz"
    }
  ]
}

The Docker image will now pull using the provided security credentials given.

More information

Find out how to set up a private Docker registry with DC/OS.