NAV

# Stacks

## Stack

> Example

    {
      "deployed_datetime": "Mon, 13 Oct 2014 11:01:43 +0000",
      "destroyed_datetime": null,
      "nickname": "deployment stack",
      "name": "dockercloud-app",
      "resource_uri": "/api/app/v1/user_namespace/stack/7fe7ec85-58be-4904-81da-de2219098d7c/",
      "services": [
        "/api/app/v1/user_namespace/service/09cbcf8d-a727-40d9-b420-c8e18b7fa55b/"
      ],
      "state": "Running",
      "synchronized": true,
      "uuid": "09cbcf8d-a727-40d9-b420-c8e18b7fa55b"
    }

A stack is a logical grouping of closely related services, that may be linked with one another.

This is a namespaced endpoint.

### Attributes

Attribute | Description
--- | ---
uuid | A unique identifier for the stack generated automatically on creation
resource_uri | A unique API endpoint that represents the stack
name | A user provided name for the stack.
state | The state of the stack (see table `Stack states` below)
synchronized | Flag indicating if the current stack definition is synchronized with their services.
services | List of service resource URIs belonging to the stack
deployed_datetime | The date and time of the last deployment of the stack (if applicable, `null` otherwise)
destroyed_datetime | The date and time of the `terminate` operation on the stack (if applicable, `null` otherwise)
nickname | A user-friendly name for the stack (`name` by default)

### Stack states

State | Description
--- | ---
Not Running | The stack has been created and has no deployed services yet. Possible actions in this state: `start`, `terminate`.
Starting | All services for the stack are either starting or already running. No actions allowed in this state.
Running | All services for the service are deployed and running. Possible actions in this state: `redeploy`, `terminate`.
Partly running | One or more services of the stack are deployed and running. Possible actions in this state: `redeploy`, `terminate`.
Stopping | All services for the stack are either stopping or already stopped. No actions allowed in this state.
Stopped | All services for the service are stopped. Possible actions in this state: `start`, `redeploy`, `terminate`.
Redeploying | The stack is redeploying all its services with the updated configuration. No actions allowed in this state.
Terminating | All services for the stack are either being terminated or already terminated. No actions allowed in this state.
Terminated | The stack and all its services have been terminated. No actions allowed in this state.

## List all stacks

    import dockercloud

    stacks = dockercloud.Stack.list()

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

    stackList, err := dockercloud.ListStacks()

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

    log.Println(stackList)

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

    docker-cloud stack ls

Lists all current and recently terminated stacks. Returns a list of `Stack` objects.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

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

### Query Parameters

Parameter | Description
--- | ---
uuid | Filter by UUID
name | Filter by stack name

## Create a new stack

    import dockercloud

    stack = dockercloud.Stack.create(name="my-new-stack", services=[{"name": "hello-word", "image": "tutum/hello-world", "target_num_containers": 2}])
    stack.save()

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

    stack, err := dockercloud.CreateStack(dockercloud.StackCreateRequest{Name: "my-new-stack", Services: []dockercloud.ServiceCreateRequest{{Image: "tutum/hello-world", Name: "test", Target_num_containers: 2}}})

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

    log.Println(stack)

    POST /api/app/v1/stack/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json
    Content-Type: application/json

    {
        "name": "my-new-stack",
        "services": [
            {
                "name": "hello-word",
                "image": "tutum/hello-world",
                "target_num_containers": 2,
                "linked_to_service": [
                    {
                        "to_service": "database",
                        "name": "DB"
                    }
                ]
            },
            {
                "name": "database",
                "image": "tutum/mysql"
            }
        ]
    }

    docker-cloud stack create --name hello-world -f docker-compose.yml

Creates a new stack without starting it. Note that the JSON syntax is abstracted by both, the Docker Cloud CLI and our UI, in order to use Stack YAML files.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`POST /api/app/v1/[optional_namespace/]stack/`

### JSON Parameters

Parameter | Description
--- | ---
name | (required) A human-readable name for the stack, i.e. `my-hello-world-stack`
nickname | (optional) A user-friendly name for the stack (`name` by default)
services | (optional) List of services belonging to the stack. Each service accepts the same parameters as a Create new service operation (default: `[]`) plus the ability to refer “links” and “volumes-from” by the name of another service in the stack (see example).

## Export an existing stack

    import dockercloud

    stack = dockercloud.Stack.fetch("46aca402-2109-4a70-a378-760cfed43816")
    stack.export()

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

    stack, err := dockercloud.GetStack("46aca402-2109-4a70-a378-760cfed43816")

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

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

    GET /api/app/v1/stack/46aca402-2109-4a70-a378-760cfed43816/export/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud stack export 46aca402

