Portainer Documentation: Release 1.22.1

Portainer Documentation
Release 1.22.1
Portainer.io
Oct 30, 2019

Contents
1 Deployment 3
1.1 Quick start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 Inside a Swarm cluster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3 Persist Portainer data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.4 Advanced deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2 Configuration 9
2.1 Admin password . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.2 Hiding specific containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.3 Use your own logo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.4 Use your own templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
2.5 Use an external endpoint source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
2.6 Available flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3 API 13
3.1 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
4 Agent 15
4.1 Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.2 Deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.3 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
4.4 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5 External endpoints 21
5.1 Endpoint definition format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.2 Endpoint synchronization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
6 Templates 25
6.1 Container template definition format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
6.2 Stack template definition format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
6.3 Build and host your own templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
7 Troubleshooting 37
7.1 Ensuring Docker is configured correctly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
7.2 Ensuring Docker Swarm is configured correctly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
8 Contribute 39
i
8.1 Build Portainer locally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
8.2 Contribution guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
8.3 Contributing to the documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
9 Limitations 41
9.1 Docker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
9.2 Swarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
9.3 Supported platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
10 FAQ 43
10.1 Contact us . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
10.2 How do I reset my Portainer password? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
10.3 Why are my stacks marked as Limited in Portainer? . . . . . . . . . . . . . . . . . . . . . . . . . . 43
10.4 Why is my version number not matching the latest version? . . . . . . . . . . . . . . . . . . . . . . 44
10.5 Can I activate my extension licenses without an internet connection? . . . . . . . . . . . . . . . . . 44
10.6 My licenses/extensions don’t activate, what do I do? . . . . . . . . . . . . . . . . . . . . . . . . . . 44
10.7 Users have access to an endpoint, but they cannot see anything. Why? . . . . . . . . . . . . . . . . . 44
10.8 Portainer lost it’s configuration, why? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
10.9 How do I make sure Portainer stays where my data is persisted? . . . . . . . . . . . . . . . . . . . . 45
10.10 Why doesn’t Portainer support compose version 3 on a standalone (non-swarm) host? . . . . . . . . 45
10.11 How do I get the logs from Portainer? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
10.12 Published ports in the services view redirect me to about:blank#blocked, what can I do? . . . . . . . 47
10.13 External endpoints are not working in the latest Portainer version, is this a bug? . . . . . . . . . . . . 49
10.14 Where can I find the source code of the Portainer agent? . . . . . . . . . . . . . . . . . . . . . . . . 49
10.15 My host is using SELinux, can I use Portainer ? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
10.16 How can I use Portainer behind a proxy? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
10.17 How can I expose the Docker API over TCP so that Portainer can communicate with my environment? 50
10.18 How can I set up Portainer on Windows Server 2016? . . . . . . . . . . . . . . . . . . . . . . . . . 50
10.19 How can I play with Portainer outside of the public demo? . . . . . . . . . . . . . . . . . . . . . . . 50
10.20 Exposed ports in the container view redirects me to 0.0.0.0, what can I do? . . . . . . . . . . . . . . 50
10.21 How do I troubleshoot Portainer? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
ii
Portainer Documentation, Release 1.22.1
Portainer is a simple management solution for Docker.

It consists of a web UI that allows you to easily manage your Docker containers, images, networks and volumes.
Contents:
Contents 1
2 Contents
CHAPTER 1
Deployment
Portainer is built to run on Docker and is really simple to deploy. Portainer deployment scenarios can be executed on
any platform unless specified.
1.1 Quick start
If you are running Linux, deploying Portainer is as simple as:
$ docker volume create portainer_data

$ docker run -d -p 9000:9000 -p 8000:8000 --name portainer --restart always -v /var/
˓→run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer
Voilà, you can now use Portainer by accessing the port 9000 on the server where Portainer is running.
1.2 Inside a Swarm cluster
Before deploying Portainer inside your Swarm cluster, you should ensure that Docker and your Swarm are configured
correctly. You can refer to the Troubleshooting section to ensure you have correctly configured your environment.
Following the above, you are ready to deploy Portainer inside a Swarm cluster using our recommended agent-enabled
deployment. Note: This setup will assume that you’re executing the following instructions on a Swarm manager node.
$ curl -L https://downloads.portainer.io/portainer-agent-stack.yml -o portainer-agent-

˓→stack.yml
$ docker stack deploy --compose-file=portainer-agent-stack.yml portainer
Have a look at the Agent section to find more details on how to connect an existing Portainer instance to a manually
deployed Portainer agent.
3
1.3 Persist Portainer data
By default, Portainer store its data inside the container in the /data folder on Linux (C:\\data on Windows).
You’ll need to persist Portainer data to keep your changes after restart/upgrade of the Portainer container. You can use
a bind mount on Linux to persist the data on the Docker host folder:

˓→run/docker.sock:/var/run/docker.sock -v /path/on/host/data:/data portainer/portainer
1.3.1 Windows
Docker for Windows 10 supports running both Linux and Windows containers and you need to use a different start
command depending on which container type you are using. Windows Server supports only native Windows contain-
ers.
Note: You must create the folder in which you want the data to be persisted before running the following command.
For example, if you want the data to persist in C:ProgramDataPortainer you need to create the Portainer directory
within C:ProgramData as it does not exist by default.
Example for Linux containers:

˓→run/docker.sock:/var/run/docker.sock -v C:\ProgramData\Portainer:/data portainer/
˓→portainer
Example for native Windows containers:
$ docker run -d -p 9000:9000 -p 8000:8000 --name portainer --restart always -v \\.

˓→\pipe\docker_engine:\\.\pipe\docker_engine -v C:\ProgramData\Portainer:C:\data
˓→portainer/portainer
1.3.2 Docker Swarm service
If you deployed Portainer as a Docker Swarm service:
$ docker service create \

