portainer-sdk

Easy way to deploy and update your containers with a command or an API request through Portainer.

Portainer SDK

The goal of this project is to deal with a simple machine-to-machine way to manage docker containers through portainer, it mainly provides :

• a portainer API client module to integrate portainer and docker features
• a portainer command (CLI) to easily consume the portainer API from a shell

This is a draft project...

Supported features

• show portainer version
• show portainer info
• manage remote portainer host
• portainer authentication
• saved settings
• create / pull a docker image
• remove a docker image
• list docker images
• create a docker container
• get docker container details
• list docker containers
• remove a docker container
• start a docker container
• stop a docker container
• deploy a docker container
• env vars support
• add i18n resources
• other docker API features...
• other portainer API features...

Command Line Interface

Installation

$ npm i -g portainer-sdk

Usage

The best way to get started with portainer cli is to simply read the help.

$ portainer --help

Examples

Some simple examples of usual tasks :

• Pull a docker image

$ portainer image-create --from tutum/hello-world

• Create a docker container

$ portainer container-create tutum/hello-world \
  --name hello-world \
  --hostConfig '{ "RestartPolicy": { "Name": "unless-stopped" } }' \
  --labels '{ "traefik.enable": "true", "traefik.frontend.rule": "Host:hello.local.io", "traefik.webservice.frontend.entryPoints": "http" }'

• Start the container

$ portainer container-start hello-world

• Test the container

$ http hello.local.io

• Stop the container

$ portainer container-stop hello-world

• Delete the container

$ portainer container-remove hello-world

• Delete the image

$ portainer image-remove tutum/hello-world

• Redeploy a container

$ portainer container-deploy tutum/hello-world hello-world \                                                                                                     master 
  --hostConfig '{ "RestartPolicy": { "Name": "unless-stopped" } }' \
  --labels '{ "traefik.enable": "true", "traefik.frontend.rule": "Host:hello.local.io", "traefik.webservice.frontend.entryPoints": "http" }'

Tricks

More advanced examples :

• Get containers with id

$ portainer container-list | jq "[.[] | {id: .Id, name: .Names[0]}]" | prettyoutput

• Get images with id

$ portainer image-list | jq "[.[] | {id: .Id, image: .Image}]" | prettyoutput

• Redeploy a remote image from private registry

Example of a web application using a redis database :

$ portainer container-deploy my-image:0.0.1 my-container \                                                                                     master 
  --registry 'my.private-registry.io' \
  --hostConfig '{ "Links": ["redis-server:redis"], "RestartPolicy": { "Name": "unless-stopped" } }' \
  --env '["APP_ENV=staging", "REDIS_HOST=redis"]' \
  --labels '{ "traefik.enable": "true", "traefik.frontend.rule": "Host:my-container.mydomain.io", "traefik.webservice.frontend.entryPoints": "http" }'

Supported environment variables

Some environment variables are supported by the command to override settings, or to facilitate bigger process integration :

• PORTAINER_HOST : base URL of the portainer host to use
• PORTAINER_JWT : portainer JWT token (obtained in authentication result, and usually available for 8 hours)
• PORTAINER_USERNAME : username of the portainer account to use when an authentication is needed (to generate a new JWT)
• PORTAINER_PASSWORD : password of the portainer account to use when an authentication is needed (to generate a new JWT)
• PORTAINER_DOCKER_REGISTRY : docker registry server hostname
• ENCRYPTION_KEY : encryption key to use to encrypt / decrypt passwords saved in settings file
• LOG_LEVEL : log level
• LANG : preferred lang to use (aliases : LC_ALL, LC_MESSAGES, LANGUAGE)

SDK

portainer

auth

Authenticate a account portainer account and returns a JWT, usually available for 8 hours.

• params :

  • username : (string, optionnal) portainer account username
  • password?: (string, optionnal) portainer account password
  • host: (string, optionnal) portainer host

• async result :

  • jwt : (string) generated JWT token
  • statusCode : (number) HTTP status code
  • body: (any) response body

getHostOptions

Get portainer host options.

• params :

  • host: (string, optionnal) portainer host

• result :

  • saveSettings: (boolean) true if settings are saved
  • defaultHost : (string)
  • jwt: (string, optionnal) last generated JWT
  • hosts: PortainerHostsOptions;

setHostOptions

Set portainer host options.

• params :

  • key: string
  • value: any
  • host?: string

• no result

portainer.docker

container

TODO

• params :

  • id: string
  • host?: string

• result : Promise

containers

TODO

• params : host?: string

• result : Promise

createContainer

TODO

• params :

  • image : string
  • hostConfig? : any
  • labels? : any
  • name? : string
  • env? : any
  • data? : any
  • query? : any
  • headers? : any
  • host? : string
  • jwt? : string

• result : Promise

createImage

TODO

• params :

  • from : string
  • registry? : string
  • data? : any
  • query? : any
  • headers? : any
  • host? : string
  • jwt? : string

• result : Promise

deployContainer

TODO

• params :

  • image : string
  • name : string
  • hostConfig? : any
  • labels? : any
  • env? : any
  • data? : any
  • query? : any
  • headers? : any
  • host? : string
  • jwt? : string

• result : Promise

images

TODO

• params :

  • data? : any
  • query? : any
  • headers? : any
  • host? : string
  • jwt? : string

• result : Promise

info

TODO

• params :

  • data? : any
  • query? : any
  • headers? : any
  • host? : string
  • jwt? : string

• result : Promise

removeContainer

TODO

• params :

  • id : string
  • data? : any
  • query? : any
  • headers? : any
  • host? : string
  • jwt? : string

• result : Promise

removeImage

TODO

• params :

  • image : string
  • data? : any
  • query? : any
  • headers? : any
  • host? : string
  • jwt? : string

• result : Promise

startContainer

TODO

• params :

  • id : string
  • data? : any
  • query? : any
  • headers? : any
  • host? : string
  • jwt? : string

• result : Promise

stopContainer

TODO

• params :

  • id : string
  • data? : any
  • query? : any
  • headers? : any
  • host? : string
  • jwt? : string

• result : Promise

version

TODO

• params :

  • data? : any
  • query? : any
  • headers? : any
  • host? : string
  • jwt? : string

• result : Promise

Enjoy !