Package: portainer-deployer
Portainer DeployerPortainer API simplified through command-line interface.📝 Table of ContentsAboutGetting StartedConfiguringUsageBuilt UsingAuthorsAcknowledgmentsContributing⚠️Important Notice⚠️This is not an officialPortainersoftware, it is just an Open Source tool to make an abstraction of Portainer's API.🧐 AboutPortainer Deployeris aCommand-line interfacetool developed in Python to abstract somePortainer's features by using itsAPI. The principal use case for this application is to manage Stacks in the CI/CD process, making it faster and easy.🏁 Getting StartedThe 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.confhttps://raw.githubusercontent.com/Jorgmassih/portainer-deployer/main/portainer_deployer/app.conf.example
$chgrp-R$USER/etc/pd-config&&chmod-R774/etc/pd-configThis step should be executed beforeallinstallation methods. If you have already done that, you can skip to the next steps.Note: Probably you will need to usesudofor creating the configuration folder and downloading the config template fileInstallationPython 3.8.xor greater is required for this project to run correctly.You should be able to download it vía pip$python-mpipinstall--upgradepip
$python-mpipinstallportainer-deployer
$portainer-deployer--versionIf you want to avoid installing theportainer-deployerdependencies in your main python environment you can create a virtual environment before installing it:$mkdir~/portainer-deployer-env&&cd~/portainer-deployer-env
$python-mvenvpd_env&&source./pd_env/bin/activate
$python-mpipinstall--upgradepip
$python-mpipinstallportainer-deployer
$portainer-deployer--versionFor more information about virtual environments, please consult theOfficial Documentation.SincePortainer Deployeris a command-line tool, you can invoke the application by runningportainer-deployerafter installation. We know that could be tedious to use the entire command to call the application, so, feel free to use an alias. e.g.$aliaspd="portainer-deployer"Docker installationThis 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 overlapping with other applications, or if you are aWindowsuser, this could be a fancy solution for you.The idea is to create isolation for executing the applicatión in a recommended stable environment.To get started with this method make sure you have astable versionof Docker installed by runningdocker -vand run the following snippet:$dockerpulljorgmassih/portainer-deployer
$dockerrun--rm-vpath/to/config/file:/etc/pdcli/app.confportainer-deployer--version# change --version for your desired command of portainer-deployerOptionally you could use analiasfor simplifying the command.$aliaspd="docker run --rm -v path/to/config/file:/etc/pdcli/app.conf portainer-deployer"$pd--helpBinary installationwill be available soon in the next releases. Please be patient.Post InstallationBefore 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 runningportainer-deployer config <config arguments goes here>. You can go more in deep theconfig sectionlater.ExamplesGet all the Stacks from portainer$portainer-deployerget--allGet Stacks by its id$portainer-deployerget--id<random-id>Deploy Stack from file by specifying its path$portainer-deployerdeploy--path/path/to/my/docker-compose.yml--endpoint45--update-keysa.b.c=valuee.f.g='[value2,value3...value4]'--namemyStackDeploy Stack passing string throughstandard input (stdin)$cat/path/to/my/docker-compose.yml|portainer-deployerdeploy--endpoint2--namemyStackor$portainer-deployerdeploy--endpoint2--namemyStack"version: 3\n services:\n web:\n image:nginx"Noticethat using thestdincan 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-keysor-u.You can consult more information about allowed arguments and subcommands by runningportainer-deployer --helporportainer-deployer -h.🔧 ConfiguringThe first thing you need to set up is the configuration path by runningportainer-deployer config --config-path <YOUR ABSOLUTE PATH TO CONFIG FILE>.For example:$portainer-deployerconfig--config-path/etc/pd-config/default.confConfigpathupdatedto:/etc/pd-config/default.confNote: setting the config path is just valid forallinstallation methods exceptDocker installation method.Setting configurations in the config fileThere are two ways to go ahead with the configuration, the first one is by using theconfigsub-command to set all necessary variables. Another one is by editing directly theconfig file. The first one mentioned is strongly recommended to avoid misconfigurations.Using theconfigsub-commandBy Enteringportainer-deployer config --helpin your shell you will receive:$portainer-deployerconfig--helpusage:portainer-deployerconfig[-h][--setSET[SET...]|--getGET|--config-pathCONFIG_PATH]optionalarguments:-h,--helpShowhelpmessageandexit.--setSET[SET...],-sSET[SET...]Setaconfigvaluespecifyingthesection,keyandvalue.e.g.--setsection.url='http://localhost:9000'--getGET,-gGETGetaconfigvalue.e.g.--getsection.port--config-pathCONFIG_PATH,-cCONFIG_PATHSetPortainerDeployerabsuluteconfigpath.e.g.--config-path/abusolute/path/to/default.confNoticethat you have to use the nomenclature ofsection.key='new value'.The following table list the available sections:SectionDescriptionPORTAINERAll concerning configuration to Portainer API connection.Also, here is a list of all keys of the variables that can be set and gotten:KeyChoices/DefaultsDescriptionurlPortainer URL to connect. e.g.https://10.0.0.3usernameUsername to connect to the API.tokenToken given by Portainer to connect to the API.verify_sslyes, noIn case of "no" skip ssl verification.ExamplesSet Portainerurl$portainer-deployerconfig--setportainer.url='https://localhost:9443'Get Portainerusername$portainer-deployerconfig--getportainer.usernameIn the case ofyou try to set a variable not listed before, the operation won't take effect.Editing theconfig fileThis method consists in editing the file you set by runningportainer-deployer config --config-path <YOUR PATH>at the moment of installation, therefore you need the right privileges to access that file.The config file is written inINIformat and looks like this:# app.conf[PORTAINER]url=https://your-portainer.host.labusername=<YOUR PORTAINER USERNAME>token=<YOUR PORTAINER TOKEN>verify_ssl=yes#It can be yes or not, [T,t]rue or [F,f]alseNote: If you are using the Docker installation method make sure to create a volume with the configuration file inside.🎈 UsagePortainer Deployer is composed of 4 main sub-commands:getdeployremoveconfig(explained in the past section)In this reading, we are going to focus onget,deployandremovesub-commands.Thegetsub-commandBy runningportainer-deployer getyou will be able to retrieve stacks information from Portainer bynameorid, you can retreive information of all stacks by setting the--allargument.The commandportainer-deployer get -hwill result in:$portainer-deployerget--helpusage:portainer-deployerget[-h][--idID|--nameNAME|--all]GetstackinfofromPortainer.