--name portainer \
--publish 9000:9000 \
--publish 8000:8000 \
--replicas=1 \
--constraint 'node.role == manager' \
--mount type=bind,src=//path/on/host/data,dst=/data \
portainer/portainer
Note: The Swarm service example will persist Portainer data in /path/on/host/data for each host in the cluster.
If the container is re-scheduled on another node, existing Portainer data might not be available. Persisting data across
all nodes of a Swarm cluster is outside the scope of this documentation.
1.4 Advanced deployment
Advanced Portainer deployment scenarios.
4 Chapter 1. Deployment
1.4.1 Declaring the Docker environment to manage upon deployment
You can specify the initial environment you want Portainer to manage via the CLI, use the -H flag and the tcp://
protocol to connect to a remote Docker environment:
$ docker run -d -p 9000:9000 -p 8000:8000 --name portainer --restart always -v
˓→portainer_data:/data portainer/portainer -H tcp://<REMOTE_HOST>:<REMOTE_PORT>
Ensure you replace REMOTE_HOST and REMOTE_PORT with the address/port of the Docker server you want to
manage.
You can also bind mount the Docker socket to manage a local Docker environment (only possible on environments
where the Unix socket is available):
˓→run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer -H
˓→unix:///var/run/docker.sock
If your Docker environment is protected using TLS, you’ll need to ensure that you have access to CA, the certificate
and the public key used to access your Docker engine.
You can upload the required files via the Portainer UI or use the --tlsverify flag on the CLI.
Portainer will try to use the following paths to the files specified previously (on Linux, see the configuration section
for details about Windows):
• CA: /certs/ca.pem
• certificate: /certs/cert.pem
• public key: /certs/key.pem
You must ensure these files are present in the container using a bind mount:
$ docker run -d -p 9000:9000 -p 8000:8000 --name portainer --restart always -v /path/
˓→to/certs:/certs -v portainer_data:/data portainer/portainer -H tcp://<DOCKER_HOST>:
˓→<DOCKER_PORT> --tlsverify
You can also use the --tlscacert, --tlscert and --tlskey flags if you want to change the default path to
the CA, certificate and key file respectively:
$ docker run -d -p 9000:9000 -p 8000:8000 --name portainer -v /path/to/certs:/certs
˓→portainer/portainer -H tcp://<DOCKER_HOST>:<DOCKER_PORT> --tlsverify --tlscacert /
˓→certs/myCa.pem --tlscert /certs/myCert.pem --tlskey /certs/myKey.pem
$ docker run -d -p 9000:9000 -p 8000:8000 --name portainer --restart always -v /path/

˓→to/certs:/certs -v portainer_data:/data portainer/portainer -H tcp://<DOCKER_HOST>:
˓→<DOCKER_PORT> --tlsverify --tlscacert /certs/myCa.pem --tlscert /certs/myCert.pem --
˓→tlskey /certs/myKey.pem
1.4.2 Secure Portainer using SSL
By default, Portainer’s web interface and API is exposed over HTTP. This is not secured, it’s recommended to enable
SSL in a production environment.
To do so, you can use the following flags --ssl, --sslcert and --sslkey:
$ docker run -d -p 443:9000 -p 8000:8000 --name portainer --restart always -v ~/local-
˓→certs:/certs -v portainer_data:/data portainer/portainer --ssl --sslcert /certs/
˓→portainer.crt --sslkey /certs/portainer.key
1.4. Advanced deployment 5

You can use the following commands to generate the required files:
$ openssl genrsa -out portainer.key 2048

$ openssl ecparam -genkey -name secp384r1 -out portainer.key
$ openssl req -new -x509 -sha256 -key portainer.key -out portainer.crt -days 3650
Note that Certbot could be used as well to generate a certificate and a key. However, because Docker has issues with
symlinks, if you use Certbot, you will need to pass both the “live” and “archive” directories as volumes (shown below).
docker run -d -p 9000:9000 -p 8000:8000 \

-v /var/run/docker.sock:/var/run/docker.sock \
-v /root/portainer/data:/data \
-v /etc/letsencrypt/live/<redacted>:/certs/live/<redacted>:ro \
-v /etc/letsencrypt/archive/<redacted>:/certs/archive/<redacted>:ro \
--name portainer \
portainer/portainer:1.13.4 --ssl --sslcert /certs/live/<redacted>/cert.pem --
˓→sslkey /certs/live/<redacted>/privkey.pem
1.4.3 Deploy Portainer via docker-compose
You can use docker-compose to deploy Portainer.

Here is an example compose file:
version: '2'
services:
portainer:
image: portainer/portainer
command: -H unix:///var/run/docker.sock
restart: always
ports:
- 9000:9000
- 8000:8000
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- portainer_data:/data
volumes:
portainer_data:
Click here to download the Compose file.
1.4.4 Deploy Portainer without Docker
Portainer binaries are available on each release page: Portainer releases

Download and extract the binary to a location on disk:
$ cd /opt
$ wget https://github.com/portainer/portainer/releases/download/1.22.1/portainer-1.22.
˓→1-linux-amd64.tar.gz
$ tar xvpfz portainer-1.22.1-linux-amd64.tar.gz
Then just use the portainer binary as you would use CLI flags with Docker.
Note: Portainer will try to write its data into the /data folder by default. You must ensure this folder exists first (or
change the path it will use via the --data, see below).
$ mkdir /data
$ cd /opt/portainer
$ ./portainer --template-file "${PWD}/templates.json"
You can use the -p flag to serve Portainer on another port:
$ ./portainer -p :8080
You can change the folder used by Portainer to store its data with the --data flag:
$ ./portainer --data /opt/portainer-data
1.4. Advanced deployment 7

CHAPTER 2
Configuration
Portainer can be easily tuned using CLI flags.
2.1 Admin password
2.1.1 From the command line
Portainer allows you to specify a bcrypt encrypted password from the command line for the admin account. You need
to generate the bcrypt encrypted password first.
You can generate the encrypted password with the following command:
$ htpasswd -nb -B admin <password> | cut -d ":" -f 2
or if your system does not provide htpasswd you can use a docker container with the command:
$ docker run --rm httpd:2.4-alpine htpasswd -nbB admin <password> | cut -d ":" -f 2
To specify the admin password from the command line, start Portainer with the --admin-password flag:
$ docker run -d -p 9000:9000 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.
˓→sock portainer/portainer --admin-password='$2y$05$qFHAlNAH0A.6oCDe1/4W.ueCWC/
˓→iTfBMXIHBI97QYfMWlMCJ7N.a6'
2.1.2 Inside a file
You can also store the plaintext password inside a file and use the --admin-password-file flag:
# mypassword is plaintext here
$ echo -n mypassword > /tmp/portainer_password
˓→sock -v /tmp/portainer_password:/tmp/portainer_password portainer/portainer --admin-
(continues on next page)
˓→password-file /tmp/portainer_password
9
(continued from previous page)
This works well with Swarm & Docker secrets too:

