Skip to content

Instantly share code, notes, and snippets.

Last active March 17, 2022 00:04
  • Star 2 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
Star You must be signed in to star a gist
What would you like to do?
Portainer create image from HTTP API

This document aims to help you use the Portainer HTTP API to build a Docker image on a specific environment.


  • A Portainer instance
  • A Portainer user account
  • The environment where you want to build the image created as an endpoint inside the Portainer instance


Follow these instructions to build a Docker image inside a specific Docker environment using the Portainer HTTP API.

NOTE: I'm using httpie to execute HTTP queries from the CLI.


First, you need to authenticate against the HTTP API, see the example in here for more details:

Retrieve the JWT token, you'll need it to execute authenticated HTTP queries against the Portainer API.

Retrieve the endpoint (Docker environment) ID

You'll need the endpoint ID of the Docker environment where you want to build the Docker image. To do so, list all the available endpoints in your Portainer instance and retrieve the ID of your environment.

NOTE: Replace <JWT_TOKEN> with the value of the JWT token you retrieved after authentication.

http GET :9000/api/endpoints \
"Authorization: Bearer <JWT_TOKEN>"

The response will look like this:

        "AuthorizedTeams": [], 
        "AuthorizedUsers": [], 
        "Extensions": [], 
        "Id": 1, 
        "Name": "local", 
        "PublicURL": "", 
        "TLSConfig": {
            "TLS": false, 
            "TLSSkipVerify": false
        "URL": "unix:///var/run/docker.sock"

Retrieve the Id of the endpoint where you want to build the Docker image.

Build the Docker image

Now, let's use the Portainer API to build an image.

From a Git repository

We'll want to build an image from a Git repository, we'll use this one for example:

The image is going to be called portainer-example/git-repository-build:latest, based on this Git repository and using the Dockerfile available at sub/Dockerfile in the repository.

NOTE: We'll actually be using the Docker API through Portainer to achieve this (see the ImageBuild operation

$ http POST :9000/api/endpoints/<ENDPOINT_ID>/docker/build \
t=='portainer-example/git-repository-build:latest' \
remote=='' \
dockerfile=='sub/Dockerfile' \
"Authorization: Bearer <JWT_TOKEN>"

Replace <ENDPOINT_ID> with the Id of the endpoint that we retrieved above. E.g. .../api/endpoints/1/docker....

The response should be something like:

{"stream":"Step 1/3 : FROM nginx:stable-alpine"}
{"stream":" ---\u003e 24ed1c575f81\n"}
{"stream":"Step 2/3 : COPY sub/index.html /usr/share/nginx/html/index.html"}
{"stream":" ---\u003e a32796e0fda3\n"}
{"stream":"Step 3/3 : EXPOSE 80"}
{"stream":" ---\u003e Running in ffea75237eee\n"}
{"stream":"Removing intermediate container ffea75237eee\n"}
{"stream":" ---\u003e c17607e75e11\n"}
{"stream":"Successfully built c17607e75e11\n"}
{"stream":"Successfully tagged portainer-example/git-repository-build:latest\n"}

That's it, the image is now built inside your Docker environment.

Copy link

dcrocco commented Sep 28, 2020

How do you specify a branch from the repository?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment