psu/README.md

Portainer Stack Utils

Bash script to deploy/update/remove stacks in a Portainer instance from a docker-compose yaml file.

Based on previous work by @vladbabii on docker-how-to/portainer-bash-scripts.

Table of contents

• How to install
  • Standalone
  • Docker image, variants and multi-architecture
• How to use
  • With options
  • With flags
  • With envvars
• Documentation
• Supported Portainer API
• License

How to install

Standalone

Note

: The easiest way to install psu is to use Docker method, instead of this one

Check the Requirements section then git clone the repo and use the bash script below:

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 section.

Requirements

You will need these dependencies installed:

Linux based systems (Alpine, Debian, Ubuntu...)

• bash^* (>= 4.4.23)
• curl^* (>= 7.64.0, but >= 7.76.0 is recommended)
• jq^* (>= 1.5.1)
• uuidgen recommended only for some OS (Alpine and Debian work fine without it)

For Debian and similar apt-powered Linux systems, run: apt install bash curl jq

macOS

• bash^* (>= 4.4.23)
• curl^* (>= 7.64.0, but >= 7.76.0 is recommended)
• jq^* (>= 1.5.1)
• timeout^* (included in the coreutils package)
• greadlink (included in the coreutils package)

You should install Homebrew, then run: brew install bash coreutils jq

Windows

• bash^* (>= 4.4.23)
• curl^* (>= 7.64.0, but >= 7.76.0 is recommended)
• jq^* (>= 1.5.1)

Note

: psushould work with Windows, but it could be unstable ⚠️

You should download and install Git and jq for Windows

For all systems

• docker-compose is recommended but not required (useful for linting docker compose/stack files)

^* = required

Docker image, variants and multi-architecture

If you don't want or can't install psu and its dependencies, you can run it with the default published Docker image, like this:

docker run psuapp/psu:1.3 deploy ...

Note

: Docker images are also available on GitLab.

For detailed instructions, see How to use section.

Supported tags

Published Docker images are tagged matching GitLab tags:

• 1, 1.3, 1.3.1 -> v1.3.1
• 1.3.0-beta.1 -> v1.3.0-beta.1
• 1.3.0-alpha -> v1.3.0-alpha
• 1.2, 1.2.0 -> v1.2.0
• 1.2.0-beta.1 -> v1.2.0-beta.1
• 1.2.0-alpha -> v1.2.0-alpha
• 1.1, 1.1.0 -> v1.1.0
• 1.1.0-alpha -> v1.1.0-alpha
• 1.0, 1.0.7 -> v1.0.7
• 1.0.6 -> v1.0.6
• 1.0.5 -> v1.0.5
• 1.0.4 -> v1.0.4
• 1.0.3 -> v1.0.3
• 1.0.2 -> v1.0.2
• 1.0.1 -> v1.0.1
• 1.0.0 -> v1.0.0
• 0.1.2 -> v0.1.2
• 0.1.1 -> v0.1.1
• 0.1.0 -> 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.

• 1-core, 1.3-core, 1.3.1-core -> v1.3.1
• 1.2-core, 1.2.0-core -> v1.2.0
• 1.1-core, 1.1.0-core -> v1.1.0
• 1.0-core, 1.0.7-core -> v1.0.7

The debian and debian-core variants use Debian instead of Alpine as base image for psu.

• 1-debian, 1.3-debian, 1.3.1-debian -> v1.3.1
• 1-debian-core, 1.3-debian-core, 1.3.1-debian-core -> v1.3.1
• 1.2-debian, 1.2.0-debian -> v1.2.0
• 1.2-debian-core, 1.2.0-debian-core -> v1.2.0
• 1.1-debian, 1.1.0-debian -> v1.1.0
• 1.1-debian-core, 1.1.0-debian-core -> v1.1.0
• 1.0-debian, 1.0.7-debian -> v1.0.7
• 1.0-debian-core, 1.0.7-debian-core -> v1.0.7

Multi-Architecture

The Docker images support multi-architecture: linux/amd64, linux/arm64 and linux/arm/v7.

On ARM machines, if you get this error when running a psu Docker image:

standard_init_linux.go:228: exec user process caused: exec format error

You need to install linux/amd64 QEMU binary, like this:

docker run --privileged --rm tonistiigi/binfmt --install linux/amd64

Then run your psu Docker image again and it should work 🤞

And if you want to uninstall this QEMU binary, run this command:

docker run --privileged --rm tonistiigi/binfmt --uninstall linux/amd64

Testing/debugging:

For testing/debugging, you can use this Docker image in interactive mode, to run any commands inside the container:

docker run -v $(pwd)/docker-compose.yml:/docker-compose.yml -it --rm --entrypoint bash psuapp/psu:1.3
# Run any commands here! E.g.
$ psu --version
Portainer Stack Utils, version 1.3.1
  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.

Examples

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

psu rm --user admin --password password --url https://portainer.local --name mystack

With Docker:

docker run -v $(pwd)/docker-compose.yml:/docker-compose.yml -v $(pwd)/.env:/.env psuapp/psu:1.3 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.

Examples

psu deploy -u admin -p password -l https://portainer.local -n mystack -c /path/to/docker-compose.yml -g /path/to/env_vars_file

psu rm -u admin -p password -l https://portainer.local -n mystack

With Docker:

docker run -v $(pwd)/docker-compose.yml:/docker-compose.yml -v $(pwd)/.env:/.env psuapp/psu:1.3 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/CD 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.

Examples

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

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:

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.3

Documentation

For advanced usage, see the full PSU documentation.

For detailed instructions, see the CLI Commands documentation.

Supported Portainer API

PSU was created for the latest versions of Portainer API, which at the time of writing are 1.24.2, 2.6.3, 2.9.3 and 2.11.0.

License

Source code contained by this project is licensed under the GNU General Public License version 3.

See LICENSE file for reference.