# mypassword is plaintext here
$ echo -n mypassword | docker secret create portainer-pass -
--name portainer \
--secret portainer-pass \
--publish 9000:9000 \
--publish 8000:8000 \
--replicas=1 \
--mount type=bind,src=/var/run/docker.sock,dst=/var/run/docker.sock \
portainer/portainer \
--admin-password-file '/run/secrets/portainer-pass' \
-H unix:///var/run/docker.sock
Note: This will automatically create an administrator account called admin with the specified password.
2.2 Hiding specific containers
Portainer allows you to hide containers with a specific label by using the -l flag.
For example, take a container started with the label owner=acme (note that this is an example label, you can define
your own labels):
$ docker run -d --label owner=acme nginx
To hide this container, simply add the -l owner=acme option on the CLI when starting Portainer:
˓→sock portainer/portainer -l owner=acme
Note that the -l flag can be repeated multiple times to specify multiple labels:
˓→sock portainer/portainer -l owner=acme -l service=secret
2.3 Use your own logo
You do not like our logo? Want to make Portainer more corporate? Don’t worry, you can easily switch for an external
logo (it must be exactly 155px by 55px) using the --logo flag:
˓→sock portainer/portainer --logo "https://www.docker.com/sites/all/themes/docker/
˓→assets/images/brand-full.svg"
2.4 Use your own templates
Portainer allows you to rapidly deploy containers using App Templates.
10 Chapter 2. Configuration
By default Portainer templates will be used but you can also define your own templates.
Note: at the moment, templates are only loaded once at first Portainer startup. If you already deployed a Portainer
instance and want to use your own templates after this, you’ll need to clear any existing templates (default templates)
via the HTTP API.
There are two ways to specify your own templates:
2.4.1 Bind-mount your own templates
Using the –template-file flag you can specify the path to your own template file on the file-system. By default, it points
to /templates.json on both Linux and Windows hosts.
For example, you can mount your own template file inside the container:

˓→sock -v /path/to/my/templates.json:/templates.json portainer/portainer
Or using the –template-file to specify a specific path to the templates file:

˓→sock -v /path/to/template/folder:/templates portainer/portainer --template-file /
˓→templates/templates.json
2.4.2 Host your template file
Using the –templates flag you can specify an URL where the template file can be accessed via HTTP.

˓→sock portainer/portainer --templates http://my-host.my-domain/templates.json
For more information about hosting your own template definitions see Templates
2.5 Use an external endpoint source
Portainer gives you the option to define all the endpoints available in the UI from a JSON file.
You just need to start Portainer with the --external-endpoints flag and specify the path to the JSON file in the
container.
Note: when using the external endpoint management, endpoint management will be disabled in the UI.
$ docker run -d -p 9000:9000 -p 8000:8000 -v /tmp/endpoints:/endpoints portainer/

˓→portainer --external-endpoints /endpoints/endpoints.json
For more information about the endpoint definition format see External endpoints
2.6 Available flags
The following CLI flags are available:

• --admin-password: Specify a bcrypt hashed password for the admin user
2.5. Use an external endpoint source 11

• --admin-password-file: Path to the file containing the password for the admin user
• --bind, -p: Address and port to serve Portainer (default: :9000)
• --data, -d: Directory where Portainer data will be stored (default: /data on Linux, C:\data on Windows)
• --external-endpoints: Enable external endpoint management by specifying the path to a JSON endpoint
source in a file
• --hide-label, -l: Hide containers with a specific label in the UI
• --host, -H: Docker daemon endpoint
• --logo: URL to a picture to be displayed as a logo in the UI, use Portainer logo if not specified
• --no-analytics: Disable analytics (default: false)
• --no-snapshot: Disable periodic endpoint snapshot (default: false)
• --snapshot-interval: Time interval between two endpoint snapshot jobs expressed as a string, e.g. 30s,
5m, 1h. . . as supported by the time.ParseDuration method (default: 5m)
• --ssl: Secure Portainer instance using SSL (default: false)
• --sslcert: Path to the SSL certificate used to secure the Portainer instance (default: /certs/
portainer.crt, C:\certs\portainer.crt on Windows)
• --sslkey: Path to the SSL key used to secure the Portainer instance (default: /certs/portainer.key,
C:\certs\portainer.key on Windows)
• --sync-interval: Time interval between two endpoint synchronization requests expressed as a string, e.g.
30s, 5m, 1h. . . as supported by the time.ParseDuration method (default: 60s)
• --templates, -t: URL to templates (apps) definitions
• --template-file: Path on disk to templates (apps) definitions (default: /templates.json)
• --tlscacert: Path to the CA (default: /certs/ca.pem on Linux, C:\certs\ca.pem on Windows)
• --tlscert: Path to the TLS certificate file (default: /certs/cert.pem, C:\certs\cert.pem on
Windows)
• --tlskey: Path to the TLS key (default: /certs/key.pem, C:\certs\key.pem on Windows)
• --tlsverify: TLS support (default: false)
• --tunnel-port: Specify an alternate tunnel port to use with the Edge agent. Use --tunnel-port 8001
with -p 8001:8001 to make the Edge agent communicate on port 8001
12 Chapter 2. Configuration
CHAPTER 3
API
Portainer exposes an HTTP API that you can use to automate everything you do via the Portainer UI.
3.1 Documentation
The API documentation is available on Swaggerhub and you can also find some examples here.
13
14 Chapter 3. API
CHAPTER 4
Agent
4.1 Purpose
The Portainer Agent is a workaround for a Docker API limitation when using the Docker API to manage a Docker
environment. The user interactions with specific resources (containers, networks, volumes and images) are limited to
those available on the node targeted by the Docker API request.
Docker Swarm mode introduces a concept which is the clustering of Docker nodes. It also adds services, tasks, configs
and secrets which are cluster-aware resources. Cluster-aware means that you can query for a list of services or inspect
a task inside any node on the cluster, as long as you’re executing the Docker API request on a manager node.
Containers, networks, volumes and images are node specific resources, not cluster-aware. When you, for example,
want to list all the volumes available on a node inside your cluster, you will need to send a query to that specific node.
The purpose of the agent aims to allow previously node specific resources to be cluster-aware. All while keeping the
Docker API request format. As aforementioned, this means that you only need to execute one Docker API request to
retrieve all these resources from every node inside the cluster. In all bringing a better Docker user experience when
managing Swarm clusters.
4.2 Deployment
Instructions on how to deploy the Agent and how to connect it to Portainer.
4.2.1 Deploy it as a stack
Have a look at the deployment documentation Inside a Swarm cluster to quickly deploy the agent and a Portainer
instance inside a Swarm cluster via docker stack deploy.
15
4.2.2 Manual deployment
Overall, the setup consists of the following steps:

• Step 1: Create a new overlay network in your Swarm cluster for the Agent.
• Step 2: Deploy the Agent as a global service in your cluster (connected to the overlay network).
• Step 3: Connect your Portainer instance to any of the agents by using the Agent’s IP:PORT as an endpoint.
Note: This setup assumes that you are executing the following instructions on a Swarm manager node.
Step 1, creating a new overlay network in your Swarm cluster:
$ docker network create --driver overlay --attachable portainer_agent_network
Step 2, deploying the Agent as a global service in your cluster:

--name portainer_agent \
--network portainer_agent_network \
--mode global \
--constraint 'node.platform.os == linux' \
--mount type=bind,src=//var/run/docker.sock,dst=/var/run/docker.sock \
--mount type=bind,src=//var/lib/docker/volumes,dst=/var/lib/docker/volumes \
portainer/agent
Step 3, deploying the Portainer instance as a service:

