# Containers

## Container

> Example

```json
{
    "autodestroy": "OFF",
    "autorestart": "OFF",
    "bindings": [
        {
            "volume": "/api/infra/v1/user_namespace/volume/1863e34d-6a7d-4945-aefc-8f27a4ab1a9e/",
            "host_path": null,
            "container_path": "/data",
            "rewritable": true
        },
        {
            "volume": null,
            "host_path": "/etc",
            "container_path": "/etc",
            "rewritable": true
        }
    ],
    "cap_add": [
        "ALL"
    ],
    "cap_drop": [
        "NET_ADMIN",
        "SYS_ADMIN"
    ],
    "container_envvars": [
        {
            "key": "DB_1_ENV_DEBIAN_FRONTEND",
            "value": "noninteractive"
        },
        {
            "key": "DB_1_ENV_MYSQL_PASS",
            "value": "**Random**"
        },
        {
            "key": "DB_1_ENV_MYSQL_USER",
            "value": "admin"
        },
        {
            "key": "DB_1_ENV_PATH",
            "value": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
        },
        {
            "key": "DB_1_ENV_REPLICATION_MASTER",
            "value": "**False**"
        },
        {
            "key": "DB_1_ENV_REPLICATION_PASS",
            "value": "replica"
        },
        {
            "key": "DB_1_ENV_REPLICATION_SLAVE",
            "value": "**False**"
        },
        {
            "key": "DB_1_ENV_REPLICATION_USER",
            "value": "replica"
        },
        {
            "key": "DB_1_PORT",
            "value": "tcp://172.16.0.3:3306"
        },
        {
            "key": "DB_1_PORT_3306_TCP",
            "value": "tcp://172.16.0.3:3306"
        },
        {
            "key": "DB_1_PORT_3306_TCP_ADDR",
            "value": "172.16.0.3"
        },
        {
            "key": "DB_1_PORT_3306_TCP_PORT",
            "value": "3306"
        },
        {
            "key": "DB_1_PORT_3306_TCP_PROTO",
            "value": "tcp"
        },
        {
            "key": "DB_ENV_DEBIAN_FRONTEND",
            "value": "noninteractive"
        },
        {
            "key": "DB_ENV_MYSQL_PASS",
            "value": "**Random**"
        },
        {
            "key": "DB_ENV_MYSQL_USER",
            "value": "admin"
        },
        {
            "key": "DB_ENV_PATH",
            "value": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
        },
        {
            "key": "DB_ENV_REPLICATION_MASTER",
            "value": "**False**"
        },
        {
            "key": "DB_ENV_REPLICATION_PASS",
            "value": "replica"
        },
        {
            "key": "DB_ENV_REPLICATION_SLAVE",
            "value": "**False**"
        },
        {
            "key": "DB_ENV_REPLICATION_USER",
            "value": "replica"
        },
        {
            "key": "DB_PASS",
            "value": "szVaPz925B7I"
        },
        {
            "key": "DB_PORT",
            "value": "tcp://172.16.0.3:3306"
        },
        {
            "key": "DB_PORT_3306_TCP",
            "value": "tcp://172.16.0.3:3306"
        },
        {
            "key": "DB_PORT_3306_TCP_ADDR",
            "value": "172.16.0.3"
        },
        {
            "key": "DB_PORT_3306_TCP_PORT",
            "value": "3306"
        },
        {
            "key": "DB_PORT_3306_TCP_PROTO",
            "value": "tcp"
        },
        {
            "key": "DB_DOCKERCLOUD_API_URL",
            "value": "https://cloud.docker.com/api/app/v1/user_namespace/service/c0fed1dc-c528-40c9-aa4c-dc00672ebcbf/"
        }
    ],
    "container_ports": [
        {
            "endpoint_uri": "http://wordpress-stackable-1.admin.cont.dockerapp.io:49153/",
            "inner_port": 80,
            "outer_port": 49153,
            "port_name": "http",
            "protocol": "tcp",
            "published": true,
            "uri_protocol": "http"
        }
    ],
    "cpu_shares": 100,
    "cpuset": "0,1",
    "cgroup_parent": "m-executor-abcd",
    "deployed_datetime": "Thu, 16 Oct 2014 12:04:08 +0000",
    "destroyed_datetime": null,
    "devices": [
        "/dev/ttyUSB0:/dev/ttyUSB0"
    ],
    "dns": [
        "8.8.8.8"
    ],
    "dns_search": [
        "example.com",
        "c1dd4e1e-1356-411c-8613-e15146633640.local.dockerapp.io"
    ],
    "domainname": "domainname",
    "entrypoint": "",
    "exit_code": null,
    "exit_code_msg": null,
    "extra_hosts": [
        "onehost:50.31.209.229"
    ],
    "hostname": "hostname",
    "image_name": "tutum/wordpress-stackable:latest",
    "labels": {
        "com.example.description": "Accounting webapp",
        "com.example.department": "Finance",
        "com.example.label-with-empty-value": ""
    },
    "linked_to_container": [
    	{
    		"endpoints": {
    			"3306/tcp": "tcp://172.16.0.3:3306"
    		},
    		"from_container": "/api/app/v1/user_namespace/container/c1dd4e1e-1356-411c-8613-e15146633640/",
    		"name": "DB_1",
    		"to_container": "/api/app/v1/user_namespace/container/ba434e1e-1234-411c-8613-e15146633640/"
    	}
    ],
    "link_variables": {
        "WORDPRESS_STACKABLE_1_ENV_DB_HOST": "**LinkMe**",
        "WORDPRESS_STACKABLE_1_ENV_DB_NAME": "wordpress",
        "WORDPRESS_STACKABLE_1_ENV_DB_PASS": "szVaPz925B7I",
        "WORDPRESS_STACKABLE_1_ENV_DB_PORT": "**LinkMe**",
        "WORDPRESS_STACKABLE_1_ENV_DB_USER": "admin",
        "WORDPRESS_STACKABLE_1_ENV_DEBIAN_FRONTEND": "noninteractive",
        "WORDPRESS_STACKABLE_1_ENV_HOME": "/",
        "WORDPRESS_STACKABLE_1_ENV_PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
        "WORDPRESS_STACKABLE_1_PORT": "tcp://172.16.0.2:80",
        "WORDPRESS_STACKABLE_1_PORT_80_TCP": "tcp://172.16.0.2:80",
        "WORDPRESS_STACKABLE_1_PORT_80_TCP_ADDR": "172.16.0.2",
        "WORDPRESS_STACKABLE_1_PORT_80_TCP_PORT": "80",
        "WORDPRESS_STACKABLE_1_PORT_80_TCP_PROTO": "tcp",
        "WORDPRESS_STACKABLE_ENV_DB_HOST": "**LinkMe**",
        "WORDPRESS_STACKABLE_ENV_DB_NAME": "wordpress",
        "WORDPRESS_STACKABLE_ENV_DB_PASS": "szVaPz925B7I",
        "WORDPRESS_STACKABLE_ENV_DB_PORT": "**LinkMe**",
        "WORDPRESS_STACKABLE_ENV_DB_USER": "admin",
        "WORDPRESS_STACKABLE_ENV_DEBIAN_FRONTEND": "noninteractive",
        "WORDPRESS_STACKABLE_ENV_HOME": "/",
        "WORDPRESS_STACKABLE_ENV_PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
        "WORDPRESS_STACKABLE_PORT": "tcp://172.16.0.2:80",
        "WORDPRESS_STACKABLE_PORT_80_TCP": "tcp://172.16.0.2:80",
        "WORDPRESS_STACKABLE_PORT_80_TCP_ADDR": "172.16.0.2",
        "WORDPRESS_STACKABLE_PORT_80_TCP_PORT": "80",
        "WORDPRESS_STACKABLE_PORT_80_TCP_PROTO": "tcp"
    },
    "mac_address": "02:42:ac:11:65:43",
    "memory": 1024,
    "memory_swap": 4096,
    "name": "wordpress-stackable",
    "net": "bridge",
    "node": "/api/infra/v1/user_namespace/node/9691c44e-3155-4ca2-958d-c9571aac0a14/",
    "pid": "none",
    "private_ip": "10.7.0.1",
    "privileged": false,
    "public_dns": "wordpress-stackable-1.admin.cont.dockerapp.io",
    "read_only": true,
    "resource_uri": "/api/app/v1/user_namespace/container/c1dd4e1e-1356-411c-8613-e15146633640/",
    "roles": ["global"],
    "run_command": "/run-wordpress.sh",
    "security_opt": [
        "label:user:USER",
        "label:role:ROLE"
    ],
    "service": "/api/app/v1/user_namespace/service/adeebc1b-1b81-4af0-b8f2-cefffc69d7fb/",
    "started_datetime": "Thu, 16 Oct 2014 12:04:08 +0000",
    "state": "Running",
    "stdin_open": false,
    "stopped_datetime": null,
    "synchronized": true,
    "tty": false,
    "user": "root",
    "uuid": "c1dd4e1e-1356-411c-8613-e15146633640",
    "working_dir": "/app"
}
```


