portainer-deployer 0.0.3

A command-line tool to abstract some Portainer's features by using its API.

Portainer Deployer

---

Portainer API simplified through command-line interface.

📝 Table of Contents

• About
• Getting Started
• Configuring
• Usage
• Built Using
• Authors
• Acknowledgments
• Contributing

⚠️Important Notice⚠️

This is not an official Portainer software, it is just and Open Source tool to make an abstraction of Portainer's API.

🧐 About

Portainer Deployer is a Command-line interface tool developed in Python to abstract some Portainer's features by using its API. The principal use case for this application is to manage Stacks in the CI/CD process, making it faster and easy.

🏁 Getting Started

First steps with Portainer Deployer are about installing and running your first commands. There are multiple installation methods, and they all will be listed in this section, but before you need to create the config directory and the config file.

$ mkdir -p /etc/pd-config # Or wherever you want
$ curl -o /etc/pd-config/default.conf https://raw.githubusercontent.com/Jorgmassih/portainer-deployer/main/portainer_deployer/app.conf.example
$ chgrp -R $USER /etc/pd-config && chmod -R 774 /etc/pd-config

This step should be executed before all installation methods. If you have already done that, you can skip to the next steps.

Note: Probably you will need to use sudo for creating the configuration folder and downloading the config template fil.e

Installation

This method requires a modern stable version of Python 3.8.x or greater already installed.

Then, you should be able to downloading the app vía pip

$ python -m pip install --upgrade pip
$ python -m pip install portainer-deployer
$ portainer-deployer --version

If you want to avoid installing the portainer-deployer dependencies in your main python environment you can create a virtual environment before installing it:

$ mkdir ~/portainer-deployer-env && cd ~/portainer-deployer-env
$ python -m venv pd_env && source ./pd_env/bin/activate
$ python -m pip install --upgrade pip
$ python -m pip install portainer-deployer
$ portainer-deployer --version

For more information abunt virtual environments, please consult the Official Documentation.

Since Portainer Deployer is a command line tool, you can invoke the application by running portainer-deployer after installation. We know that could be tedious using the entire command to call the application, so, feel free to use an alias. e.g.

$ alias pd="portainer-deployer"

Docker installation

This is the recommended method in case you don't have the required Python version or simply any installation of Python.

If you want to use the tool but without installing it in your environment to avoid overlaping with others applications, or if you are a Windows user, this could be a fancy solution for you.

The idea is create an isolation for executing the applicatión in a recommended stable environment.

To get started with this method make sure you have a stable version of Docker installed by running docker -v and run the following snippet:

$ docker pull jorgmassih/portainer-deployer
$ docker run --rm -v path/to/config/file:/etc/pdcli/app.conf portainer-deployer --version # change --version for your desired command of portainer-deployer

Optionally you could use an alias for simplifying the command.

$ alias pd="docker run --rm -v path/to/config/file:/etc/pdcli/app.conf portainer-deployer"
$ pd --help

Binary installation will be available soon in next releases. Please be patient.

Post Installation

Before starting using Portainer Deployer normally, you will need to set some configurations to set up the connection with Portainer API. This can be easily managed by running portainer-deployer config <config arguments goes here>. You can go more in deep the config section later.

Examples

Get all the Stacks from portainer

$ portainer-deployer get --all 

Get Stacks by its id

$ portainer-deployer get --id <random-id>

Deploy Stack from file by specifying its path

$ portainer-deployer deploy --path /path/to/my/docker-compose.yml --endpoint 45 --update-keys a.b.c=value e.f.g='[value2,value3...value4]' --name myStack

Deploy Stack passing string through standard input (stdin)

$ cat /path/to/my/docker-compose.yml | portainer-deployer deploy --endpoint 2 --name myStack

or

$ portainer-deployer deploy --endpoint 2 --name myStack "version: 3\n services:\n web:\n image:nginx"

Notice that using the stdin can be faster than specifying a path to be processed by the program, otherwise, specifying a path grants access to some features such as modifying some keys in runtime by using the arguments --update-keys or -u.

You can consult more information about allowed arguments and subcommands by running portainer-deployer --help or portainer-deployer -h.

🔧 Configuring

The first thing you need to set up is the configuration path by running portainer-deployer config --config-path <YOUR ABSOLUTE PATH TO CONFIG FILE>.

For example:

$ portainer-deployer config --config-path /etc/pd-config/default.conf 
Config path updated to: /etc/pd-config/default.conf

Note: setting the config path is just valid for all installation methods except Docker installation method.