--name portainer \
--publish 9000:9000 \
--publish 8000:8000 \
--replicas=1 \
portainer/portainer -H "tcp://tasks.portainer_agent:9001" --tlsskipverify
Step 4, deploying the Agent for all Windows Server nodes

Because of Docker limitation you need to deploy the Agent to all Windows Server nodes by running following com-
mand on each of them.
$ docker run -d --name portainer_agent --restart always --network portainer_agent_

˓→network -e AGENT_CLUSTER_ADDR=tasks.portainer_agent --mount type=npipe,source=\\.
˓→\pipe\docker_engine,target=\\.\pipe\docker_engine portainer/agent:windows1803-amd64
Note: If you’re using Windows server 1803, you might need to open up DNS ports to
support the DNS resolution of tasks.portainer_agent. See: https://success.docker.com/article/
swarm-internal-dns-is-inaccessible-on-windows-server-1803
4.2.3 Connecting an existing Portainer instance to an agent
If you want to connect an existing Portainer instance to an agent, you can choose the Agent environment type when
creating a new endpoint.
Ensure when deploying the agent, that you expose the Agent’s port inside your Swarm cluster, and that the mode is set
to host (default port is 9001):
16 Chapter 4. Agent

--publish mode=host,target=9001,published=9001 \
--mode global \
portainer/agent
Note: Please be aware that this could potentially open up the Agent for use by anybody in case the Docker host is
reachable from the internet. Publishing the Agent port 9001 in host mode basically means opening up this port in the
Docker hosts firewall for all interfaces. Therefore it is highly recommended to use the AGENT_SECRET environment
variable to define a shared secret, see Shared secret. The Agent implements the Trust On First Use (TOFU) principle,
so only the first Portainer to connect will be able to use it, but you want to avoid an attacker beating you to it.
You can then use the address of any node in your cluster (with the agent port) inside the Agent URL field.
Alternatively, you can deploy the agent using the following stack:
version: '3.2'
services:
agent:
image: portainer/agent
volumes:
- /var/lib/docker/volumes:/var/lib/docker/volumes
ports:
- target: 9001
published: 9001
protocol: tcp
mode: host
networks:
- portainer_agent
deploy:
mode: global
placement:
constraints: [node.platform.os == linux]
networks:
portainer_agent:
driver: overlay
attachable: true
Note: In case you are running only a single Agent cluster in the same Swarm overlay network as your Portainer
instance, you can just omit publishing the Agent port 9001. Portainer and the Agents will be able to communicate
with each other inside the same overlay network and there is no need for the Agents to be accessible from the outside.
4.3 Configuration
You can use variant agent configurations to achieve different setups or enable specific features.
4.3. Configuration 17
4.3.1 Shared secret
By default, the agent will register the first Portainer instance that connects to it and prevent connections from any other
instance after that.
To bypass this security mechanism, Portainer and the agent can be configured at deployment time to use a shared
secret. This configuration allows multiple Portainer instances to connect to the same agent endpoint.
The AGENT_SECRET environment variable can be used to define the shared secret.
When deploying the agent as a service:

--publish mode=host,target=9001,published=9001 \
-e AGENT_SECRET=mysecrettoken \
--mode global \
portainer/agent
Via a stack file:
version: '3.2'
services:
agent:
environment:
AGENT_SECRET: mysecrettoken
volumes:
ports:
- target: 9001
published: 9001
protocol: tcp
mode: host
networks:
- portainer_agent
deploy:
mode: global
placement:
networks:
portainer_agent:
driver: overlay
attachable: true
The AGENT_SECRET must be specified when deploying Portainer as well:
$ docker run -d -p 9000:9000 -p 8000:8000 --name portainer --restart always -e AGENT_

˓→SECRET=mysecrettoken -v /var/run/docker.sock:/var/run/docker.sock -v portainer_
˓→data:/data portainer/portainer
18 Chapter 4. Agent
4.3.2 Enable host management features
The following features are disabled by default for security reasons:

• Ability to manage the filesystem of the host where the agent is running
• Ability to retrieve hardware information about the host where the agent is running (PCI devices/disks)
In order to enable these features, the agent must be configured properly by:
• Enabling the host management features via the CAP_HOST_MANAGEMENT environment variable
• Bind-mounting the root of the host in the agent container (must be bind-mounted in /host)
Example when deploying the agent via a stack file:
version: '3.2'
services:
agent:
environment:
CAP_HOST_MANAGEMENT: 1
volumes:
- /:/host
ports:
- target: 9001
published: 9001
protocol: tcp
mode: host
networks:
- portainer_agent
deploy:
mode: global
placement:
networks:
portainer_agent:
driver: overlay
attachable: true
4.3.3 Available options
You can change the configuration of the agent by using environment variables.
The following environment variables can be tuned:
• AGENT_PORT: Agent port (default: 9001)
• LOG_LEVEL: Agent log level (default: INFO)
• AGENT_CLUSTER_ADDR: Address used by each agent to form a cluster.
• AGENT_SECRET: Shared secret used to authorize Portainer instances to connect to the agent
• CAP_HOST_MANAGEMENT: Enable host management features by setting the value to 1
4.3. Configuration 19
4.4 Usage
4.4.1 API
If you want to use the Portainer API to query containers running on a specific node inside a Swarm cluster and when
using the Portainer agent setup, you can specify the X-PortainerAgent-Target header in the HTTP request to
target a specific node in the cluster. The value must be set to the name of a specific node that can be retrieved via the
NodeName property when querying cluster resources (containers, volumes. . . ).
20 Chapter 4. Agent
CHAPTER 5
External endpoints
External endpoint definitions are written in JSON.

It must consist of an array with every endpoint definition consisting of one element.
[
{
"Name": "my-first-endpoint",
"URL": "tcp://myendpoint.mydomain:2375"
},
{
"Name": "my-second-endpoint",
"URL": "tcp://mysecondendpoint.mydomain:2375",
"TLS": true,
"TLSSkipVerify": true,
"TLSCACert": "/tmp/ca.pem",
"TLSCert": "/tmp/cert.pem",
"TLSKey": "/tmp/key.pem"
}
]
5.1 Endpoint definition format
An endpoint element must be a valid JSON object.

Example:
{
"Name": "my-secure-endpoint",
"URL": "tcp://myendpoint.mydomain:2375",
"TLS": true,
"TLSCACert": "/tmp/ca.pem",
"TLSCert": "/tmp/cert.pem",
21

"TLSKey": "/tmp/key.pem"
}
It is composed of multiple fields, some mandatory and some optionals.
5.1.1 Name
Name of the endpoint. Used to check if an endpoint already exists in the database during a synchronization request. It
will also be displayed in the UI.
This field is mandatory.
5.1.2 URL
How to reach the endpoint.

