mirror of
https://gitlab.com/psuapp/psu.git
synced 2024-08-30 18:12:34 +00:00
734 lines
49 KiB
Markdown
734 lines
49 KiB
Markdown
<h1>
|
|
<div class="docsify-hidden">Portainer Stack Utils Docs</div>
|
|
<abbr title="command-line interface">CLI</abbr> Commands
|
|
</h1>
|
|
<div class="docsify-hidden">
|
|
|
|
<h2>Table of contents</h2>
|
|
<!-- Generated by https://github.com/mcpride/atom-mdtoc -->
|
|
<!-- MDTOC maxdepth:2 firsth1:2 numbering:0 flatten:0 bullets:1 updateOnSave:1 -->
|
|
|
|
- [Available actions](#available-actions)
|
|
- [Aliased actions](#aliased-actions)
|
|
- [Available options](#available-options)
|
|
- [Available environment variables](#available-environment-variables)
|
|
- [Actions in details](#actions-in-details)
|
|
- [`deploy`](#deploy)
|
|
- [`rm`](#rm)
|
|
- [`ls`](#ls)
|
|
- [`status`](#status)
|
|
- [`services`](#services)
|
|
- [`tasks`](#tasks)
|
|
- [`tasks:healthy`](#taskshealthy)
|
|
- [`containers`](#containers)
|
|
- [`login`](#login)
|
|
- [`lint`](#lint)
|
|
- [`inspect`](#inspect)
|
|
- [`system:info`](#systeminfo)
|
|
- [`actions`](#actions)
|
|
- [`help`](#help)
|
|
- [`version`](#version)
|
|
- [Options in details](#options-in-details)
|
|
- [Stack environment variables](#stack-environment-variables)
|
|
- [Verbose mode](#verbose-mode)
|
|
- [Debug mode](#debug-mode)
|
|
- [Strict mode](#strict-mode)
|
|
- [Quiet mode](#quiet-mode)
|
|
- [`detect-job` option](#detect-job-option)
|
|
- [Glossary](#glossary)
|
|
- [Job](#job)
|
|
|
|
<!-- /MDTOC -->
|
|
|
|
</div>
|
|
|
|
## Available actions
|
|
|
|
| Name | Description |
|
|
| --------------------------------- | ----------- |
|
|
| [`deploy`](#deploy) | Deploy/update the given stack. |
|
|
| [`rm`](#rm) | Remove/undeploy the given stack. |
|
|
| [`ls`](#ls) | List stacks already deployed. |
|
|
| [`status`](#status) | Check if the stack is running/deployed correctly. |
|
|
| [`services`](#services) | List services already deployed in the current stack. |
|
|
| [`tasks`](#tasks) | List tasks in the current stack. |
|
|
| [`tasks:healthy`](#taskshealthy) | List tasks who are running correctly in the current stack. |
|
|
| [`containers`](#containers) | List containers running in the current stack. |
|
|
| [`login`](#login) | Log in to a Portainer instance. |
|
|
| [`lint`](#lint) | Validate the Docker compose/stack file. |
|
|
| [`inspect`](#inspect) | Display low-level information of the current stack. |
|
|
| [`system:info`](#systeminfo) | Display Docker system-wide information. |
|
|
| [`actions`](#actions) | List available actions for this program. |
|
|
| [`help`](#help) | Display help message. |
|
|
| [`version`](#version) | Display this program version. |
|
|
|
|
### Aliased actions
|
|
|
|
| Aliased action | Equivalent action |
|
|
| ------------------ | ---------------------------------- |
|
|
| `auth` | [`login`](#login) |
|
|
| `docker:info` | [`system:info`](#systeminfo) |
|
|
| `list` | [`ls`](#ls) |
|
|
| `ps` | [`tasks`](#tasks) |
|
|
| `ps:healthy` | [`tasks:healthy`](#taskshealthy) |
|
|
| `remove` | [`rm`](#rm) |
|
|
| `undeploy` | [`rm`](#rm) |
|
|
| `update` | [`deploy`](#deploy) |
|
|
| `validate` | [`lint`](#lint) |
|
|
|
|
## Available options
|
|
|
|
<!-- [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [lint](#lint), [inspect](#inspect), [system:info](#systeminfo), [actions](#actions), [help](#help), [version](#version) | -->
|
|
|
|
| Flag | Option | Description | Used in action(s) |
|
|
| -----------| -------------------------------- | ----------- | ----------------- |
|
|
| `-l` | `--url=URL` | URL of the Portainer instance | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
|
|
| `-u` | `--user=USERNAME` | Username of the Portainer instance | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
|
|
| `-p` | `--password=PASSWORD` | Password of the Portainer instance | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
|
|
| `-A` | `--auth-token=[AUTH_TOKEN]` | Use a Portainer auth token instead of `--user` and `--password` options, you can get it with the `psu login` command. Defaults to `null` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
|
|
| `-n` | `--name=STACK_NAME` | Stack name | [deploy](#deploy), [rm](#rm), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [inspect](#inspect) |
|
|
| `-c`, `-f` | `--compose-file=FILE_PATH` | Path to docker compose/stack file (required if action=deploy) | [deploy](#deploy), [lint](#lint) |
|
|
| `-C`, `-F` | `--compose-file-base64=[BASE64]` | Content of docker compose/stack file, encoded in base64, useful with Docker in Docker (only used when action=deploy) | [deploy](#deploy), [lint](#lint) |
|
|
| `-g` | `--env-file=[FILE_PATH]` | Path to a file of environment variables, to be used by the stack (only used when action=deploy) | [deploy](#deploy) |
|
|
| `-G` | `--env-file-base64=[BASE64]` | Content of file with environment variables, encoded in base64, to be used by the stack, useful with Docker in Docker (only used when action=deploy) | [deploy](#deploy) |
|
|
| `-e` | `--endpoint=[ENDPOINT_ID]` | Which Docker endpoint to use. Defaults to `1` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
|
|
| `-r` | `--prune` | Whether to prune unused containers or not (only used when action=deploy). Defaults to `false` | [deploy](#deploy) |
|
|
| `-T` | `--timeout=[SECONDS]` | Timeout, number of seconds before thrown an error (only used when action=status\|tasks\|tasks:healthy). Defaults to `100` | [status](#status), [tasks](#tasks), [tasks:healthy](#taskshealthy) |
|
|
| `-j` | `--detect-job=[true\|false]` | Auto detect services who are jobs in the current stack. Defaults to `true` | [status](#status), [tasks](#tasks), [tasks:healthy](#taskshealthy) |
|
|
| `-S` | `--service=[SERVICE_NAME]` | Filtering by a service name of the current stack (only used when action=status\|tasks\|tasks:healthy\|containers) | [status](#status), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers) |
|
|
| `-i` | `--insecure` | Skip the host's SSL certificate verification, use at your own risk. Defaults to `false` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
|
|
| `-v` | `--verbose` | Increase the verbosity of messages. Defaults to `false` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [lint](#lint), [inspect](#inspect), [system:info](#systeminfo), [actions](#actions) |
|
|
| `-d` | `--debug` | Print as much information as possible to help diagnosing a malfunction. Defaults to `false` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [lint](#lint), [inspect](#inspect), [system:info](#systeminfo), [actions](#actions) |
|
|
| `-m` | `--masked-variables` | In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true\|extended\|false. Defaults to `false` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
|
|
| `-q` | `--quiet` | Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to `false` | [ls](#ls), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [inspect](#inspect) |
|
|
| `-t` | `--strict` | Never updates an existent stack nor removes an inexistent one, and instead exits with an error. Defaults to `false` | [deploy](#deploy), [rm](#rm) |
|
|
| `-L` | `--lint=[true\|false]` | Validate the Docker compose/stack file before deploying the stack (only used when action=deploy). Defaults to `true` | [deploy](#deploy) |
|
|
| `-h` | `--help` | Display help message. To display help of a given action, run: `psu <action> --help` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [lint](#lint), [inspect](#inspect), [system:info](#systeminfo), [actions](#actions), [version](#version) |
|
|
| `-V` | `--version` | Display the version of this program | |
|
|
| `-s` | `--secure=[yes\|no]` | **DEPRECATED**: Use the `--insecure` option instead. Enable or disable the host's SSL certificate verification. Defaults to `yes` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
|
|
| `-a` | `--action=[ACTION_NAME]` | **DEPRECATED**: Use `<action>` argument instead. The name of the action to execute | |
|
|
|
|
## Available environment variables
|
|
|
|
| Environment variable | Description | Used in action(s) |
|
|
| ------------------------------------------- | -------------- | ----------------- |
|
|
| `ACTION=ACTION_NAME` | The name of the action to execute | <abbr title="not applicable">n/a</abbr> |
|
|
| `PORTAINER_URL=URL` | URL of the Portainer instance | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
|
|
| `PORTAINER_USER=USERNAME` | Username of the Portainer instance | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
|
|
| `PORTAINER_PASSWORD=PASSWORD` | Password of the Portainer instance | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
|
|
| `PORTAINER_AUTH_TOKEN=[AUTH_TOKEN]` | Use a Portainer auth token instead of `--user` and `--password` options, you can get it with the `psu login` command. Defaults to `null` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
|
|
| `PORTAINER_STACK_NAME=STACK_NAME` | Stack name | [deploy](#deploy), [rm](#rm), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [inspect](#inspect) |
|
|
| `DOCKER_COMPOSE_FILE=FILE_PATH` | Path to docker compose/stack file (required if action=deploy) | [deploy](#deploy), [lint](#lint) |
|
|
| `ENVIRONMENT_VARIABLES_FILE=[FILE_PATH]` | Path to a file of environment variables, to be used by the stack (only used when action=deploy) | [deploy](#deploy) |
|
|
| `PORTAINER_ENDPOINT=[ENDPOINT_ID]` | Which Docker endpoint to use. Defaults to `1` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
|
|
| `PORTAINER_PRUNE=[true\|false]` | Whether to prune unused containers or not (only used when action=deploy). Defaults to `false` | [deploy](#deploy) |
|
|
| `TIMEOUT=[SECONDS]` | Timeout, number of seconds before thrown an error (only used when action=status\|tasks\|tasks:healthy). Defaults to `100` | [status](#status), [tasks](#tasks), [tasks:healthy](#taskshealthy) |
|
|
| `AUTO_DETECT_JOB=[true\|false]` | Auto detect services who are jobs in the current stack. Defaults to `true` | [status](#status), [tasks](#tasks), [tasks:healthy](#taskshealthy) |
|
|
| `PORTAINER_SERVICE_NAME=[SERVICE_NAME]` | Filtering by a service name of the current stack (only used when action=status\|tasks\|tasks:healthy\|containers) | [status](#status), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers) |
|
|
| `HTTPIE_VERIFY_SSL=[yes\|no]` | Enable or disable the host's SSL certificate verification. Defaults to `yes` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
|
|
| `VERBOSE_MODE=[true\|false]` | Increase the verbosity of messages. Defaults to `false` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [lint](#lint), [inspect](#inspect), [system:info](#systeminfo), [actions](#actions) |
|
|
| `DEBUG_MODE=[true\|false]` | Print as much information as possible to help diagnosing a malfunction. Defaults to `false` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [lint](#lint), [inspect](#inspect), [system:info](#systeminfo), [actions](#actions) |
|
|
| `MASKED_VARIABLES=[true\|extended\|false]` | In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true\|extended\|false. Defaults to `false` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) |
|
|
| `QUIET_MODE=[true\|false]` | Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to `false` | [ls](#ls), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [inspect](#inspect) |
|
|
| `STRICT_MODE=[true\|false]` | Never updates an existent stack nor removes an inexistent one, and instead exits with an error. Defaults to `false` | [deploy](#deploy), [rm](#rm) |
|
|
| `DOCKER_COMPOSE_LINT=[true\|false]` | Validate the Docker compose/stack file before deploying the stack (only used when action=deploy). Defaults to `true` | [deploy](#deploy) |
|
|
|
|
<!-- | `PORTAINER_INSECURE=[true\|false]` | Skip the host's SSL certificate verification, use at your own risk. Defaults to `false` | [deploy](#deploy), [rm](#rm), [ls](#ls), [status](#status), [services](#services), [tasks](#tasks), [tasks:healthy](#taskshealthy), [containers](#containers), [login](#login), [inspect](#inspect), [system:info](#systeminfo) | -->
|
|
<!-- | `DOCKER_COMPOSE_BASE64=[BASE64]` | Content of docker compose/stack file, encoded in base64, useful with Docker in Docker (only used when action=deploy) | [deploy](#deploy), [lint](#lint) | -->
|
|
<!-- | `ENVIRONMENT_VARIABLES_BASE64=[BASE64]` | Content of file with environment variables, encoded in base64, to be used by the stack, useful with Docker in Docker (only used when action=deploy) | [deploy](#deploy) | -->
|
|
|
|
## Actions in details
|
|
|
|
### `deploy`
|
|
|
|
Deploy/update the given stack.
|
|
|
|
#### Aliased action:
|
|
`update`
|
|
|
|
#### Usage:
|
|
`psu deploy [options]`
|
|
|
|
#### Examples:
|
|
|
|
```bash
|
|
psu deploy --user admin --password password --url https://portainer.local --name mystack --compose-file /path/to/docker-compose.yml --env-file /path/to/env_vars_file
|
|
```
|
|
|
|
#### Required options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-l` | `--url=URL` | URL of the Portainer instance |
|
|
| `-u` | `--user=USERNAME` | Username of the Portainer instance |
|
|
| `-p` | `--password=PASSWORD` | Password of the Portainer instance |
|
|
| `-n` | `--name=STACK_NAME` | Stack name |
|
|
| `-c`, `-f` | `--compose-file=FILE_PATH` | Path to docker compose/stack file (required if action=deploy) |
|
|
|
|
#### Optional options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-A` | `--auth-token=[AUTH_TOKEN]` | Use a Portainer auth token instead of `--user` and `--password` options, you can get it with the `psu login` command. Defaults to `null` |
|
|
| `-e` | `--endpoint=[ENDPOINT_ID]` | Which Docker endpoint to use. Defaults to `1` |
|
|
| `-L` | `--lint=[true\|false]` | Validate the Docker compose/stack file before deploying the stack (only used when action=deploy). Defaults to `true` |
|
|
| `-C`, `-F` | `--compose-file-base64=[BASE64]` | Content of docker compose/stack file, encoded in base64, useful with Docker in Docker (only used when action=deploy) |
|
|
| `-g` | `--env-file=[FILE_PATH]` | Path to a file of environment variables, to be used by the stack (only used when action=deploy) |
|
|
| `-G` | `--env-file-base64=[BASE64]` | Content of file with environment variables, encoded in base64, to be used by the stack, useful with Docker in Docker (only used when action=deploy) |
|
|
| `-r` | `--prune` | Whether to prune unused containers or not (only used when action=deploy). Defaults to `false` |
|
|
| `-i` | `--insecure` | Skip the host's SSL certificate verification, use at your own risk. Defaults to `false` |
|
|
| `-v` | `--verbose` | Increase the verbosity of messages. Defaults to `false` |
|
|
| `-d` | `--debug` | Print as much information as possible to help diagnosing a malfunction. Defaults to `false` |
|
|
| `-m` | `--masked-variables` | In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true\|extended\|false. Defaults to `false` |
|
|
| `-t` | `--strict` | Never updates an existent stack nor removes an inexistent one, and instead exits with an error. Defaults to `false` |
|
|
| `-h` | `--help` | Display help message. To display help of a given action, run: `psu <action> --help` |
|
|
|
|
### `rm`
|
|
Remove/undeploy the given stack.
|
|
|
|
#### Aliased actions:
|
|
`remove`, `undeploy`
|
|
|
|
#### Usage:
|
|
`psu rm [options]`
|
|
|
|
#### Examples:
|
|
|
|
```bash
|
|
psu rm --user admin --password password --url https://portainer.local --name mystack
|
|
```
|
|
|
|
#### Required options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-l` | `--url=URL` | URL of the Portainer instance |
|
|
| `-u` | `--user=USERNAME` | Username of the Portainer instance |
|
|
| `-p` | `--password=PASSWORD` | Password of the Portainer instance |
|
|
| `-n` | `--name=STACK_NAME` | Stack name |
|
|
|
|
#### Optional options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-A` | `--auth-token=[AUTH_TOKEN]` | Use a Portainer auth token instead of `--user` and `--password` options, you can get it with the `psu login` command. Defaults to `null` |
|
|
| `-e` | `--endpoint=[ENDPOINT_ID]` | Which Docker endpoint to use. Defaults to `1` |
|
|
| `-i` | `--insecure` | Skip the host's SSL certificate verification, use at your own risk. Defaults to `false` |
|
|
| `-v` | `--verbose` | Increase the verbosity of messages. Defaults to `false` |
|
|
| `-d` | `--debug` | Print as much information as possible to help diagnosing a malfunction. Defaults to `false` |
|
|
| `-m` | `--masked-variables` | In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true\|extended\|false. Defaults to `false` |
|
|
| `-t` | `--strict` | Never updates an existent stack nor removes an inexistent one, and instead exits with an error. Defaults to `false` |
|
|
| `-h` | `--help` | Display help message. To display help of a given action, run: `psu <action> --help` |
|
|
|
|
### `ls`
|
|
List stacks already deployed.
|
|
|
|
#### Aliased actions:
|
|
`list`
|
|
|
|
#### Usage:
|
|
`psu ls [options]`
|
|
|
|
#### Examples:
|
|
|
|
```bash
|
|
psu ls --user admin --password password --url https://portainer.local
|
|
```
|
|
|
|
Output a JSON array of the stacks already deployed:
|
|
```json
|
|
[
|
|
{
|
|
"Id": "mystack_jpofkc0i9uo9wtx1zesuk649w",
|
|
"Name": "mystack",
|
|
"Type": "1",
|
|
"EndpointID": "1",
|
|
"EntryPoint": "docker-compose.yml",
|
|
"SwarmID": "jpofkc0i9uo9wtx1zesuk649w",
|
|
"ProjectPath": "/data/compose/mystack_jpofkc0i9uo9wtx1zesuk649w",
|
|
"Env": [
|
|
{
|
|
"name": "MYSQL_ROOT_PASSWORD",
|
|
"value": "password"
|
|
}
|
|
]
|
|
},
|
|
{
|
|
"Id": "mysecondstack_i0649w9uo9wtx1zesujpofkck",
|
|
"Name": "mysecondstack",
|
|
"Type": "1",
|
|
"EndpointID": "1",
|
|
"EntryPoint": "docker-compose.yml",
|
|
"SwarmID": "i0649w9uo9wtx1zesujpofkck",
|
|
"ProjectPath": "/data/compose/mysecondstack_i0649w9uo9wtx1zesujpofkck"
|
|
},
|
|
{
|
|
"Id": "mythirdstack_w9uo9wtxi064ujpofkck91zes",
|
|
"Name": "mythirdstack",
|
|
"Type": "1",
|
|
"EndpointID": "1",
|
|
"EntryPoint": "docker-compose.yml",
|
|
"SwarmID": "mythirdstack_w9uo9wtxi064ujpofkck91zes",
|
|
"ProjectPath": "/data/compose/mythirdstack_mythirdstack_w9uo9wtxi064ujpofkck91zes"
|
|
},
|
|
]
|
|
```
|
|
|
|
**With the `quiet` mode enabled**:
|
|
```bash
|
|
psu ls --user admin --password password --url https://portainer.local --quiet
|
|
```
|
|
|
|
Output the name of the stacks already deployed:
|
|
```bash
|
|
mystack
|
|
mysecondstack
|
|
mythirdstack
|
|
```
|
|
|
|
#### Required options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-l` | `--url=URL` | URL of the Portainer instance |
|
|
| `-u` | `--user=USERNAME` | Username of the Portainer instance |
|
|
| `-p` | `--password=PASSWORD` | Password of the Portainer instance |
|
|
|
|
#### Optional options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-A` | `--auth-token=[AUTH_TOKEN]` | Use a Portainer auth token instead of `--user` and `--password` options, you can get it with the `psu login` command. Defaults to `null` |
|
|
| `-e` | `--endpoint=[ENDPOINT_ID]` | Which Docker endpoint to use. Defaults to `1` |
|
|
| `-q` | `--quiet` | Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to `false` |
|
|
| `-i` | `--insecure` | Skip the host's SSL certificate verification, use at your own risk. Defaults to `false` |
|
|
| `-v` | `--verbose` | Increase the verbosity of messages. Defaults to `false` |
|
|
| `-d` | `--debug` | Print as much information as possible to help diagnosing a malfunction. Defaults to `false` |
|
|
| `-m` | `--masked-variables` | In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true\|extended\|false. Defaults to `false` |
|
|
| `-h` | `--help` | Display help message. To display help of a given action, run: `psu <action> --help` |
|
|
|
|
### `status`
|
|
Check if the stack is running/deployed correctly
|
|
|
|
If your stack has some services who acts as [jobs](#job), see the [`--detect-job`](#detect-job-option) option for more details.
|
|
|
|
This action is very useful in CI/CD pipelines, it's equivalent to the [`kubectl rollout status`](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#-em-status-em-) command of Kubernetes.
|
|
|
|
#### Usage:
|
|
`psu status [options]`
|
|
|
|
#### Examples:
|
|
|
|
```bash
|
|
psu status --user admin --password password --url https://portainer.local --name mystack
|
|
```
|
|
|
|
This command outputs nothing if the stack is correctly running or deployed.
|
|
|
|
It also has an exit code (or exit status).
|
|
The exit code value return based on a command or program will successfully execute _(return 0)_ or not _(return 1 or higher)_.
|
|
|
|
```bash
|
|
psu status --user admin --password password --url https://portainer.local --name mystack --timeout 20
|
|
|
|
if [ $? -eq 0 ]; then
|
|
echo "[OK] This stack is running/deployed correctly"
|
|
else
|
|
echo "[ERROR] This stack isn't running/deployed correctly!"
|
|
fi
|
|
```
|
|
|
|
For more informations about exit code, you can read this [article](https://tecadmin.net/tutorial/bash-scripting/bash-exit-codes/) and this [Wikipedia page](https://en.wikipedia.org/wiki/Exit_status)
|
|
|
|
#### Required options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-l` | `--url=URL` | URL of the Portainer instance |
|
|
| `-u` | `--user=USERNAME` | Username of the Portainer instance |
|
|
| `-p` | `--password=PASSWORD` | Password of the Portainer instance |
|
|
| `-n` | `--name=STACK_NAME` | Stack name |
|
|
|
|
#### Optional options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-A` | `--auth-token=[AUTH_TOKEN]` | Use a Portainer auth token instead of `--user` and `--password` options, you can get it with the `psu login` command. Defaults to `null` |
|
|
| `-e` | `--endpoint=[ENDPOINT_ID]` | Which Docker endpoint to use. Defaults to `1` |
|
|
| `-S` | `--service=[SERVICE_NAME]` | Filtering by a service name of the current stack (only used when action=status\|tasks\|tasks:healthy\|containers) |
|
|
| `-j` | `--detect-job=[true\|false]` | Auto detect services who are jobs in the current stack. Defaults to `true` |
|
|
| `-T` | `--timeout=[SECONDS]` | Timeout, number of seconds before thrown an error (only used when action=status\|tasks\|tasks:healthy). Defaults to `100` |
|
|
| `-i` | `--insecure` | Skip the host's SSL certificate verification, use at your own risk. Defaults to `false` |
|
|
| `-v` | `--verbose` | Increase the verbosity of messages. Defaults to `false` |
|
|
| `-d` | `--debug` | Print as much information as possible to help diagnosing a malfunction. Defaults to `false` |
|
|
| `-m` | `--masked-variables` | In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true\|extended\|false. Defaults to `false` |
|
|
| `-h` | `--help` | Display help message. To display help of a given action, run: `psu <action> --help` |
|
|
|
|
### `services`
|
|
List services already deployed in the current stack.
|
|
|
|
#### Usage:
|
|
`psu services [options]`
|
|
|
|
#### Required options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-l` | `--url=URL` | URL of the Portainer instance |
|
|
| `-u` | `--user=USERNAME` | Username of the Portainer instance |
|
|
| `-p` | `--password=PASSWORD` | Password of the Portainer instance |
|
|
| `-n` | `--name=STACK_NAME` | Stack name |
|
|
|
|
#### Optional options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-A` | `--auth-token=[AUTH_TOKEN]` | Use a Portainer auth token instead of `--user` and `--password` options, you can get it with the `psu login` command. Defaults to `null` |
|
|
| `-e` | `--endpoint=[ENDPOINT_ID]` | Which Docker endpoint to use. Defaults to `1` |
|
|
| `-q` | `--quiet` | Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to `false` |
|
|
| `-i` | `--insecure` | Skip the host's SSL certificate verification, use at your own risk. Defaults to `false` |
|
|
| `-v` | `--verbose` | Increase the verbosity of messages. Defaults to `false` |
|
|
| `-d` | `--debug` | Print as much information as possible to help diagnosing a malfunction. Defaults to `false` |
|
|
| `-m` | `--masked-variables` | In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true\|extended\|false. Defaults to `false` |
|
|
| `-h` | `--help` | Display help message. To display help of a given action, run: `psu <action> --help` |
|
|
|
|
### `tasks`
|
|
List tasks in the current stack.
|
|
|
|
If your stack has some services who acts as [jobs](#job), see the [`--detect-job`](#detect-job-option) option for more details.
|
|
|
|
#### Usage:
|
|
`psu tasks [options]`
|
|
|
|
#### Aliased action:
|
|
`ps`
|
|
|
|
#### Required options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-l` | `--url=URL` | URL of the Portainer instance |
|
|
| `-u` | `--user=USERNAME` | Username of the Portainer instance |
|
|
| `-p` | `--password=PASSWORD` | Password of the Portainer instance |
|
|
| `-n` | `--name=STACK_NAME` | Stack name |
|
|
|
|
#### Optional options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-A` | `--auth-token=[AUTH_TOKEN]` | Use a Portainer auth token instead of `--user` and `--password` options, you can get it with the `psu login` command. Defaults to `null` |
|
|
| `-e` | `--endpoint=[ENDPOINT_ID]` | Which Docker endpoint to use. Defaults to `1` |
|
|
| `-S` | `--service=[SERVICE_NAME]` | Filtering by a service name of the current stack (only used when action=status\|tasks\|tasks:healthy\|containers) |
|
|
| `-j` | `--detect-job=[true\|false]` | Auto detect services who are jobs in the current stack. Defaults to `true` |
|
|
| `-T` | `--timeout=[SECONDS]` | Timeout, number of seconds before thrown an error (only used when action=status\|tasks\|tasks:healthy). Defaults to `100` |
|
|
| `-q` | `--quiet` | Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to `false` |
|
|
| `-i` | `--insecure` | Skip the host's SSL certificate verification, use at your own risk. Defaults to `false` |
|
|
| `-v` | `--verbose` | Increase the verbosity of messages. Defaults to `false` |
|
|
| `-d` | `--debug` | Print as much information as possible to help diagnosing a malfunction. Defaults to `false` |
|
|
| `-m` | `--masked-variables` | In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true\|extended\|false. Defaults to `false` |
|
|
| `-h` | `--help` | Display help message. To display help of a given action, run: `psu <action> --help` |
|
|
|
|
### `tasks:healthy`
|
|
|
|
List tasks who are running correctly in the current stack.
|
|
|
|
If your stack has some services who acts as [jobs](#job), see the [`--detect-job`](#detect-job-option) option for more details.
|
|
|
|
#### Usage:
|
|
`psu tasks:healthy [options]`
|
|
|
|
#### Aliased action:
|
|
`ps:healthy`
|
|
|
|
#### Required options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-l` | `--url=URL` | URL of the Portainer instance |
|
|
| `-u` | `--user=USERNAME` | Username of the Portainer instance |
|
|
| `-p` | `--password=PASSWORD` | Password of the Portainer instance |
|
|
| `-n` | `--name=STACK_NAME` | Stack name |
|
|
|
|
#### Optional options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-A` | `--auth-token=[AUTH_TOKEN]` | Use a Portainer auth token instead of `--user` and `--password` options, you can get it with the `psu login` command. Defaults to `null` |
|
|
| `-e` | `--endpoint=[ENDPOINT_ID]` | Which Docker endpoint to use. Defaults to `1` |
|
|
| `-S` | `--service=[SERVICE_NAME]` | Filtering by a service name of the current stack (only used when action=status\|tasks\|tasks:healthy\|containers) |
|
|
| `-j` | `--detect-job=[true\|false]` | Auto detect services who are jobs in the current stack. Defaults to `true` |
|
|
| `-T` | `--timeout=[SECONDS]` | Timeout, number of seconds before thrown an error (only used when action=status\|tasks\|tasks:healthy). Defaults to `100` |
|
|
| `-q` | `--quiet` | Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to `false` |
|
|
| `-i` | `--insecure` | Skip the host's SSL certificate verification, use at your own risk. Defaults to `false` |
|
|
| `-v` | `--verbose` | Increase the verbosity of messages. Defaults to `false` |
|
|
| `-d` | `--debug` | Print as much information as possible to help diagnosing a malfunction. Defaults to `false` |
|
|
| `-m` | `--masked-variables` | In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true\|extended\|false. Defaults to `false` |
|
|
| `-h` | `--help` | Display help message. To display help of a given action, run: `psu <action> --help` |
|
|
|
|
### `containers`
|
|
List containers running in the current stack.
|
|
|
|
#### Usage:
|
|
`psu containers [options]`
|
|
|
|
#### Required options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-l` | `--url=URL` | URL of the Portainer instance |
|
|
| `-u` | `--user=USERNAME` | Username of the Portainer instance |
|
|
| `-p` | `--password=PASSWORD` | Password of the Portainer instance |
|
|
| `-n` | `--name=STACK_NAME` | Stack name |
|
|
|
|
#### Optional options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-A` | `--auth-token=[AUTH_TOKEN]` | Use a Portainer auth token instead of `--user` and `--password` options, you can get it with the `psu login` command. Defaults to `null` |
|
|
| `-e` | `--endpoint=[ENDPOINT_ID]` | Which Docker endpoint to use. Defaults to `1` |
|
|
| `-S` | `--service=[SERVICE_NAME]` | Filtering by a service name of the current stack (only used when action=status\|tasks\|tasks:healthy\|containers) |
|
|
| `-q` | `--quiet` | Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to `false` |
|
|
| `-i` | `--insecure` | Skip the host's SSL certificate verification, use at your own risk. Defaults to `false` |
|
|
| `-v` | `--verbose` | Increase the verbosity of messages. Defaults to `false` |
|
|
| `-d` | `--debug` | Print as much information as possible to help diagnosing a malfunction. Defaults to `false` |
|
|
| `-m` | `--masked-variables` | In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true\|extended\|false. Defaults to `false` |
|
|
| `-h` | `--help` | Display help message. To display help of a given action, run: `psu <action> --help` |
|
|
|
|
### `login`
|
|
Log in to a Portainer instance.
|
|
|
|
#### Usage:
|
|
`psu login [options]`
|
|
|
|
#### Aliased action:
|
|
`auth`
|
|
|
|
#### Required options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-l` | `--url=URL` | URL of the Portainer instance |
|
|
| `-u` | `--user=USERNAME` | Username of the Portainer instance |
|
|
| `-p` | `--password=PASSWORD` | Password of the Portainer instance |
|
|
|
|
#### Optional options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-i` | `--insecure` | Skip the host's SSL certificate verification, use at your own risk. Defaults to `false` |
|
|
| `-v` | `--verbose` | Increase the verbosity of messages. Defaults to `false` |
|
|
| `-d` | `--debug` | Print as much information as possible to help diagnosing a malfunction. Defaults to `false` |
|
|
| `-m` | `--masked-variables` | In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true\|extended\|false. Defaults to `false` |
|
|
| `-h` | `--help` | Display help message. To display help of a given action, run: `psu <action> --help` |
|
|
|
|
### `lint`
|
|
Validate the Docker compose/stack file.
|
|
|
|
#### Usage:
|
|
`psu lint [options]`
|
|
|
|
#### Aliased action:
|
|
`validate`
|
|
|
|
#### Required options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-c`, `-f` | `--compose-file=FILE_PATH` | Path to docker compose/stack file (required if action=deploy) |
|
|
|
|
#### Optional options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-C`, `-F` | `--compose-file-base64=[BASE64]` | Content of docker compose/stack file, encoded in base64, useful with Docker in Docker (only used when action=deploy) |
|
|
| `-v` | `--verbose` | Increase the verbosity of messages. Defaults to `false` |
|
|
| `-d` | `--debug` | Print as much information as possible to help diagnosing a malfunction. Defaults to `false` |
|
|
| `-h` | `--help` | Display help message. To display help of a given action, run: `psu <action> --help` |
|
|
|
|
### `inspect`
|
|
Display low-level information of the current stack.
|
|
|
|
#### Usage:
|
|
`psu inspect [options]`
|
|
|
|
#### Examples:
|
|
```bash
|
|
psu inspect --user admin --password password --url https://portainer.local --name mystack
|
|
```
|
|
|
|
Output the JSON object of the stack if it's already deployed:
|
|
```json
|
|
{
|
|
"Id": "mystack_jpofkc0i9uo9wtx1zesuk649w",
|
|
"Name": "mystack",
|
|
"Type": "1",
|
|
"EndpointID": "1",
|
|
"EntryPoint": "docker-compose.yml",
|
|
"SwarmID": "jpofkc0i9uo9wtx1zesuk649w",
|
|
"ProjectPath": "/data/compose/mystack_jpofkc0i9uo9wtx1zesuk649w",
|
|
"Env": [
|
|
{
|
|
"name": "MYSQL_ROOT_PASSWORD",
|
|
"value": "password"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
**With the `quiet` mode enabled**:
|
|
```bash
|
|
psu inspect --user admin --password password --url https://portainer.local --name mystack --quiet
|
|
```
|
|
|
|
Output the stack name if it's already deployed:
|
|
```bash
|
|
mystack
|
|
```
|
|
|
|
**Check if the stack is already deployed**:
|
|
```bash
|
|
stack_exist=$(psu inspect --user admin --password password --url https://portainer.local --name mystack)
|
|
|
|
if [ -n "$stack_exist" ]; then
|
|
echo OK
|
|
else
|
|
echo KO
|
|
fi
|
|
|
|
## OR check the exit code of the last executed command:
|
|
stack_exist=$(psu inspect --user admin --password password --url https://portainer.local --name mystack)
|
|
|
|
status=$?
|
|
if $(exit $status); then
|
|
echo OK
|
|
else
|
|
echo KO
|
|
fi
|
|
```
|
|
|
|
#### Required options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-l` | `--url=URL` | URL of the Portainer instance |
|
|
| `-u` | `--user=USERNAME` | Username of the Portainer instance |
|
|
| `-p` | `--password=PASSWORD` | Password of the Portainer instance |
|
|
| `-n` | `--name=STACK_NAME` | Stack name |
|
|
|
|
#### Optional options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-A` | `--auth-token=[AUTH_TOKEN]` | Use a Portainer auth token instead of `--user` and `--password` options, you can get it with the `psu login` command. Defaults to `null` |
|
|
| `-e` | `--endpoint=[ENDPOINT_ID]` | Which Docker endpoint to use. Defaults to `1` |
|
|
| `-q` | `--quiet` | Display the minimum of information or nothing, UNIX/Linux friendly. Defaults to `false` |
|
|
| `-i` | `--insecure` | Skip the host's SSL certificate verification, use at your own risk. Defaults to `false` |
|
|
| `-v` | `--verbose` | Increase the verbosity of messages. Defaults to `false` |
|
|
| `-d` | `--debug` | Print as much information as possible to help diagnosing a malfunction. Defaults to `false` |
|
|
| `-m` | `--masked-variables` | In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true\|extended\|false. Defaults to `false` |
|
|
| `-h` | `--help` | Display help message. To display help of a given action, run: `psu <action> --help` |
|
|
|
|
### `system:info`
|
|
Display Docker system-wide information.
|
|
|
|
#### Usage:
|
|
`psu system:info [options]`
|
|
|
|
#### Aliased action:
|
|
`docker:info`
|
|
|
|
#### Required options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-l` | `--url=URL` | URL of the Portainer instance |
|
|
| `-u` | `--user=USERNAME` | Username of the Portainer instance |
|
|
| `-p` | `--password=PASSWORD` | Password of the Portainer instance |
|
|
|
|
#### Optional options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-A` | `--auth-token=[AUTH_TOKEN]` | Use a Portainer auth token instead of `--user` and `--password` options, you can get it with the `psu login` command. Defaults to `null` |
|
|
| `-e` | `--endpoint=[ENDPOINT_ID]` | Which Docker endpoint to use. Defaults to `1` |
|
|
| `-i` | `--insecure` | Skip the host's SSL certificate verification, use at your own risk. Defaults to `false` |
|
|
| `-v` | `--verbose` | Increase the verbosity of messages. Defaults to `false` |
|
|
| `-d` | `--debug` | Print as much information as possible to help diagnosing a malfunction. Defaults to `false` |
|
|
| `-m` | `--masked-variables` | In debug/verbose mode, value of sensitive variables will be hidden, avoid leaking passwords/tokens in logs. Possible values: true\|extended\|false. Defaults to `false` |
|
|
| `-h` | `--help` | Display help message. To display help of a given action, run: `psu <action> --help` |
|
|
|
|
### `actions`
|
|
List available actions for this program.
|
|
|
|
#### Optional options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-v` | `--verbose` | Increase the verbosity of messages. Defaults to `false` |
|
|
| `-d` | `--debug` | Print as much information as possible to help diagnosing a malfunction. Defaults to `false` |
|
|
| `-h` | `--help` | Display help message. To display help of a given action, run: `psu <action> --help` |
|
|
|
|
### `help`
|
|
Display help message.
|
|
|
|
### `version`
|
|
Display this program version.
|
|
|
|
#### Optional options:
|
|
| Flag | Option | Description |
|
|
| ---------- | -------------------------------- | ----------- |
|
|
| `-h` | `--help` | Display help message. To display help of a given action, run: `psu <action> --help` |
|
|
|
|
## Options in details
|
|
|
|
### Stack environment variables
|
|
|
|
There can be set environment variables for each stack, be it a new deployment or an update. For example:
|
|
|
|
```bash
|
|
touch .env
|
|
echo "MYSQL_ROOT_PASSWORD=agoodpassword" >> .env
|
|
echo "ALLOWED_HOSTS=*" >> .env
|
|
psu deploy --user admin --password password --url https://portainer.local --name mystack --compose-file docker-compose.yml --env-file .env
|
|
```
|
|
|
|
Stack environment variables can be enabled through `ENVIRONMENT_VARIABLES_FILE` envvar or `--env-file` option or `-g` flag.
|
|
|
|
### Verbose mode
|
|
|
|
In verbose mode the script prints execution steps.
|
|
|
|
```text
|
|
Getting auth token...
|
|
Getting stack mystack...
|
|
Stack mystack not found.
|
|
Getting Docker info...
|
|
Getting swarm cluster (if any)...
|
|
Swarm cluster found.
|
|
Preparing stack JSON...
|
|
Creating stack mystack...
|
|
```
|
|
|
|
Verbose mode can be enabled through `VERBOSE_MODE` envvar or `--verbose` option or `-v` flag.
|
|
|
|
### Debug mode
|
|
|
|
In debug mode the script prints as much information as possible to help diagnosing a malfunction.
|
|
|
|
**WARNING**: Debug mode will print configuration values (with Portainer credentials) and Portainer API responses (with sensitive information like authentication token and stacks environment variables). Avoid using debug mode in CI/CD pipelines, as pipeline logs are usually recorded.
|
|
|
|
Debug mode can be enabled through `DEBUG_MODE` envvar or `--debug` option or `-d` flag.
|
|
|
|
### Strict mode
|
|
|
|
In strict mode the script never updates an existent stack nor removes an inexistent one, and instead exits with an error.
|
|
|
|
Strict mode can be enabled through `STRICT_MODE` envvar or `--strict` option or `-t` flag.
|
|
|
|
### Quiet mode
|
|
|
|
In quiet mode the script prints the minimum of informations or nothing.
|
|
|
|
It's inspired by the `--quiet` option of [`docker images`](https://docs.docker.com/engine/reference/commandline/images/#options) command.
|
|
|
|
Quiet mode can be enabled through `QUIET_MODE` envvar or `--quiet` option or `-q` flag.
|
|
|
|
### `detect-job` option
|
|
|
|
The `--detect-job` option (`true` by default) detects if a service has a restart policy set to `none` and considered this service as a [Job](#job).
|
|
If set to `false`, to considering a service as a [Job](#job), you need to set a container's [label](https://docs.docker.com/compose/compose-file/#labels-1) named `job-name` with the value you want (e.g. `my-job-service-name`) in the Docker compose/stack file.
|
|
|
|
_See the [Job definition](#job) section for more details._
|
|
|
|
## Glossary
|
|
|
|
### Job
|
|
|
|
Docker (or Portainer) doesn't have a true [Job](https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/) mechanism like [Kubernetes](https://kubernetes.io).
|
|
|
|
But `psu` use an equivalent Docker behavior, based on filtering tasks status with a specific container's [label](https://docs.docker.com/compose/compose-file/#labels-1) (`job-name`).
|
|
Or when, in your Docker compose/stack file, a service [`deploy.restart_policy.condition`](https://docs.docker.com/compose/compose-file/#restart_policy) option is set to `none`.
|
|
|
|
The `psu` definition of a job is a Swarm [service](https://docs.docker.com/engine/swarm/how-swarm-mode-works/services/) who ensures that all its specified [task(s)](https://docs.docker.com/engine/swarm/how-swarm-mode-works/swarm-task-states/) successfully terminate.
|
|
|
|
Using a job is useful when you want to have a service who run a script (e.g. database migration).
|
|
And shutdown this service when its script is successfully executed.
|
|
|
|
See the service named `job` in the [`docker-stack-web-app.yml`](https://gitlab.com/psuapp/psu/tree/v1.0.2/tests/dockerfiles/docker-stack-web-app.yml) file, for a real use case.
|
|
It has both a container's label `job-name` and a restart policy set to `none`.
|