Get a JSON representation of the stack following the Stack YAML representation.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

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

### Path Parameters

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

## Get an existing stack

    import dockercloud

    stack = dockercloud.Stack.fetch("46aca402-2109-4a70-a378-760cfed43816")

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

    stack, err := dockercloud.GetStack("46aca402-2109-4a70-a378-760cfed43816")

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

    log.Println(stack)

    GET /api/app/v1/stack/46aca402-2109-4a70-a378-760cfed43816/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud stack inspect 46aca402-2109-4a70-a378-760cfed43816

Get all the details of an specific stack

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

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

### Path Parameters

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

## Update an existing stack

    import dockercloud

    stack = dockercloud.Stack.fetch("46aca402-2109-4a70-a378-760cfed43816")
    stack.services = {"services": [{"name": "hello-word", "image": "tutum/hello-world", "target_num_containers": 2}]}
    stack.save()

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

    stack, err := dockercloud.GetStack("46aca402-2109-4a70-a378-760cfed43816")

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

    if err = stack.Update(dockercloud.StackCreateRequest{Services: []dockercloud.ServiceCreateRequest{{Name: "hello-world", Image: "tutum/hello-world", Target_num_containers: 2}}}); err != nil {
       log.Println(err)
    }

    PATCH /api/app/v1/stack/46aca402-2109-4a70-a378-760cfed43816/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json
    Content-Type: application/json

    {
        "services": [
            {
                "name": "hello-word",
                "image": "tutum/hello-world",
                "target_num_containers": 3,
                "linked_to_service": [
                    {
                        "to_service": "database",
                        "name": "DB"
                    }
                ]
            },
            {
                "name": "database",
                "image": "tutum/mysql"
            }
        ]
    }

    docker-cloud stack update -f docker-compose.yml 46aca402

Updates the details of every service in the stack.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

`PATCH /api/app/v1/[optional_namespace/]stack/(uuid)/`

### Path Parameters

Parameter | Description
--- | ---
uuid | The UUID of the stack to update

### JSON Parameters

Parameter | Description
--- | ---
services | (optional) List of services belonging to the stack. Each service accepts the same parameters as a Update an existing service operation (default: `[]`) plus the ability to refer “links” and “volumes-from” by the name of another service in the stack (see example).

## Stop a stack

    import dockercloud

    stack = dockercloud.Stack.fetch("46aca402-2109-4a70-a378-760cfed43816")
    stack.stop()

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

    stack, err := dockercloud.GetStack("46aca402-2109-4a70-a378-760cfed43816")

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

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

    POST /api/app/v1/stack/46aca402-2109-4a70-a378-760cfed43816/stop/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud stack stop 46aca402-2109-4a70-a378-760cfed43816

Stops the services in the stack.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

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

### Path Parameters

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

## Start a stack

    import dockercloud

    stack = dockercloud.Stack.fetch()
    stack.start()

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

    stack, err := dockercloud.GetStack("46aca402-2109-4a70-a378-760cfed43816")

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

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

    POST /api/app/v1/stack/46aca402-2109-4a70-a378-760cfed43816/start/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud stack start 46aca402

Starts the services in the stack.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

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

### Path Parameters

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

## Redeploy a stack

    import dockercloud

    stack = dockercloud.Stack.fetch("46aca402-2109-4a70-a378-760cfed43816")
    stack.redeploy()

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

    stack, err := dockercloud.GetStack("46aca402-2109-4a70-a378-760cfed43816")

    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 = stack.Redeploy(dockercloud.ReuseVolumesOption{Reuse: false}); err != nil {
       log.Println(err)
    }

    POST /api/app/v1/stack/46aca402-2109-4a70-a378-760cfed43816/redeploy/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud stack redeploy 46aca402

Redeploys all the services in the stack.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

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

### Path Parameters

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

### Query Parameters

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

## Terminate a stack

    import dockercloud

    stack = dockercloud.Stack.fetch("46aca402-2109-4a70-a378-760cfed43816")
    stack.delete()

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

    stack, err := dockercloud.GetStack("46aca402-2109-4a70-a378-760cfed43816")

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

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

    DELETE /api/app/v1/stack/46aca402-2109-4a70-a378-760cfed43816/ HTTP/1.1
    Host: cloud.docker.com
    Authorization: Basic dXNlcm5hbWU6YXBpa2V5
    Accept: application/json

    docker-cloud stack terminate 46aca402

Terminate all the services in a the stack and the stack itself.

### Endpoint Type

Available in Docker Cloud’s REST API

### HTTP Request

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

### Path Parameters

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