Protocol must be specified, only tcp:// and unix:// are supported at the moment. Any definition not using one
of these 2 protocols will be skipped.
5.1.3 TLS
Specify this field to true if you need to use TLS to connect to the endpoint. Defaults to false. When applying the
true value to this field, Portainer will expect the TLSCACertPath, TLSCertPath and TLSKeyPath fields to be defined
too.
This field is optional.
5.1.4 TLSSkipVerify
Specify this field to true if you want to skip server verification. Defaults to false.
5.1.5 TLSCACert
Path to the CA used to connect to the endpoint.

5.1.6 TLSCert
Path to the certificate used to connect to the endpoint.

22 Chapter 5. External endpoints

5.1.7 TLSKey
Path to the key used to connect to the endpoint.

5.2 Endpoint synchronization
When using the --external-endpoints flag, Portainer will read the specified JSON file at startup and automat-
ically create the endpoints.
Portainer will then read the file based on the interval defined in --sync-interval (every 60s by default) and will
automatically do the following:
• For each endpoint in the database, it will automatically merge any configuration find in the file using the enpoint
name as the comparison key
• If an endpoint exists in the database but is not present in the file, it will be removed from the database
• If an endpoint exists in the file but not in the database it will be created in the database
When using external endpoint management, endpoint management will via the UI will be disabled to avoid any pos-
sible configuration overwrite (the endpoints view is still accessible but will only display the list of endpoints without
giving the possibility to create/update endpoints). A simple warning message will be displayed in the endpoints view.
5.2. Endpoint synchronization 23

24 Chapter 5. External endpoints

CHAPTER 6
Templates
Template definitions are written in JSON.

It must consist of an array with every template definition consisting of one element.
6.1 Container template definition format
A template element must be a valid JSON object.

Example of a container template:
{
"type": 1,
"title": "Nginx",
"description": "High performance web server",
"logo": "https://cloudinovasi.id/assets/img/logos/nginx.png",
"image": "nginx:latest",
"ports": [
"8080:80/tcp",
"443/tcp"
]
}
6.1.1 type
Template type, valid values are: 1 (container), 2 (Swarm stack) or 3 (Compose stack).
NOTE: Type 3 (Compose stack) is limited to using the version: “2” stack format, this is a limitation of
docker/libcompose.
25
6.1.2 title
Title of the template.

6.1.3 description
Description of the template.

6.1.4 image
The Docker image associated to the template. The image tag must be included.
6.1.5 administrator_only
Should the template be available to administrator users only.

Example:
{
"administrator_only": true
}
6.1.6 name
Default name to use for this template in the UI.

6.1.7 logo
URL of the template’s logo.

6.1.8 registry
The registry where the Docker image is stored. If not specified, Portainer will use the Dockerhub as the default registry.
26 Chapter 6. Templates
6.1.9 command
The command to run in the container. If not specified, the container will use the default command specified in its
Dockerfile.
Example:
{
"command": "/bin/bash -c \"echo hello\" && exit 777"
}
6.1.10 env
A JSON array describing the environment variables required by the template. Each element in the array must be a
valid JSON object.
An input will be generated in the templates view for each element in the array. Depending on the object properties,
different types of inputs can be generated (text input, select).
Element format:
{
"name": "the name of the environment variable, as supported in the container image
˓→ (mandatory)",
"label": "label for the input in the UI (mandatory unless set is present)",
"description": "a short description for this input, will be available as a tooltip
˓→in the UI (optional)",
"default": "default value associated to the variable (optional)",

"preset": "boolean. If set to true, the UI will not generate an input (optional)",
"select": "an array of possible values, will generate a select input (optional)"
}
Example:
{
"env": [
{
"name": "MYSQL_ROOT_PASSWORD",
"label": "Root password",
"description": "Password used by the root user."
},
{
"name": "ENV_VAR_WITH_DEFAULT_VALUE",
"default": "default_value",
"preset": true
},
{
"name": "ENV_VAR_WITH_SELECT_VALUE",
"label": "An environment variable",
"description": "A description for this env var",
"select": [
{
"text": "Yes, I agree",
"value": "Y",
6.1. Container template definition format 27


"default": true
},
{
"text": "No, I disagree",
"value": "N"
},
{
"text": "Maybe",
"value": "YN"
}
],
"description": "Some environment variable."
}
]
}
6.1.11 network
A string corresponding to the name of an existing Docker network.

Will auto-select the network (if it exists) in the templates view.
Example:
{
"network": "host"
}
6.1.12 volumes
A JSON array describing the associated volumes of the template. Each element in the array must be a valid JSON
object that has a required container property.
For each element in the array, a Docker volume will be created and associated when starting the container. If a bind
property is defined it will be used as the source of a bind mount. If a readonly property is is defined and true, the
volume will be mounted in read-only mode.
Example:
{
"volumes": [
{
"container": "/etc/nginx"
},
{
"container": "/usr/share/nginx/html",
"bind": "/var/www",
"readonly": true
}
]
}
6.1.13 ports
A JSON array describing the ports exposed by template. Each element in the array must be a valid JSON string
specifying the port number in the container and the protocol.
It can be optionally prefixed with the port that must be mapped on the host in the port: form.
If the host port is not specified, the Docker host will automatically assign one when starting the container.
Example:
{
"ports": ["8080:80/tcp", "443/tcp"]
}
6.1.14 labels
A JSON array describing the labels associated to the template. Each element in the array must be a valid JSON object
with two properties name and value.
Example:
{
"labels": [
{ "name": "com.example.vendor", "value": "Acme" },
{ "name": "com.example.license", "value": "GPL" },
{ "name": "com.example.version", "value": "1.0" }
]
}
6.1.15 privileged
Should the container be started in privileged mode. Boolean, will default to false if not specified.
{
"privileged": true
}
6.1.16 interactive
Should the container be started in foreground (equivalent of -i -t flags). Boolean, will default to false if not
specified.
{
"interactive": true
}
6.1. Container template definition format 29

6.1.17 restart_policy
Restart policy associated to the container. Value must be one of the following:
• no
• unless-stopped
• on-failure
• always
This field is optional. Will default to always if not specified.
{
"restart_policy": "unless-stopped"
}
6.1.18 hostname
Set the hostname of the container.

This field is optional. Will use Docker default if not specified.
{
"hostname": "mycontainername"
}
6.1.19 note
Usage / extra information about the template. This will be displayed inside the template creation form in the Portainer
UI.
Supports HTML.
{
"note": "You can use this field to specify extra information. It supports 
˓→ HTML."
}
6.1.20 platform
Supported platform. This field value must be set to linux or windows. This will display a small platform related icon
in the Portainer UI.
{
"platform": "linux"
}
6.1.21 categories
An array of categories that will be associated to the template. Portainer UI category filter will be populated based on
all available categories.
{
"categories": ["webserver", "open-source"]
}
6.2 Stack template definition format
A template element must be a valid JSON object.

