import Divider from '@site/src/components/Divider';

# deployment

these routes relate to interacting with monitor `deployments`

| name | route |
| ---- | ------ |
| [list deployments](/api/deployment#list-deployments) | `GET /api/deployment/list` |
| [get deployment](/api/deployment#get-deployment) | `GET /api/deployment/<deployment_id>` |
| [get deployment action state](/api/deployment#get-deployment-action-state) | `GET /api/deployment/<deployment_id>/action_state` |
| [get deployment container log](/api/deployment#get-deployment-container-log) | `GET /api/deployment/<deployment_id>/log` |
| [get deployment container stats](/api/deployment#get-deployment-container-stats) | `GET /api/deployment/<deployment_id>/stats` |
| [get deployment deployed version](/api/deployment#get-deployment-deployed-version) | `GET /api/deployment/<deployment_id>/deployed_version` |
| [create deployment](/api/deployment#create-deployment) | `POST /api/deployment/create` |
| [create full deployment](/api/deployment#create-full-deployment) | `POST /api/deployment/create_full` |
| [copy deployment](/api/deployment#copy-deployment) | `POST /api/deployment/<deployment_id>/copy` |
| [delete deployment](/api/deployment#delete-deployment) | `DELETE /api/deployment/<deployment_id>/delete` |
| [update deployment](/api/deployment#update-deployment) | `PATCH /api/deployment/update` |
| [rename deployment](/api/deployment#rename-deployment) | `PATCH /api/deployment/<deployment_id>/rename` |
| [reclone deployment](/api/deployment#reclone-deployment) | `POST /api/deployment/<deployment_id>/reclone` |
| [pull deployment](/api/deployment#pull-deployment) | `POST /api/deployment/<deployment_id>/pull` |
| [deploy container](/api/deployment#deploy-container) | `POST /api/deployment/<deployment_id>/deploy` |
| [start container](/api/deployment#start-container) | `POST /api/deployment/<deployment_id>/start_container` |
| [stop container](/api/deployment#stop-container) | `POST /api/deployment/<deployment_id>/stop_container` |
| [remove container](/api/deployment#remove-container) | `POST /api/deployment/<deployment_id>/remove_container` |

```mdx-code-block
<Divider />
```

## list deployments
`GET /api/deployment/list`

this method will return an array of deployments with container state that the requesting user has a minimum of `Read` permissions on.

### response body
```json
[
	{
		deployment: Deployment,
		state: DockerContainerState,
		container?: {
			name: string,
			id: string,
			image: string,
			state: DockerContainerState,
			status?: string,
		}
	},
	...
]
```

```mdx-code-block
<Divider />
```

## get deployment
`GET /api/deployment/<deployment_id>`

this method will return the deployment with container state that 
the requesting user has a minimum of `Read` permissions on.
it will return `500: Internal Server Error` if the user does not have the required permissions.

### response body
```json
{
	deployment: Deployment,
	state: DockerContainerState,
	container?: {
		name: string,
		id: string,
		image: string,
		state: DockerContainerState,
		status?: string,
	}
}
```

```mdx-code-block
<Divider />
```
## get deployment action state
`GET /api/deployment/<deployment_id>/action_state`

this method returns the action state for the deployment, eg. whether the deployment is currently `deploying`.

### response body
```json
{
	deploying: boolean,
    stopping: boolean,
    starting: boolean,
    removing: boolean,
    pulling: boolean,
    recloning: boolean,
    updating: boolean,
    renaming: boolean,
}
```

```mdx-code-block
<Divider />
```

## get deployment container log
`GET /api/deployment/<deployment_id>/log`

this method is used to get the container's log associated with the deployment.

### query params
```json
{
	tail: number // number of log lines to fetch. this is passed to the --tail flag of docker logs command
}
```

### response body
```json
{
	stdout: string,
	stderr: string,
}
```

```mdx-code-block
<Divider />
```

## get deployment container stats
`GET /api/deployment/<deployment_id>/stats`

this method returns the results of running `docker stats <container_name>` 
for the container associated with the deployment.

### response body
```json
{
	name: string,
	cpu_perc: string,
	mem_perc: string,
	mem_usage: string,
	net_io: string,
	block_io: string,
	pids: string,
}
```

```mdx-code-block
<Divider />
```

## get deployment deployed version
`GET /api/deployment/<deployment_id>/deployed_version`

this method is used to get the image version of the container associated with the deployment, if it exists.
otherwise, it will return the version specified in the deployment config.

### response body
```json
string // the deployed version like '0.2.4'
```

```mdx-code-block
<Divider />
```

## create deployment
`POST /api/deployment/create`

this method is used to create a new deployment on a particular server.
it will return the created deployment.

:::note
users must be **admin** or have `update` permissions on the server specified by the `server_id` 
in the request body in order for this request to succeed.
:::

### request body
```json
{
	name: string,
	server_id: string,
}
```

### response body
[Deployment](/api/types#deployment)

```mdx-code-block
<Divider />
```

## create full deployment
`POST /api/deployment/create_full`

this method is used to create a new deployment on a particular server, already initialized with config.
it will return the created deployment

### request body
[Deployment](/api/types#deployment)

### response body
[Deployment](/api/types#deployment)

```mdx-code-block
<Divider />
```

## copy deployment
`POST /api/deployment/<deployment_id>/copy`

this method will create a copy of the deployment with a new _id and name,
with all the same configuration as the target deployment.
it can be used to move the deployment to another server.

### request body
```json
{
	name: string,
	server_id: string,
}
```

### response body
[Deployment](/api/types#deployment)

```mdx-code-block
<Divider />
```

## delete deployment
`DELETE /api/deployment/<deployment_id>/delete`

this method will delete the deployment. if a container is associated with the deployment, it will be destroyed.

### response body
[Deployment](/api/types#deployment)

```mdx-code-block
<Divider />
```

## update deployment
`PATCH /api/deployment/update`

### request body
[Deployment](/api/types#deployment)

### response body
[Deployment](/api/types#deployment)

```mdx-code-block
<Divider />
```

## rename deployment
`PATCH /api/deployment/<deployment_id>/rename`

### request body
```json
{
	new_name: string,
}
```

```mdx-code-block
<Divider />
```

## reclone deployment
`POST /api/deployment/<deployment_id>/reclone`

if the deployment has a repo attached, this will reclone the repo,
including the on-clone and on-pull actions.

### response body
[Update](/api/types#update)

```mdx-code-block
<Divider />
```

## pull deployment
`POST /api/deployment/<deployment_id>/pull`

if the deployment has a repo attached, this will `git pull` in the repo,
including the on-pull action.

### response body
[Update](/api/types#update)

```mdx-code-block
<Divider />
```

## deploy container
`POST /api/deployment/<deployment_id>/deploy`

this will deploy the container corresponding to the deployments configuration.
if the container already exists, it will destroy it first.

### response body
[Update](/api/types#update)

```mdx-code-block
<Divider />
```

## start container
`POST /api/deployment/<deployment_id>/start_container`

this will run `docker start <container_name>` for the container
corresponding to the deployment

### response body
[Update](/api/types#update)

```mdx-code-block
<Divider />
```

## stop container
`POST /api/deployment/<deployment_id>/stop_container`

this will run `docker stop <container_name>` for the container
corresponding to the deployment

### response body
[Update](/api/types#update)

```mdx-code-block
<Divider />
```

## remove container
`POST /api/deployment/<deployment_id>/remove_container`

this will run `docker stop <container_name> && docker container rm <container_name>`
for the container corresponding to the deployment

### response body
[Update](/api/types#update)