optionalarguments:-h,--helpShowhelpmessageandexit.--idIDIdofthestacktolookfor--nameNAME,-nNAMENameofthestacktolookfor--all,-aGetsallstacksThedeploysub-commandThis one allows to post stacks and run them in Portainer, it can be done by passing the string asstdinor passing thepathto theymlfile.$portainer-deployerdeploy--help
usage:portainer-deployerdeploy[-h][--pathPATH][--nameNAME][--update-keysUPDATE_KEYS[UPDATE_KEYS...]]--endpointENDPOINT[stack]positionalarguments:stackDockerComposestringforthestack

optionalarguments:-h,--helpShowhelpmessageandexit.--pathPATH,-pPATHThepathtoDockerComposefileforthestack.Analternativeistopassthestackasastring.--nameNAME,-nNAMENameofthestacktolookfor.--update-keysUPDATE_KEYS[UPDATE_KEYS...],-uUPDATE_KEYS[UPDATE_KEYS...]Modifythestackfilebypassingalistofkey=valuepairs,wherethekeyisindotnotation.i.e.a.b.c=value1d='[value2, value3]'--redeploy,-RRe-deplyincaseofstacksexists.-yAcceptredeployanddonotaskforconfirmationbeforeredeployingthestack.--endpointENDPOINT,-eENDPOINTEndpointIdtodeploythestack.You can redeploy a stack by using the--redeployflag. This is useful to update an image rebuild. This feature requires a confirmation and can be accepted automatically and skipped with the-yflag.Theremovesub-commandThis sub-command allows you to remove a stack from Portainer by setting itsidornameand theendpointas well.$portainer-deployerremove--help
usage:portainer-deployerremove[-h][--idID|--nameNAME][--endpointENDPOINT][-y]RemoveastackfromPortainer.

optionalarguments:-h,--helpShowhelpmessageandexit.--idIDIdofthestackremove--nameNAME,-nNAMENameofthestacktoremove--endpointENDPOINT,-eENDPOINTEndpointIdfromthestacktoremove.-yAcceptremovalactionanddonotaskforconfirmation.This sub-command also has a confirmation step, and can be accepted automatically and skipped with the-yflag.⛏️ Built UsingPython 🐍- Core Programming Languageargparse- Main Python library for parsing arguments✍️ Authors@jorgmassih👨‍💻- Idea & Initial work🎉 AcknowledgementsPortainerand its development teamMy College ProfessorRodrigo Orizondo (@yoyirod)🕊️🙏 for the inspirationThe DevOps community🤝 ContributingI'm open to contributions!
If you are interested in collaborating, you can reach out to me via the info onmy bio.