Example of a stack template:
{
"type": 2,
"title": "CockroachDB",
"description": "CockroachDB cluster",
"note": "Deploys an insecure CockroachDB cluster, please refer to <a href=\"https://
˓→www.cockroachlabs.com/docs/stable/orchestrate-cockroachdb-with-docker-swarm.html\"
˓→target=\"_blank\">CockroachDB documentation</a> for production deployments.",
"categories": ["database"],
"platform": "linux",
"logo": "https://cloudinovasi.id/assets/img/logos/cockroachdb.png",
"repository": {
"url": "https://github.com/portainer/templates",
"stackfile": "stacks/cockroachdb/docker-stack.yml"
}
}
6.2.1 type
Template type, valid values are: 1 (container), 2 (Swarm stack) or 3 (Compose stack).
A Swarm stack will be deployed using the equivalent of docker stack deploy whereas a Compose stack will
be deployed using the equivalent of docker-compose.
NOTE: Type 3 (Compose stack) is limited to using the version: “2” stack format, this is a limitation of
docker/libcompose.
6.2.2 title
Title of the template.

6.2. Stack template definition format 31

6.2.3 description
Description of the template.

6.2.4 repository
A JSON object describing the public git repository from where the stack template will be loaded. It indicates the URL
of the git repository as well as the path to the Compose file inside the repository.
Element format:
{
"url": "URL of the public git repository (mandatory)",
"stackfile": "Path to the Compose file inside the repository (mandatory)",
}
Example:
{
"url": "https://github.com/portainer/templates",
"stackfile": "stacks/cockroachdb/docker-stack.yml"
}
6.2.5 administrator_only
Should the template be available to administrator users only.

Example:
{
"administrator_only": true
}
6.2.6 name
Default name to use for this template in the UI.

6.2.7 logo
URL of the template’s logo.

6.2.8 env
A JSON array describing the environment variables required by the template. Each element in the array must be a
valid JSON object.
An input will be generated in the templates view for each element in the array. Depending on the object properties,
different types of inputs can be generated (text input, select).
Element format:
{
"name": "the name of the environment variable, as supported in the container image
˓→ (mandatory)",
"label": "label for the input in the UI (mandatory unless set is present)",
"description": "a short description for this input, will be available as a tooltip
˓→in the UI (optional)",
"default": "default value associated to the variable (optional)",

"preset": "boolean. If set to true, the UI will not generate an input (optional)",
"select": "an array of possible values, will generate a select input (optional)"
}
Example:
{
"env": [
{
"name": "MYSQL_ROOT_PASSWORD",
"label": "Root password",
"description": "Password used by the root user."
},
{
"name": "ENV_VAR_WITH_DEFAULT_VALUE",
"default": "default_value",
"preset": true
},
{
"name": "ENV_VAR_WITH_SELECT_VALUE",
"label": "An environment variable",
"description": "A description for this env var",
"select": [
{
"text": "Yes, I agree",
"value": "Y",
"default": true
},
{
"text": "No, I disagree",
"value": "N"
},
{
"text": "Maybe",
"value": "YN"
}
],
"description": "Some environment variable."
}
6.2. Stack template definition format 33


]
}
6.2.9 note
Usage / extra information about the template. This will be displayed inside the template creation form in the Portainer
UI.
Supports HTML.
{
"note": "You can use this field to specify extra information. It supports 
˓→ HTML."
}
6.2.10 platform
Supported platform. This field value must be set to linux or windows. This will display a small platform related icon
in the Portainer UI.
{
"platform": "linux"
}
6.2.11 categories
An array of categories that will be associated to the template. Portainer UI category filter will be populated based on
all available categories.
{
"categories": ["webserver", "open-source"]
}
6.3 Build and host your own templates
The simplest way to use your own templates is to bind mount your own template file directly into the Portainer
container, see Configuration.
You can also build your own container that will use Nginx to serve the templates definitions.
Clone the Portainer templates repository, edit the templates file, build and run the container:
$ git clone https://github.com/portainer/templates.git portainer-templates

$ cd portainer-templates
# Edit the file templates.json
$ docker build -t portainer-templates .
$ docker run -d -p "8080:80" portainer-templates
Now you can access your templates definitions at http://docker-host:8080/templates.json.

You can also mount the templates.json file inside the container, so you can edit the file and see live changes:
$ docker run -d -p "8080:80" -v "${PWD}/templates.json:/usr/share/nginx/html/

˓→templates.json" portainer-templates
6.3. Build and host your own templates 35

CHAPTER 7
Troubleshooting
Portainer is built to run on Docker. If Docker is not configured correctly, then this can cause issues that appear to be
coming from Portainer.
7.1 Ensuring Docker is configured correctly
The first thing to look at whether Docker is actually functioning correctly on your system.
$ docker version
The above command should have returned information about Docker running on your system. Below is a snippet of
what this may look like.
$ Client: Docker Engine - Community
Version: 19.03.3
API version: 1.40
Go version: go1.12.10
Git commit: a872fc2f86
Built: Tue Oct 8 00:59:59 2019
OS/Arch: linux/amd64
Experimental: false
7.2 Ensuring Docker Swarm is configured correctly
All nodes will require the following ports to be open:

• 7946/tcp
• 7946/udp
• 4789/udp
For the manager node:
37
• 2377/tcp
Next, make sure you are using the --advertise-addr option.
• When creating the cluster via docker swarm init, use --advertise-addr with either the private IP
address or NIC name directly (--advertise-addr eth1 for example)
• When joining a cluster on worker nodes via docker swarm join, use --advertise-addr the same as
above with either private IP address or NIC name directly
38 Chapter 7. Troubleshooting
CHAPTER 8
Contribute
Use the following instructions and guidelines to contribute to the Portainer project.
8.1 Build Portainer locally
8.1.1 Requirements
Ensure you have Docker, Node.js >= 6, yarn and Golang (>= 1.11) installed on your system.
8.1.2 Build
Checkout the project, set up the project inside your $GOPATH and go inside the root directory:
$ git clone https://github.com/portainer/portainer.git

$ mkdir -p ${GOPATH}/src/github.com/portainer
$ ln -s ${PWD}/portainer ${GOPATH}/src/github.com/portainer/portainer
$ cd portainer
Install dependencies with yarn:
$ yarn
Build and run the project:
$ yarn start
Access Portainer at http://localhost:9000
Tip: The frontend application will be updated when you save your changes to any of the sources (app/**/*.js,
assets/css/app.css or index.html). Just refresh the browser.
39
8.2 Contribution guidelines
Please follow the contribution guidelines on the repository.
8.3 Contributing to the documentation
Checkout the project and go inside the root directory:
$ git clone https://github.com/portainer/portainer-docs.git

