mirror of
https://gitlab.com/psuapp/psu.git
synced 2024-08-30 18:12:34 +00:00
248 lines
11 KiB
Markdown
248 lines
11 KiB
Markdown
<h1>Portainer Stack Utils</h1>
|
|
<div class="docsify-hidden">
|
|
|
|
[](https://hub.docker.com/r/psuapp/psu/)
|
|
[](https://gitlab.com/psuapp/psu/commits/1-3-next)
|
|
|
|
Bash script to deploy/update/remove stacks in a [Portainer](https://portainer.io/) instance from a [docker-compose](https://docs.docker.com/compose) [yaml file](https://docs.docker.com/compose/compose-file).
|
|
|
|
_Based on previous work by [@vladbabii](https://github.com/vladbabii) on [docker-how-to/portainer-bash-scripts](https://github.com/docker-how-to/portainer-bash-scripts)._
|
|
|
|
<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 -->
|
|
|
|
- [How to install](#how-to-install)
|
|
- [Standalone](#standalone)
|
|
- [Docker image and variants](#docker-image-and-variants)
|
|
- [How to use](#how-to-use)
|
|
- [With options](#with-options)
|
|
- [With flags](#with-flags)
|
|
- [With envvars](#with-envvars)
|
|
- [Documentation](#documentation)
|
|
- [Supported Portainer API](#supported-portainer-api)
|
|
- [License](#license)
|
|
|
|
<!-- /MDTOC -->
|
|
</div>
|
|
|
|
## How to install
|
|
|
|
### Standalone
|
|
|
|
Just clone the repo and use the script:
|
|
|
|
```bash
|
|
git clone https://gitlab.com/psuapp/psu.git
|
|
cd psu/
|
|
# Allow the 'psu' command to run everywhere:
|
|
export PATH="$(pwd):$PATH"
|
|
# Or if you want it permanent, with a super user account, run:
|
|
# ln -s $(pwd)/psu /usr/local/bin
|
|
#
|
|
# Then you can use psu, e.g.
|
|
psu deploy ...
|
|
```
|
|
|
|
For detailed instructions, see [How to use](#how-to-use) section.
|
|
|
|
#### Requirements
|
|
|
|
You will need these dependencies installed:
|
|
|
|
- [bash](https://www.gnu.org/software/bash/)<sup title="required">*</sup> <small>(>= 5.0.3)</small>
|
|
- [curl](https://curl.se/)<sup title="required">*</sup> <small>(>= 7.64.0, but >= 7.76.0 is recommended)</small>
|
|
- [jq](https://stedolan.github.io/jq/)<sup title="required">*</sup> <small>(>= 1.5.1)</small>
|
|
- [timeout](https://man7.org/linux/man-pages/man1/timeout.1.html)<sup title="required">*</sup> <small>For macOS run: `brew install coreutils`</small>
|
|
- [uuidgen](https://man7.org/linux/man-pages/man1/uuidgen.1.html) only for some <abbr title="Operating System">OS</abbr> <small>(Debian and Alpine work fine without it)</small>
|
|
|
|
<sup>\*</sup> = required
|
|
|
|
For Debian and similar apt-powered systems: `apt install bash curl jq`
|
|
|
|
### Docker image and variants
|
|
|
|
If you don't want or can't install `psu` and its dependencies, you can run it with the default [published Docker image](https://hub.docker.com/r/psuapp/psu), like this:
|
|
```bash
|
|
docker run psuapp/psu:1.2 deploy ...
|
|
```
|
|
> **Note**: Docker images are also available on [GitLab](https://gitlab.com/psuapp/psu/container_registry).
|
|
|
|
For detailed instructions, see [How to use](#how-to-use) section.
|
|
|
|
#### Supported tags
|
|
|
|
Published Docker images are [tagged](https://hub.docker.com/r/psuapp/psu/tags) matching [GitLab tags](https://gitlab.com/psuapp/psu/-/tags):
|
|
|
|
<!-- - `dev` -> [`dev`](https://gitlab.com/psuapp/psu/-/tags/dev) -->
|
|
|
|
- `1.3.0-alpha` -> [`v1.3.0-alpha`](https://gitlab.com/psuapp/psu/-/tags/v1.3.0-alpha)
|
|
- `1`, `1.2`, `1.2.0` -> [`v1.2.0`](https://gitlab.com/psuapp/psu/-/tags/v1.2.0)
|
|
- `1.2.0-beta.1` -> [`v1.2.0-beta.1`](https://gitlab.com/psuapp/psu/-/tags/v1.2.0-beta.1)
|
|
- `1.2.0-alpha` -> [`v1.2.0-alpha`](https://gitlab.com/psuapp/psu/-/tags/v1.2.0-alpha)
|
|
- `1.1`, `1.1.0` -> [`v1.1.0`](https://gitlab.com/psuapp/psu/-/tags/v1.1.0)
|
|
- `1.1.0-alpha` -> [`v1.1.0-alpha`](https://gitlab.com/psuapp/psu/-/tags/v1.1.0-alpha)
|
|
- `1.0`, `1.0.7` -> [`v1.0.7`](https://gitlab.com/psuapp/psu/-/tags/v1.0.7)
|
|
- `1.0.6` -> [`v1.0.6`](https://gitlab.com/psuapp/psu/-/tags/v1.0.6)
|
|
- `1.0.5` -> [`v1.0.5`](https://gitlab.com/psuapp/psu/-/tags/v1.0.5)
|
|
- `1.0.4` -> [`v1.0.4`](https://gitlab.com/psuapp/psu/-/tags/v1.0.4)
|
|
- `1.0.3` -> [`v1.0.3`](https://gitlab.com/psuapp/psu/-/tags/v1.0.3)
|
|
- `1.0.2` -> [`v1.0.2`](https://gitlab.com/psuapp/psu/-/tags/v1.0.2)
|
|
- `1.0.1` -> [`v1.0.1`](https://gitlab.com/psuapp/psu/-/tags/v1.0.1)
|
|
- `1.0.0` -> [`v1.0.0`](https://gitlab.com/psuapp/psu/-/tags/v1.0.0)
|
|
- `0.1.2` -> [`v0.1.2`](https://gitlab.com/psuapp/psu/-/tags/v0.1.2)
|
|
- `0.1.1` -> [`v0.1.1`](https://gitlab.com/psuapp/psu/-/tags/v0.1.1)
|
|
- `0.1.0` -> [`v0.1.0`](https://gitlab.com/psuapp/psu/-/tags/v0.1.0)
|
|
|
|
##### Variants
|
|
|
|
The `core` variant doesn't include `docker-compose`, so it's a bit smaller.
|
|
But you can't lint Docker compose/stack file before deploying a stack.
|
|
<!-- - `dev-core` -> [`dev`](https://gitlab.com/psuapp/psu/-/tags/dev) -->
|
|
|
|
- `1-core`, `1.2-core`, `1.2.0-core` -> [`v1.2.0`](https://gitlab.com/psuapp/psu/-/tags/v1.2.0)
|
|
- `1.1-core`, `1.1.0-core` -> [`v1.1.0`](https://gitlab.com/psuapp/psu/-/tags/v1.1.0)
|
|
- `1.0-core`, `1.0.7-core` -> [`v1.0.7`](https://gitlab.com/psuapp/psu/-/tags/v1.0.7)
|
|
|
|
The `debian` and `debian-core` variants use [Debian](https://www.debian.org) instead of [Alpine](https://alpinelinux.org/) as base image for `psu`.
|
|
<!-- - `dev-debian` -> [`dev`](https://gitlab.com/psuapp/psu/-/tags/dev)
|
|
- `dev-debian-core` -> [`dev`](https://gitlab.com/psuapp/psu/-/tags/dev) -->
|
|
|
|
- `1-debian`, `1.2-debian`, `1.2.0-debian` -> [`v1.2.0`](https://gitlab.com/psuapp/psu/-/tags/v1.2.0)
|
|
- `1-debian-core`, `1.2-debian-core`, `1.2.0-debian-core` -> [`v1.2.0`](https://gitlab.com/psuapp/psu/-/tags/v1.2.0)
|
|
- `1.1-debian`, `1.1.0-debian` -> [`v1.1.0`](https://gitlab.com/psuapp/psu/-/tags/v1.1.0)
|
|
- `1.1-debian-core`, `1.1.0-debian-core` -> [`v1.1.0`](https://gitlab.com/psuapp/psu/-/tags/v1.1.0)
|
|
- `1.0-debian`, `1.0.7-debian` -> [`v1.0.7`](https://gitlab.com/psuapp/psu/-/tags/v1.0.7)
|
|
- `1.0-debian-core`, `1.0.7-debian-core` -> [`v1.0.7`](https://gitlab.com/psuapp/psu/-/tags/v1.0.7)
|
|
|
|
#### Testing/debugging:
|
|
|
|
For testing/debugging, you can use this Docker image in interactive mode, to run any commands inside the container:
|
|
```bash
|
|
docker run -v $(pwd)/docker-compose.yml:/docker-compose.yml -it --rm --entrypoint bash psuapp/psu:1.2
|
|
# Run any commands here! E.g.
|
|
$ psu --version
|
|
Portainer Stack Utils, version 1.3.0-alpha
|
|
License GPLv3: GNU GPL version 3
|
|
```
|
|
|
|
## How to use
|
|
|
|
The provided `psu` script allows to deploy/update/remove... Portainer stacks. Settings can be passed through envvars and/or options and/or flags. Both envvars, options and flags can be mixed but options or flags will always overwrite envvar values. When deploying a stack, if it doesn't exist a new one is created, otherwise it's updated (unless strict mode is active).
|
|
|
|
### With options
|
|
|
|
This is more suitable for standalone script usage.
|
|
|
|
- `<action>` ("deploy", "rm", "ls"..., required): Whether to deploy, remove, list... the stack, _not an option but an argument_
|
|
- `--user` (string, required): Username
|
|
- `--password` (string, required): Password
|
|
- `--url` (string, required): URL to Portainer
|
|
- `--name` (string, required): Stack name
|
|
- `--compose-file` (string, required if action=deploy): Path to docker-compose file
|
|
|
|
For detailed instructions, see the full [options list](docs/README.md#available-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
|
|
```
|
|
|
|
```bash
|
|
psu rm --user admin --password password --url https://portainer.local --name mystack
|
|
```
|
|
|
|
**With Docker:**
|
|
```bash
|
|
docker run -v $(pwd)/docker-compose.yml:/docker-compose.yml -v $(pwd)/.env:/.env psuapp/psu:1.2 deploy --user admin --password password --url https://portainer.local --name mystack --compose-file docker-compose.yml --env-file .env
|
|
```
|
|
|
|
### With flags
|
|
|
|
This is more suitable for standalone script usage.
|
|
|
|
- `<action>` ("deploy", "rm", "ls"..., required): Whether to deploy, remove, list... the stack, _not a flag but an argument_
|
|
- `-u` (string, required): Username
|
|
- `-p` (string, required): Password
|
|
- `-l` (string, required): URL to Portainer
|
|
- `-n` (string, required): Stack name
|
|
- `-c` (string, required if action=deploy): Path to docker-compose file
|
|
|
|
For detailed instructions, see the full [flags list](docs/README.md#available-options).
|
|
|
|
#### Examples
|
|
|
|
```bash
|
|
psu deploy -u admin -p password -l https://portainer.local -n mystack -c /path/to/docker-compose.yml -g /path/to/env_vars_file
|
|
```
|
|
|
|
```bash
|
|
psu rm -u admin -p password -l https://portainer.local -n mystack
|
|
```
|
|
|
|
**With Docker:**
|
|
```bash
|
|
docker run -v $(pwd)/docker-compose.yml:/docker-compose.yml -v $(pwd)/.env:/.env psuapp/psu:1.2 deploy -u admin -p password -l https://portainer.local -n mystack -c docker-compose.yml -g .env
|
|
```
|
|
|
|
### With envvars
|
|
|
|
This is particularly useful for [CI](https://en.wikipedia.org/wiki/Continuous_integration)/[CD](https://en.wikipedia.org/wiki/Continuous_deployment) pipelines using Docker containers.
|
|
|
|
- `ACTION` ("deploy", "rm", "ls"..., required): Whether to deploy, remove, list... the stack
|
|
- `PORTAINER_USER` (string, required): Username
|
|
- `PORTAINER_PASSWORD` (string, required): Password
|
|
- `PORTAINER_URL` (string, required): URL to Portainer
|
|
- `PORTAINER_STACK_NAME` (string, required): Stack name
|
|
- `DOCKER_COMPOSE_FILE` (string, required if action=deploy): Path to docker-compose file
|
|
|
|
For detailed instructions, see the full [envvars list](docs/README.md#available-environment-variables).
|
|
|
|
#### Examples
|
|
|
|
```bash
|
|
export ACTION="deploy"
|
|
export PORTAINER_USER="admin"
|
|
export PORTAINER_PASSWORD="password"
|
|
export PORTAINER_URL="https://portainer.local"
|
|
export PORTAINER_STACK_NAME="mystack"
|
|
export DOCKER_COMPOSE_FILE="/path/to/docker-compose.yml"
|
|
export ENVIRONMENT_VARIABLES_FILE="/path/to/env_vars_file"
|
|
|
|
psu
|
|
```
|
|
|
|
```bash
|
|
export ACTION="rm"
|
|
export PORTAINER_USER="admin"
|
|
export PORTAINER_PASSWORD="password"
|
|
export PORTAINER_URL="https://portainer.local"
|
|
export PORTAINER_STACK_NAME="mystack"
|
|
|
|
psu
|
|
```
|
|
|
|
**With Docker:**
|
|
```bash
|
|
docker run -v $(pwd)/docker-compose.yml:/docker-compose.yml -v $(pwd)/.env:/.env -e ACTION="deploy" -e PORTAINER_USER="admin" -e PORTAINER_PASSWORD="password" -e PORTAINER_URL="https://portainer.local" -e PORTAINER_STACK_NAME="mystack" -e DOCKER_COMPOSE_FILE="docker-compose.yml" -e ENVIRONMENT_VARIABLES_FILE=".env" psuapp/psu:1.2
|
|
```
|
|
|
|
## Documentation
|
|
|
|
<div class="docsify-hidden">
|
|
For advanced usage, see the full <a href="https://psuapp.gitlab.io/psu/1-2-stable"><abbr title="Portainer Stack Utils">PSU</abbr> documentation</a>.
|
|
</div>
|
|
|
|
For detailed instructions, see the [CLI Commands](docs/README.md) documentation.
|
|
|
|
## Supported Portainer API
|
|
|
|
<abbr title="Portainer Stack Utils">PSU</abbr> was created for the latest versions of Portainer API, which at the time of writing are [1.24.2](https://app.swaggerhub.com/apis/deviantony/Portainer/1.24.1), [2.1.1](https://app.swaggerhub.com/apis/deviantony/Portainer/2.0.1), [2.5.1](https://documentation.portainer.io/api/api-schema-ce) and [2.6.3](https://documentation.portainer.io/api/api-schema-ce).
|
|
|
|
## License
|
|
|
|
Source code contained by this project is licensed under the [GNU General Public License version 3](https://www.gnu.org/licenses/gpl-3.0.en.html).
|
|
|
|
See [LICENSE](LICENSE) file for reference.
|