Compose stacks

Create a Compose stack from a Docker Compose file, then start, stop, restart and read it.

A Compose stack runs a Docker Compose file as one Service. On a Server it runs with Docker; in a Cloud account it runs on its own Stack VM. Deploy it with the Compose route on the Deployments page.

Every request goes to https://cloudgate.octabyte.app/backend on the Hosted instance, or to your console address followed by /backend when you self-host. Send a Personal key in x-api-key and the Organization in x-organization-id; Authentication shows how to make the key, and Errors explains every refusal. The examples setCLOUDGATE_KEY and CLOUDGATE_ORG_ID in the shell first. To do the same in the console, read Compose stacks in the user guide.

Create a Compose stack

POST/compose

Who can call it: Owner or Admin. Needs service: create, which a custom role can also grant.

Request body

Field	Type	Notes
`name`required	string	1 to 100 characters.
`appName`	string	1 to 63 characters. Matches `^[a-zA-Z0-9_][a-zA-Z0-9._-]*$`.
`description`	string
`environmentId`required	string	Not empty.
`composeType`	string	One of `docker-compose`, `stack`.
`serverId`	string or null
`composeFile`	string
`sourceType`	string	One of `git`, `github`, `gitlab`, `bitbucket`, `gitea`, `raw`.

Responses

201 Created: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/compose \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "analytics",
    "environmentId": "UVFRqyCfWEtSm6NdDvrZc"
  }'

Get a Compose stack

GET/compose/{id}

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Compose stack's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/compose/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Update a Compose stack

PATCH/compose/{id}

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Compose stack's id.

Request body

Field	Type	Notes
`name`	string	1 to 100 characters.
`description`	string or null
`env`	string or null
`composeFile`	string
`composePath`	string	Not empty.
`composeType`	string	One of `docker-compose`, `stack`.
`command`	string
`isolatedDeployment`	boolean
`sourceType`	string	One of `git`, `github`, `gitlab`, `bitbucket`, `gitea`, `raw`.
`triggerType`	string or null	One of `push`, `tag`, `null`.
`autoDeploy`	boolean or null
`watchPaths`	array of string or null
`enableSubmodules`	boolean
`repository`	string or null
`owner`	string or null
`branch`	string or null
`githubId`	string or null
`gitlabProjectId`	integer or null	At least -9007199254740991.
`gitlabRepository`	string or null
`gitlabOwner`	string or null
`gitlabBranch`	string or null
`gitlabPathNamespace`	string or null
`gitlabId`	string or null
`giteaRepository`	string or null
`giteaOwner`	string or null
`giteaBranch`	string or null
`giteaId`	string or null
`bitbucketRepository`	string or null
`bitbucketRepositorySlug`	string or null
`bitbucketOwner`	string or null
`bitbucketBranch`	string or null
`bitbucketId`	string or null
`customGitUrl`	string
`customGitBranch`	string or null
`customGitSSHKeyId`	string or null

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 You may not reach what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X PATCH https://cloudgate.octabyte.app/backend/compose/RAU6yAYUXFRdXdPLyLoPC \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "name": "analytics",
    "description": "Storefront for Northwind Labs",
    "env": "NODE_ENV=production"
  }'

Delete a Compose stack

DELETE/compose/{id}

?force=true is the escape hatch for a Server that is gone for good: it drops the row even though Cloudgate could not confirm the stack's containers are gone, and the response names what was left behind.

Who can call it: Owner or Admin. Needs service: delete, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Compose stack's id.
`deleteVolumes`required	query	string
`force`required	query	string

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X DELETE "https://cloudgate.octabyte.app/backend/compose/RAU6yAYUXFRdXdPLyLoPC?deleteVolumes=example&force=example" \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Save the environment variables of a Compose stack

PATCH/compose/{id}/environment

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Compose stack's id.

Request body

Field	Type	Notes
`env`	string

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 You may not reach what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X PATCH https://cloudgate.octabyte.app/backend/compose/RAU6yAYUXFRdXdPLyLoPC/environment \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "env": "NODE_ENV=production"
  }'

Get the Stack VM status of a Compose stack

GET/compose/{id}/stack-vm

Whether the stack's Stack VM runs, read from its cloud now. A read, gated by the stack's row-level access as GET :id is.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Compose stack's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/compose/RAU6yAYUXFRdXdPLyLoPC/stack-vm \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Save the Stack VM of a Compose stack

PATCH/compose/{id}/stack-vm

Who can call it: Owner, Admin or Member. Needs service: update, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Compose stack's id.

Request body

Field	Type	Notes
`size`	string	One of `xsmall`, `small`, `medium`, `large`, `xlarge`, `2xlarge`.
`dataDiskGb`	integer	1 to 16384.

Responses

200 OK: The result, as JSON.
Refusals: 400 Validation failed; details names each field; 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X PATCH https://cloudgate.octabyte.app/backend/compose/RAU6yAYUXFRdXdPLyLoPC/stack-vm \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID" \
  -H "content-type: application/json" \
  -d '{
    "size": "xsmall",
    "dataDiskGb": 1
  }'

Start a Compose stack

POST/compose/{id}/start

Who can call it: Owner, Admin or Member. Needs deployment: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Compose stack's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/compose/RAU6yAYUXFRdXdPLyLoPC/start \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Stop a Compose stack

POST/compose/{id}/stop

Who can call it: Owner, Admin or Member. Needs deployment: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Compose stack's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/compose/RAU6yAYUXFRdXdPLyLoPC/stop \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Restart a Compose stack

POST/compose/{id}/restart

Restart: docker compose restart, the containers only; on a Stack VM, never the VM.

Who can call it: Owner, Admin or Member. Needs deployment: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Compose stack's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/compose/RAU6yAYUXFRdXdPLyLoPC/restart \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Remove the containers of a Compose stack

POST/compose/{id}/remove-containers

Remove containers.

Who can call it: Owner, Admin or Member. Needs deployment: create, which a custom role can also grant.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Compose stack's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 Your role does not allow it, or you were not granted what it touches; 404 Nothing with that id in this Organization. The error body.

curl -X POST https://cloudgate.octabyte.app/backend/compose/RAU6yAYUXFRdXdPLyLoPC/remove-containers \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Load the services of a Compose stack

GET/compose/{id}/services

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Compose stack's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/compose/RAU6yAYUXFRdXdPLyLoPC/services \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Get the converted file of a Compose stack

GET/compose/{id}/converted

The compose file as the deploy applies it.

Who can call it: Any signed-in member. The route names no permission of its own; Cloudgate checks your role and your access to what it touches as it runs.

Parameters

Name	In	Type	Notes
`id`required	path	string	The Compose stack's id.

Responses

200 OK: The result, as JSON.
Refusals: 401 No key, or the key is not valid; 403 You may not reach what it touches; 404 Nothing with that id in this Organization. The error body.

curl https://cloudgate.octabyte.app/backend/compose/RAU6yAYUXFRdXdPLyLoPC/converted \
  -H "x-api-key: $CLOUDGATE_KEY" \
  -H "x-organization-id: $CLOUDGATE_ORG_ID"

Something missing or wrong on this page? Email support@octabyte.io, or start a free trial and try it in the console.