$ cd portainer-docs
Update the documentation and trigger a local build:
$ docker run --rm -v ${PWD}/docs:/src portainer/docbuilder:latest make html
This will create a local folder docs/build/html where you will find the generated static files for the documenta-
tion.
40 Chapter 8. Contribute
CHAPTER 9
Limitations
Information about supported platforms and Docker versions.
9.1 Docker
Portainer is compatible with the following versions of Docker:

• Docker > 1.9
Portainer has partial support for the following versions of Docker:
• Docker 1.9
Portainer is not compatible with the following versions of Docker:
• Docker < 1.9
9.2 Swarm
Portainer is compatible with the following versions of Docker Swarm standalone:

• Docker Swarm >= 1.2.3
Note: this is not related to Docker Swarm mode, see https://docs.docker.com/swarm/swarm_at_scale/deploy-app/
9.3 Supported platforms
Portainer can be deployed on the following platforms:

• Linux amd64
• Linux arm
41
• Linux arm64
• Linux ppc64le
• Linux s390x
• Windows amd64
• Darwin amd64
42 Chapter 9. Limitations
CHAPTER 10
FAQ
10.1 Contact us
If you are still experiencing issues after reading this FAQ, feel free to contact us via any one of the following channels:
• Email: [email protected]
• Slack
• Twitter
• GitHub
• The Portainer Website
10.2 How do I reset my Portainer password?
At this stage, you cannot reset your password using Portainer if you have forgotten it. You can however ask another
Portainer admin to reset the password for you.
There is an open feature request for this functionality which can be tracked on our GitHub repository here.
10.3 Why are my stacks marked as Limited in Portainer?
When you see a stack file shown as limited in the Portainer UI, it is because Portainer does not have the related stack
file in it’s database. This is either because the stack was deployed outside of Portainer, or because Portainer has lost
it’s database.
If you wish to manage the stack file within Portainer, you will need to deploy it within Portainer so that the file is kept
in the database & ensure that the database is persisted.
43
10.4 Why is my version number not matching the latest version?
If you have recently updated your version of Portainer, this is an indication that your browser is holding onto the
previous version number of Portainer in it’s cache. To properly clear your cache, you will need to go into the browser
settings and empty the cache.
Note: You can use Ctrl + shift + R on most browsers to load the specific page without cache, however you
will need to repeat this on each page of Portainer to load the changes.
10.5 Can I activate my extension licenses without an internet connec-

tion?
Currently, it is not possible to activate extensions offline as Portainer runs a license check against our license verifica-
tion server. There is a feature request open for this offline activation functionality which can be tracked on our GitHub
repository here.
10.6 My licenses/extensions don’t activate, what do I do?
• As stated above, Portainer needs internet access to activate extensions. One way to test is to run a busybox
container and see if it can reach the internet via ping or curl.
• If Portainer can reach the internet then this is not the problem. If you have access to the Portainer data filesystem
you can check whether the extension binaries have been downloaded. Navigate to the filesystem in use by
Portainer and check the bin directory to make sure the extension has been downloaded. If there is no extensions
present, then there is an issue with Portainer downloading the extension.
• If the extensions are present, then you may have a permissions issue and they may not be able to run. Check to
make sure that they are executable.
10.7 Users have access to an endpoint, but they cannot see anything.
Why?
• By default all resources inside an endpoint are assigned to administrator only for security reasons. To give
non-admin users access you can use the access control widget within each resource to assign users ownership,
or you can make the resource public to give all users access.
• Alternatively, when using the Role Based Access Control (RBAC) extension you can assign users and teams a
role at the endpoint level. You can read more about the RBAC extension and it’s features here.
Note: The RBAC extension requires Portainer version 1.21.0 or newer.
10.8 Portainer lost it’s configuration, why?
Portainer as a Container: If you have not created a persistent volume for your Portainer container, then Portainer
data will be stored inside the Docker container. If the container is then restarted, you will lose all of your data.
Portainer as a Service: If you have not created a persistent volume for your Portainer service, then Portainer data will
be stored inside the Docker container created by the service. If the service is updated, you may lose your Portainer
configuration.
44 Chapter 10. FAQ

See Deployment on how to create a persistent volume. If you have a persistent volume, then the issue may be that
Portainer is not constrained to the node where the data is persisted. See the below section for more info.
10.9 How do I make sure Portainer stays where my data is persisted?
Our recommended deployment stack file constrains Portainer to a manager node, when you have multiple managers
this will potentially become a problem. Each stack or service update action could move the Portainer container
between them, and you may see Portainer appear as a fresh install.
The solution is to constrain your Portainer container to the node where your Portainer data is being persisted.
• Step 1: Following deployment of our stack file you will need to find the hostname of the node where the Portainer
volume is being persisted. Within Portainer, navigate to the volumes view and note down the hostname of your
Portainer volume. In this example the hostname is owner.
Alternatively you can run docker node ls and note down the hostname of the node where your Portainer data is
persisted.
Fig. 1: Viewing hostname of Portainer volume
• Step 2: Navigate to the Service details view for your Portainer service & navigate to placement constraints.
• Step 3: Click the placement constraints button to add a new constraint and fill in node.hostname for the name
and the hostname you gathered previously for the value.
• Step 4. Click the Apply changes button to apply your constraint.
10.10 Why doesn’t Portainer support compose version 3 on a stan-

dalone (non-swarm) host?
Portainer uses the library Libcompose to deploy stacks on a standalone host, this library has been depreciated by
Docker and the repository for it sits unmaintained. You can view this repository here.
10.11 How do I get the logs from Portainer?
You can either get the logs for Portainer from Portainer’s own GUI or from the Docker CLI on the command line.
10.9. How do I make sure Portainer stays where my data is persisted? 45

Fig. 2: Navigating to placement constraints for your Portainer service
Fig. 3: Applying the additional constraint
46 Chapter 10. FAQ

Getting Portainer’s logs from within Portainer

• Step 1. Navigate to the Container view and click on the logs button for your Portainer container.
Fig. 4: Navigating to the Container logs view for the Portainer container
• Step 2. Click on the copy button to copy the logs of the Portainer container to your clipboard.
Getting Portainer’s logs from the Docker CLI
• Step 1. Navigate to the commandline of a Docker manager node/ non-swarm Docker host and enter docker
ps -a to list all of the Docker containers.
• Step 2. Note down the CONTAINER_ID attribute of your Portainer container.
• Step 3. Enter the following command and the logs of the Portainer container will output to the commandline:
docker container logs CONTAINER_ID
10.12 Published ports in the services view redirect me to