A container is a representation of a Docker container in a node.

This is a [namespaced endpoint](#namespaced-endpoints).

### Attributes

Attribute | Description
--------- | -----------
uuid | A unique identifier for the container generated automatically on creation
resource_uri | A unique API endpoint that represents the container
image_name | The Docker image name and tag of the container
bindings | A list of volume bindings that the container has mounted (see table `Container Binding attributes` below)
name | A user provided name for the container (inherited from the service)
node | The resource URI of the node where this container is running
service | The resource URI of the service which this container is part of
public_dns | The external FQDN of the container
state | The state of the container (see table `Container states` below)
synchronized | Flag indicating if the container is synchronized with the current service definition.
exit_code | The numeric exit code of the container (if applicable, `null` otherwise)
exit_code_msg | A string representation of the exit code of the container (if applicable, `null` otherwise)
deployed_datetime | The date and time of the last deployment of the container (if applicable, `null` otherwise)
started_datetime | The date and time of the last `start` operation on the container (if applicable, `null` otherwise)
stopped_datetime | The date and time of the last `stop` operation on the container (if applicable, `null` otherwise)
destroyed_datetime | The date and time of the `terminate` operation on the container (if applicable, `null` otherwise)
container_ports | List of published ports of this container (see table `Container Port attributes` below)
container_envvars | List of user-defined environment variables set on the containers of the service, which will override the container environment variables (see table `Container Environment Variable attributes` below)
labels | Container metadata in form of dictionary
working_dir | Working directory for running binaries within a container
user | User used on the container on launch
hostname | Hostname used on the container on launch
domainname | Domainname used on the container on launch
mac_address | Ethernet device's MAC address used on the container on launch
cgroup_name | Optional parent cgroup for the container.
tty | If the container has the tty enable
stdin_open | If the container has stdin opened
dns | Container custom DNS servers
dns_search | Container custom DNS search domain
cap_add | Container added capabilities
cap_drop | Container dropped capabilities
devices | List of container device mappings
extra_hosts | List of container hostname mappings
secuirty_opt | Labeling scheme of this container
entrypoint | Entrypoint used on the container on launch
run_command | Run command used on the container on launch
cpu_shares | The relative CPU priority of the container (see [Runtime Constraints on CPU and Memory](../../engine/reference/run/#runtime-constraints-on-cpu-and-memory) for more information)
cpuset | CPUs in which execution is allowed
memory | The memory limit of the container in MB (see [Runtime Constraints on CPU and Memory](../../engine/reference/run/#runtime-constraints-on-cpu-and-memory) for more information)
memory_swap | Total memory limit (memory + swap) of the container in MB
autorestart | Whether to restart the container automatically if it stops (see [Crash recovery](../../docker-cloud/apps/autorestart/) for more information)
autodestroy | Whether to terminate the container automatically if it stops (see [Autodestroy](../../docker-cloud/apps/auto-destroy/) for more information)
roles | List of Docker Cloud roles asigned to this container (see [API roles](../../docker-cloud/apps/api-roles/) for more information))
linked_to_container | List of IP addresses of the linked containers (see table `Container Link attributes` below and [Service links](../../docker-cloud/apps/service-links/) for more information)
link_variables | List of environment variables that would be exposed in any container that is linked to this one
privileged | Whether the container has Docker's `privileged` flag set or not (see [Runtime privilege](../../engine/reference/run/#runtime-privilege-linux-capabilities-and-lxc-configuration) for more information)
read_only | Whether the container filesystem is read-only or not
private_ip | IP address of the container on the overlay network. This IP will be reachable from any other container.
net | Network mode set on the container (see table `Network Modes` below, more information ../../reference/run/#network-settings)
pid | PID (Process) Namespace mode for the container (more information ../../reference/run/#pid-settings-pid)


### Container Binding attributes

Attribute | Description
--------- | -----------
host_path | The host path of the volume
container_path | The container path where the volume is mounted
rewritable | `true` is the volume has writable permissions
volume | The resource URI of the volume


### Container Port attributes

Attribute | Description
--------- | -----------
protocol | The protocol of the port, either `tcp` or `udp`
inner_port | The published port number inside the container
outer_port | The published port number in the node public network interface
port_name | Name of the service associated to this port
uri_protocol | The protocol to be used in the endpoint for this port (i.e. `http`)
endpoint_uri | The URI of the endpoint for this port
published | Whether the port has been published in the host public network interface or not. Non-published ports can only be accessed via links.


### Container Environment Variable attributes

Attribute | Description
--------- | -----------
key | The name of the environment variable
value | The value of the environment variable


### Container States

State | Description
----- | -----------
Starting | The container is being deployed or started (from Stopped). No actions allowed in this state.
Running | The container is deployed and running. Possible actions in this state: `stop`, `terminate`.
Stopping | The container is being stopped. No actions allowed in this state.
Stopped | The container is stopped. Possible actions in this state: `start`, `terminate`.
Terminating | The container is being deleted. No actions allowed in this state.
Terminated | The container has been deleted. No actions allowed in this state.


### Network Modes

Strategy | Description
-------- | -----------
bridge | Creates a new network stack for the container on the docker bridge.
host | Uses the host network stack inside the container.


### Container Link attributes

Attribute | Description
--------- | -----------
name | The name given to the link
from_container | The resource URI of the "client" container
to_container | The resource URI of the "server" container being linked
endpoints | A dictionary with the endpoints (protocol, IP and port) to be used to reach each of the "server" container exposed ports


## List all containers

```python
import dockercloud

containers = dockercloud.Container.list()
```

```go
import "github.com/docker/go-dockercloud/dockercloud"

containerList, err := dockercloud.ListContainers()

if err != nil {
  log.Println(err)
}

log.Println(containerList)
```

```http
GET /api/app/v1/container/ HTTP/1.1
Host: cloud.docker.com
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
```

```shell
docker-cloud container ps
```

Lists all current and recently terminated containers. Returns a list of `Container` objects.

### Endpoint Type

Available in Docker Cloud's **REST API**

### HTTP Request

`GET /api/app/v1/[optional_namespace/]container/`

### Query Parameters

Parameter | Description
--------- | -----------
uuid | Filter by UUID
state | Filter by state. Possible values: `Starting`, `Running`, `Stopping`, `Stopped`, `Terminating`, `Terminated`
name | Filter by container name
service | Filter by resource URI of the target service.
node | Filter by resource URI of the target node.

## Get an existing container

```python
import dockercloud

container = dockercloud.Container.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
```

```go
import "github.com/docker/go-dockercloud/dockercloud"

container, err := dockerckoud.GetContainer("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

if err != nil {
  log.Println(err)
}

log.Println(container)
```


```http
GET /api/app/v1/container/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
Host: cloud.docker.com
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
```

```shell
docker-cloud container inspect 7eaf7fff
```

Get all the details of an specific container

### Endpoint Type

Available in Docker Cloud's **REST API**

### HTTP Request

`GET /api/app/v1/[optional_namespace/]container/(uuid)/`

### Path Parameters

Parameter | Description
--------- | -----------
uuid | The UUID of the container to retrieve


## Get the logs of a container

> Example log line

```json
{
    "type": "log",
    "log": "Log line from the container",
    "streamType": "stdout",
    "timestamp": 1433779324
}
```

```python
import dockercloud

def log_handler(message):
	print message

container = dockercloud.Container.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
container.logs(tail=300, follow=True, log_handler=log_handler)
```

```go
import "github.com/docker/go-dockercloud/dockercloud"

container, err := dockercloud.GetContainer("447ecddc-2890-4ea2-849b-99392e0dd7a6")

if err != nil {
	log.Fatal(err)
}
c := make(chan dockercloud.Logs)

go container.Logs(c)
	for {
		s := <-c
		log.Println(s)
	}
```

```http
GET /api/app/v1/container/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/logs/ HTTP/1.1
Host: ws.cloud.docker.com
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Connection: Upgrade
Upgrade: websocket
```

```shell
docker-cloud container logs 7eaf7fff
```

Get the logs of the specified container.

### Endpoint Type

Available in Docker Cloud's **STREAM API**

### HTTP Request

`GET /api/app/v1/[optional_namespace/]container/(uuid)/logs/`

### Path Parameters

Parameter | Description
--------- | -----------
uuid | The UUID of the container to retrieve logs

### Query Parameters

Parameter | Description
--------- | -----------
tail | Number of lines to show from the end of the logs (default: `300`)
follow | Whether to stream logs or close the connection immediately (default: true)
service | Filter by service (resource URI)


## Start a container

```python
import dockercloud

container = dockercloud.Container.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
container.start()
```

```go
import "github.com/docker/go-dockercloud/dockercloud"

container, err := dockercloud.GetContainer("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

if err != nil {
	log.Println(err)
}

if err = container.Start(); err != nil {
  log.Println(err)
}
```

```http
POST /api/app/v1/container/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/start/ HTTP/1.1
Host: cloud.docker.com
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
```

```shell
docker-cloud container start 7eaf7fff
```

Starts a stopped container.

### Endpoint Type

Available in Docker Cloud's **REST API**

### HTTP Request

`POST /api/app/v1/[optional_namespace/]container/(uuid)/start/`

### Path Parameters

Parameter | Description
--------- | -----------
uuid | The UUID of the container to start


## Stop a container

```python
import dockercloud

container = dockerlcoud.Container.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
container.stop()
```

```go
import "github.com/docker/go-dockercloud/dockercloud"

container, err := dockercloud.GetContainer("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

if err != nil {
	log.Println(err)
}

if err = container.Stop(); err != nil {
       log.Println(err)
   }
```

```http
POST /api/app/v1/container/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/stop/ HTTP/1.1
Host: cloud.docker.com
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
```

```shell
docker-cloud container stop 7eaf7fff
```

Stops a running container.

### Endpoint Type

Available in Docker Cloud's **REST API**

### HTTP Request

`POST /api/app/v1/[optional_namespace/]container/(uuid)/stop/`

### Path Parameters

Parameter | Description
--------- | -----------
uuid | The UUID of the container to stop



## Redeploy a container

```python
import dockercloud

container = dockercloud.Container.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
container.redeploy()
```

```go
import "github.com/docker/go-dockercloud/dockercloud"

container, err := dockercloud.GetContainer("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

if err != nil {
	log.Println(err)
}
//Redeploy(dockercloud.ReuseVolumesOption{Reuse: true) to reuse the existing volumes
//Redeploy(dockercloud.ReuseVolumesOption{Reuse: false}) to not reuse the existing volumes
if err = container.Redeploy(dockercloud.ReuseVolumesOption{Reuse: false}); err != nil {
  log.Println(err)
}
```

```http
POST /api/app/v1/container/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/start/ HTTP/1.1
Host: cloud.docker.com
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
```

```shell
docker-cloud container redeploy 7eaf7fff
```

Redeploys a container.

### Endpoint Type

Available in Docker Cloud's **REST API**

### HTTP Request

`POST /api/app/v1/[optional_namespace/]container/(uuid)/redeploy/`

### Path Parameters

Parameter | Description
--------- | -----------
uuid | The UUID of the container to redeploy

### Query Parameters

Parameter | Description
--------- | -----------
reuse_volumes | Wheather to reuse container volumes for this redeploy operation or not (default: `true`).


## Terminate a container

```python
import dockercloud

container = dockercloud.Container.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
container.delete()
```

```go
import "github.com/docker/go-dockercloud/dockercloud"

container, err := dockercloud.GetContainer("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

if err != nil {
	log.Println(err)
}

if err = container.Terminate(); err != nil {
       log.Println(err)
   }
```


```http
DELETE /api/app/v1/container/7eaf7fff-882c-4f3d-9a8f-a22317ac00ce/ HTTP/1.1
Host: cloud.docker.com
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Accept: application/json
```

```shell
docker-cloud container terminate 7eaf7fff
```

Terminates the specified container. This is not reversible. All data stored in the container will be permanently deleted.

### Endpoint Type

Available in Docker Cloud's **REST API**

### HTTP Request

`DELETE /api/app/v1/[optional_namespace/]container/(uuid)/`

### Path Parameters

Parameter | Description
--------- | -----------
uuid | The UUID of the container to terminate


## Execute command inside a container

```
import dockercloud

def msg_handler(message):
    print message

container = dockercloud.Container.fetch("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")
container.execute("ls", handler=msg_handler)
```

```go
import "github.com/docker/go-dockercloud/dockercloud"

container, err := dockercloud.GetContainer("7eaf7fff-882c-4f3d-9a8f-a22317ac00ce")

if err != nil {
  log.Println(err)
}

c := make(chan dockercloud.Exec)

container.Exec("ls", c)

```

```http
GET /api/app/v1/container/(uuid)/exec/ HTTP/1.1
Host: ws.cloud.docker.com
Authorization: Basic dXNlcm5hbWU6YXBpa2V5
Connection: Upgrade
Upgrade: websocket
```


```
docker-cloud exec 7eaf7fff ls
```

Executes a command inside the specified running container, creating a bi-directional stream for the process' standard input and output. This endpoint can be connected to using a bi-directional Secure Web Socket `wss://ws.cloud.docker.com/api/app/v1/container/(uuid)/exec/`

### Endpoint Type

Available in Docker Cloud's **STREAM API**

### HTTP Request

`GET /api/app/v1/[optional_namespace/]container/(uuid)/exec/`

### Path Parameters

Parameter | Description
--------- | -----------
uuid | The UUID of the container where the command will be executed

### Query Parameters

Parameter | Description
--------- | -----------
command | Command to be executed (default: `sh`)