Setting configurations in the config file

There are two ways to go ahead with the configuration, the first one is by using the config sub-command to set all necessary variables. The another one is by editing directly the config file. The first one mentioned is strongly recommended to avoid misconfigurations.

Using the config sub-command

By Entering portainer-deployer config --help in your shell you will receive:

$ portainer-deployer config --help                                                                                                                           
usage: portainer-deployer config [-h] [--set SET [SET ...] | --get GET | --config-path CONFIG_PATH]

optional arguments:
  -h, --help            show this help message and exit
  --set SET [SET ...], -s SET [SET ...]
                        Set a config value specifying the section, key and value. e.g. --set section.url='http://localhost:9000'
  --get GET, -g GET     Get a config value. e.g. --get section.port
  --config-path CONFIG_PATH, -c CONFIG_PATH
                        Set Portainer Deployer absulute config path. e.g. --config-path /abusolute/path/to/default.conf

Notice that you have to use the nomenclature of section.key='new value'.

The following table list the available sections:

Section	Description
PORTAINER	All concerning configuration to Portainer API connection.

Also, here is a list of all keys of the variables that can be set and get:

Variable Key	Choices/Defaults	Description
url		Portainer URL to connect. e.g. https://10.0.0.3
port		Port to reach out Portainer host.
username		Username to connect to the API.
token		Token given by Portainer to connect to the API.
ssl	yes, no	Use SSL for secure connections.

Examples

Set Portainer url

$ portainer-deployer config --set portainer.url='https://localhost'

Get Portainer port

$ portainer-deployer config --get portainer.port

In case of you try to set a variable not listed beffore, the operation won't take effect.

Editing the config file

This method consist in editing the file you set by running portainer-deployer config --config-path <YOUR PATH> at the moment of installation, therefore you need the right privileges to access to that file.

The config file is written in INI format and looks like:

# app.conf
[PORTAINER]
url = https://your-portainer.host.lab
port = 9443
username = <YOUR PORTAINER USERNAME>
token = <YOUR PORTAINER TOKEN>
ssl = yes #It can be yes or not, [T,t]rue or [F,f]alse

Note: If you are using the Docker installation method make sure to create a volume with the configuration file inside.

🎈 Usage

Portainer Deployer is composed by 3 main sub-commands:

• get
• deploy
• config (explained in the past section)

In this reading we are going to focus in get and deploy sub-commands.

The get sub-command

By runnnig portainer-deployer get you will be able to retrive stacks information from Portainer by name or id, you can retreive information of all stacks by setting the --all argument.

The command portainer-deployer get -h will result in:

$ portainer-deployer get --help                                                                        
usage: portainer-deployer get [-h] [--id ID | --name NAME | --all]

Get a stack info from portainer.

optional arguments:
  -h, --help            show this help message and exit
  --id ID               Id of the stack to look for
  --name NAME, -n NAME  Name of the stack to look for
  --all, -a             Gets all stacks

The deploy sub-command

This one allows to post stacks and run them in Portainer, it can be done by passing the string as stdin or by passing the path to the yml file.

$ portainer-deployer deploy --help
usage: portainer-deployer deploy [-h] [--path PATH] [--name NAME] [--update-keys UPDATE_KEYS [UPDATE_KEYS ...]] --endpoint ENDPOINT [stack]

positional arguments:
  stack                 Docker Compose string for the stack

optional arguments:
  -h, --help            show this help message and exit
  --path PATH, -p PATH  The path to Docker Compose file for the stack. An alternative to pass the stack as string
  --name NAME, -n NAME  Name of the stack to look for
  --update-keys UPDATE_KEYS [UPDATE_KEYS ...], -u UPDATE_KEYS [UPDATE_KEYS ...]
                        Modify the stack file by passing a list of key=value pairs, where the key is in dot notation. i.e. a.b.c=value1 d='[value2,
                        value3]'
  --endpoint ENDPOINT, -e ENDPOINT
                        Endponint Id to deploy the stack

⛏️ Built Using

• Python 🐍 - Core Programming Language
• argparse - Main Python library for parsing arguments

✍️ Authors

• @jorgmassih👨‍💻 - Idea & Initial work

🎉 Acknowledgements

• Portainer and its development team
• My Collage Professor Rodrigo Orizondo (@yoyirod) 🕊️🙏 for the inspiration
• The DevOps community

🤝 Contributing

I'm open to contributions! If you are insterested in collaboring, you can contact me via the info of my bio.