about:blank#blocked, what can I do?
If you deployed the recommended agent stack or manage the local endpoint, you will need to set a public IP on your
endpoint for published ports to work on services in Portainer.
How to set the public IP of an endpoint:
• Step 1: Go to endpoints view
• Step 2: Click on your endpoint to see it’s details
• Fill in the Public IP field for your endpoint like below:
For an agent endpoint, add the IP of one of the nodes from your cluster
For the local endpoint add the IP of the host
10.12. Published ports in the services view redirect me to about:blank#blocked, what can I do? 47
Fig. 5: Copying the logs of the Portainer container
Fig. 6: Setting public IP of Agent endpoint
48 Chapter 10. FAQ

Fig. 7: Setting public IP of local endpoint
Clicking on the published port in the Services view should now correctly redirect you to the published port of your
service in the browser.
10.13 External endpoints are not working in the latest Portainer ver-
sion, is this a bug?
We are aware that the --external-endpoint feature is not working in some of the latest versions of Portainer.
If you require use of external endpoints, we recommend rolling back to Portainer version 1.21.0 until a fix has been
released.
10.14 Where can I find the source code of the Portainer agent?
The Portainer agent is now open source! You can find it’s source code here.
10.15 My host is using SELinux, can I use Portainer ?
If you want to manage a local Docker environment with SELinux enabled, you’ll need to pass the --privileged
flag to the Docker run command when deploying Portainer:
$ docker run -d --privileged -p 9000:9000 -p 8000:8000 --name portainer --restart

˓→always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data
You can also have a look at this helper: https://github.com/dpw/selinux-dockersock.
10.13. External endpoints are not working in the latest Portainer version, is this a bug? 49
10.16 How can I use Portainer behind a proxy?
With Portainer behind a proxy, some features requiring access to the Internet (such as Apps Templates) might be
unavailable. When running Portainer as a container, you can set the HTTP_PROXY and HTTPS_PROXY env vars to
specify which proxy should be used:
$ docker run -d -p 9000:9000 -p 8000:8000 -e HTTP_PROXY=my.proxy.domain:7777

For examples on how to configure a reverse proxy to work with Portainer, you can refer to our example repo here.
Note: these are in no way production ready, and are intended solely for demonstration purposes.
10.17 How can I expose the Docker API over TCP so that Portainer
can communicate with my environment?
Portainer strongly recommend to deploy Portainer using our agent enabled deployment due to the risk involved with
exposing the Docker API. If for whatever reason it is not possible to configure Portainer with the Agent, you can
configure Portainer to communicate with the Docker API over the network (usually on TCP 2375, 2376 with TLS).
Refer to Daemon socket option in the Docker Reference and to Docker Engine on Windows.
10.18 How can I set up Portainer on Windows Server 2016?
This is a great blog post which gives instructions on how to set up Portainer on Windows Server 2016.
Note: this is applicable to Windows Server 2016 only.
10.19 How can I play with Portainer outside of the public demo?
You can deploy Portainer as a stack in Play-with-Docker.
10.20 Exposed ports in the container view redirects me to 0.0.0.0,

what can I do?
In order for Portainer to be able to redirect you to your Docker host IP address and not the 0.0.0.0 address, you will
have to change the configuration of your Docker daemon and add the --ip option. Note: that you will have to restart
your Docker daemon for the changes to be taken in effect.
Have a look at the Docker documentation for more details.
10.21 How do I troubleshoot Portainer?
• Depending on your issue, make sure you first check the Portainer documentation and our user guides to ensure
everything is configured correctly.
50 Chapter 10. FAQ

• The next thing is to check the logs of Portainer & the Portainer Agent. For instructions on how to do this, refer
to the Portainer logs section above.
• If you cannot see anything wrong with your configuration or anything in the container logs, then the next step is
to troubleshoot your environment.
Make sure that Docker is running with the command docker version.
10.21. How do I troubleshoot Portainer? 51

Portainer Documentation: Release 1.22.1

Uploaded by

Copyright:

Available Formats

Portainer Documentation: Release 1.22.1

Uploaded by

Document Information

Original Description:

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Portainer Documentation: Release 1.22.1

Uploaded by

Copyright:

Available Formats

Portainer Documentation

Oct 30, 2019

Portainer is a simple management solution for Docker.

1.1 Quick start

If you are running Linux, deploying Portainer is as simple as:

$ docker volume create portainer_data

1.2 Inside a Swarm cluster

$ curl -L https://downloads.portainer.io/portainer-agent-stack.yml -o portainer-agent-

$ docker stack deploy --compose-file=portainer-agent-stack.yml portainer

1.3 Persist Portainer data

$ docker run -d -p 9000:9000 -p 8000:8000 --name portainer --restart always -v /var/

$ docker run -d -p 9000:9000 -p 8000:8000 --name portainer --restart always -v /var/

Example for native Windows containers:

$ docker run -d -p 9000:9000 -p 8000:8000 --name portainer --restart always -v \\.

1.3.2 Docker Swarm service

If you deployed Portainer as a Docker Swarm service:

$ docker service create \

1.4 Advanced deployment

Advanced Portainer deployment scenarios.

1.4.1 Declaring the Docker environment to manage upon deployment

˓→certs/myCa.pem --tlscert /certs/myCert.pem --tlskey /certs/myKey.pem

$ docker run -d -p 9000:9000 -p 8000:8000 --name portainer --restart always -v /path/

˓→<DOCKER_PORT> --tlsverify --tlscacert /certs/myCa.pem --tlscert /certs/myCert.pem --

1.4.2 Secure Portainer using SSL

˓→portainer.crt --sslkey /certs/portainer.key

1.4. Advanced deployment 5

$ openssl genrsa -out portainer.key 2048

docker run -d -p 9000:9000 -p 8000:8000 \

1.4.3 Deploy Portainer via docker-compose

You can use docker-compose to deploy Portainer.

Click here to download the Compose file.

1.4.4 Deploy Portainer without Docker

Portainer binaries are available on each release page: Portainer releases

$ tar xvpfz portainer-1.22.1-linux-amd64.tar.gz

You can use the -p flag to serve Portainer on another port:

$ ./portainer --data /opt/portainer-data

1.4. Advanced deployment 7

Portainer can be easily tuned using CLI flags.

2.1 Admin password

2.1.1 From the command line

2.1.2 Inside a file

(continued from previous page)

This works well with Swarm & Docker secrets too:

2.2 Hiding specific containers

2.3 Use your own logo

2.4 Use your own templates

Portainer allows you to rapidly deploy containers using App Templates.

2.4.1 Bind-mount your own templates

$ docker run -d -p 9000:9000 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.

Or using the –template-file to specify a specific path to the templates file:

$ docker run -d -p 9000:9000 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.

2.4.2 Host your template file

$ docker run -d -p 9000:9000 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.

2.5 Use an external endpoint source

$ docker run -d -p 9000:9000 -p 8000:8000 -v /tmp/endpoints:/endpoints portainer/

2.6 Available flags

The following CLI flags are available:

2.5. Use an external endpoint source 11