portainer/portainer-docs

Portainer documentation

Welcome

Welcome to Portainer's official documentation site.

About Portainer

Portainer Community Edition (CE) is our foundation. With over half a million regular users, CE is a powerful, open source toolset that allows you to easily build and manage containers in Docker, Docker Swarm, Kubernetes and Azure ACI.

Portainer Business Edition (BE) is our commercial offering. With features geared towards businesses and larger organizations such as Role-Based Access Control, registry management, and dedicated support, Portainer BE is a powerful toolset that allows you to easily build and manage containers in Docker, Docker Swarm, Kubernetes and Azure ACI.

{% hint style="info" %} Portainer Business Edition requires a license key to install and use. If you don't currently have a license key, you can request three nodes free of Portainer Business Edition or purchase a license. {% endhint %}

Portainer hides the complexity of managing containers behind an easy-to-use UI. By removing the need to use the CLI, write YAML or understand manifests, Portainer makes deploying apps and troubleshooting problems so easy that anyone can do it.

Our team is here to help you on your journey. Community and five/three nodes free users can get assistance through our community support channels, and paid Business customers through our business support channels.

Documentation

We're working hard to ensure that our documentation keeps up with our ever-growing Portainer community. If you have a question we encourage you to start with the documentation (right here!). If you can't find what you're looking for, please visit our Knowledge Base or one of our support channels.

For more detailed step-by-step guides to Portainer, we're building out the Portainer Academy with more courses regularly.

{% hint style="info" %} As an open source product we rely on users in our community to support one another by asking questions, engaging in discussions and sharing knowledge. Together with the documentation found on this site and our YouTube channel, we cover a lot of ground but there may be gaps. {% endhint %}

Getting support

Community Edition, Five/Three Node Free and Home & Student Users

Community Edition, five/three nodes free and Home & Student users can get support through the following channels:

• Ask our AI bot by clicking the Ask AI button in the bottom right of this documentation site. Our AI chatbot pulls from a number of sources and is a great place to start when looking for help.
• Ask questions either in our GitHub Discussions forum or the community Slack channel. Other platforms exist (Reddit, Discord, Stack Overflow) but we are less active in those spaces.
• Log bugs in GitHub Issues so they can be properly managed.
• Flag vulnerabilities by emailing [email protected] so we can deal with them immediately.
• Flag documentation issues via our GitHub documentation channel (or start contributing and make our documentation better!).

Business Edition Customers

If you are a Professional or Enterprise tier Portainer Business Edition customer, you can log tickets directly with our team via email or filling out the Request Support form. You can report a bug, ask a question, tell us about an issue with documentation, or request a feature. Tickets are checked and resolved by Portainer staff within the SLA.

portainer-docs's Issues

Update SSL documentation to include a stack file example

The current documentation for deploying Portainer with SSL gives a docker run command, there should also be a stack file example.

Windows deployment instructions unclear; example docker run command results in an error on Windows hosts

The Deployment page provides the following command to use a bind mount to persist Portainer's data on a Windows Docker host folder:

$ docker run -d -p 9000:9000 --name portainer --restart always -v /var/run/docker.sock:/var/run/docker.sock -v C:\ProgramData\Portainer:C:\data portainer/portainer

However, the option -v /var/run/docker.sock:/var/run/docker.sock does not work on Windows hosts as the volume's source is a path to a Linux socket.

C:\Users\degroosa> docker volume create portainer_data
portainer_data

C:\Users\degroosa> docker run -d -p 9000:9000 --name portainer --restart always -v /var/run/docker.sock:/var/run/docker.sock -v C:\ProgramData\Portainer:C:\data portainer/portainer
Unable to find image 'portainer/portainer:latest' locally
latest: Pulling from portainer/portainer
407ada6e90de: Pull complete
1b9ade35fece: Pull complete
6ebe19270dfc: Pull complete
11d6b9914c95: Pull complete
56bd384cf576: Pull complete
24f71abb899c: Pull complete
8664cad12452: Pull complete
Digest: sha256:2933caa6e578e94b5d91429ea7f47ae9741ee11b71d7cb740e76c5f234cc1d87
Status: Downloaded newer image for portainer/portainer:latest
docker: Error response from daemon: invalid volume specification: '/var/run/docker.sock:/var/run/docker.sock'.
See 'docker run --help'.

I realize that the typical setup on a Windows host is more complicated than what is described on this page (a more complete set of deployment instructions are linked to on the FAQ page), but the docs don't make this very clear, and the Windows command provided on the Deployment page will never run on Windows hosts, further adding to the confusion. In fact, providing just one command for Windows hosts and no other mention of deployment on Windows hosts is confusing as it may lead the reader to believe that this one command is the only difference between deploying Portainer on a Windows host vs. a Linux host.

Can we remove or fix the provided Windows command on the Deployment page? Also, perhaps it would be good to add a section specifically for Windows Docker host deployments to the Deployment page, rather than burying a more complete set of instructions in the FAQ page where users are less likely to check.

Document X-PortainerAgent-Target // using Docker API in a Swarm cluster

see portainer/portainer#2016

Correct way for accessing individual nodes via Docker API in a Swarm cluster.

Quoting @deviantony:

"If you send a request without specifying the target header, Portainer will aggregate the containers from all nodes and decorate each container with the NodeName property. Then you can retrieve it and add it as the value of the target header to execute an action on a container inside the cluster."

Include documentation for the official portainer docker-compose.yml

Documentation for using the docker-compose.yml is not updated.

Document the type field for an environment variable

The type field is not documented at http://portainer.readthedocs.io/en/stable/templates.html

 {
    "title": "WordPress",
    "description": "A free and open-source CMS",
    "logo": "https://cloudinovasi.id/assets/img/logos/wordpress.png",
    "image": "wordpress:latest",
    "env": [
      {
        "name": "WORDPRESS_DB_HOST",
        "label": "MySQL database host",
        "type": "container"
      },
      {
        "name": "WORDPRESS_DB_PASSWORD",
        "label": "Database password"
      }
    ],
    "ports": [
      "80/tcp"
    ]
  }

documentation for admin-password is wrong

In the docs, the example for using --admin-password is incorrect.

It reads:

$ docker run -d -p 9000:9000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer --admin-password '$2y$05$qFHAlNAH0A.6oCDe1/4W.ueCWC/iTfBMXIHBI97QYfMWlMCJ7N.a6'

But it should read:

$ docker run -d -p 9000:9000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer --admin-password='$2y$05$qFHAlNAH0A.6oCDe1/4W.ueCWC/iTfBMXIHBI97QYfMWlMCJ7N.a6'

This is per the contextual help:

      --admin-password=ADMIN-PASSWORD  
                                 Hashed
                                 admin
                                 password

What exactly is SwarmID returns by Portainer API?

From my understanding, the Endpoint https://{portainer_url}/api/stacks/{id} should return ID of a particular node which that stack deployed to.

{
  "Id": "myStack_jpofkc0i9uo9wtx1zesuk649w",
  "Name": "myStack",
  "Type": 1,
  "EndpointID": 1,
  "EntryPoint": "docker-compose.yml",
  "SwarmID": "jpofkc0i9uo9wtx1zesuk649w",
  "ProjectPath": "/data/compose/myStack_jpofkc0i9uo9wtx1zesuk649w",
  "Env": [
    {
      "name": "MYSQL_ROOT_PASSWORD",
      "value": "password"
    }
  ]
}

According to the SwarmID returned, I've searched for all the given ID of all my entire cluster, there are no any matches found.
Any misunderstanding ? or any alternative ways that possibly help my aquire that node url from the API?

Apache does not proxy websocket.

I'm using the settings below in order to reverse proxy portainer container that exposes port 9000:
...
<Location /portainer/>
ProxyPass http://localhost:9000/
ProxyPassReverse http://localhost:9000/
RequestHeader set Connection ""

<Location /portainer/api/websocket/>
RequestHeader set Upgrade $http_upgrade;
RequestHeader set Connection "upgrade"
ProxyPass ws://localhost:9000/api/websocket/

...

These settings are mostly working for me but unfortunately, I am unable to use the console functionality in Portainer. When trying to use the console, my apache log spits out the following error:
AH01144: No protocol handler was valid for the URL /portainer/api/websocket/exec. If you are using a DSO version of mod_proxy, make sure the proxy submodules are included in the configuration using LoadModule. Any ideas?

Thanks.

Add the user guide section

Add a user guide section to guide the user on Portainer usage.

Wrong link to yml file, or server is down

In Inside a Swarm cluster section (https://portainer.readthedocs.io/en/stable/deployment.html#inside-a-swarm-cluster), denoted link to yml file is not correct

https://downloads.portainer.io/portainer-agent-stack.yml - Unable to connect

View Deleted Docker Containers' logs in Portainer?

Hi,

Is it possible to view the logs of deleted containers in Portainer?

https://github.com/portainer/portainer-docs/blob/master/docs/v2.0/containers/logs.md

Thanks,

portainer on windows

Hi, the windows image is not going through, I issue the following command

docker run -d -p 9000:9000 portainer/portainer:windows

The container exists, I ran it with -it flag instead of -d, at the commad I get the following error

2016/12/26 11:47:16 Unix socket /var/run/docker.sock does not exist

In my daemon.json file, I have
"hosts": ["tcp://192.168.2.10:2375", "npipe://"

Am I missing something?
Thanks for your help

Limited Control vs Full Control

Stacks are marked as Portainer having Limited or Full control. For example:

This stack was created outside of Portainer. Control over this stack is limited.

However, I don't believe it is ever explained anywhere in the documentation what exactly the difference is, nor how is is limited.

What additional benefits do we get with "Full Control"?

Allow reverse proxy authentication

Basically add an authentication mechanism that will accept an HTTP header value such as X-Forwarded-User as the authenticated user.

Incorrect instructions to build Portainer locally

1.Not enough instruction to build the project locally on:
[https://portainer.readthedocs.io/en/latest/contribute.html#contribution-guidelines]
2.The instructions should be complete and descriptive so that any beginner can start off easily in order to contribute to project.
3.No grunt related inforamtion for building the project.
4.I followed the order of instruction provided without using any extra step or hacks of mine and was unable to build portainer locally which should not happen.

Fix statement that portainer will not work on windows

Your note reads that using the docker sock is only available on linux:
Note 1: The -v /var/run/docker.sock:/var/run/docker.sock option is available on Linux environments only.

But this is incorrect, if you specify //var/run/docker.sock:/var/run/docker.sock, portainer will work on windows just fine.
Note: the "//" syntax skips Path mapping and just uses the vm path, where the socket is located.

docs : Deploy Portainer behind Traefik Proxy

Docs: "https://documentation.portainer.io/v2.0/ad/traefik/rp-traefik/"

There are two methods, the standalone has included commands for SSL certs via letsencrypt
--certificatesresolvers.leresolver.acme.httpchallenge=true
--certificatesresolvers.leresolver.acme.email=your-email #Set your email address here,
--certificatesresolvers.leresolver.acme.storage=./acme.json
--certificatesresolvers.leresolver.acme.httpchallenge.entrypoint=web

Not so in the swarm scenario, I'm a little confused as to how would the swarm get SSL certs ?
I thought copying the same commands would do, but there's no such advice in docs anywhere, just "you need to create 2 elements: Networks and volumes. "
.. am i missing something,
or is it assumed that anyone that happens to be awake can pretty much deduce that much, copy/paste commands -
I spent three days confusing docker secrets +labels with the labels of traefik, that too wasn't made clear in the docs
copied and encoded the certs and keys into secrets, thinking that labels .... duh
I already have TLS certs for every node, but I can't seem to point traefik to them - this guide at best also demonstrates how to config traefik to letsencrypt +get new ones ...
The problem with renewal would be that each node has to port forward 80 and 443, manually it's doable but dynamically on all nodes, I don't see how the router would care about a config file, unless it's only the manager node making the requests - wildcard TLS certs,
I thought of copying letsencrypt config into the acme.json, but that too isn't straightforward

Missing SSL certificates generation section

Hello team,

I'd like to respectfully highlight that both docs/v2.0/deploy/ssl.md and docs/v2.0-be/deploy/ssl.md
are missing the part for SSL certificate generation in the section Securing Portainer using SSL with Docker.

There is still related information that can be repurposed in docs/archive/1.23.2/deployment.md, section Secure Portainer using SSL

I hope this helps.
Thank you for your effort.

Readme update

Update documentation to actually explain what Portainer is. What's portainer and what does it do?
What's it features?

Thanks

Alias Recommendation

Good evening! I just wanted to make a recommendation for the portainer docs website. Is there a way that you could also use docs.portainer.io and have it routed to the documenation.portainer.io? Reason I make this recommendation is it closely resembles other sites (docs.docker.com, docs.microsoft.com) and is easier to share, type, and spread the word. Just food for thought 🙂

Deployment issues: Windows 10 Build 1709

For reasons beyond my control, I'm stuck with Win 10 build 1709 (so earlier than some nice docker updates)

I'm having the same problem as in #50 but I'm using the current deploy document. In that issue, the OP was really using Docker ON Windows Server 2016. (and that was why it didn't work, as discussed in the original thread).

I'm using Docker FOR Windows (Docker Desktop), with Linux containers (someone posted to #50 that switching to linux containers fixed it for them -- I must be missing something.

I'm using this command (from the docs, I've tried it both from a cmd prompt and from Powershell, same error):
docker run -d -p 9000:9000 -p 8000:8000 --name portainer --restart always -v /var/run/docker.sock:/var/run/docker.sock -v C:\ProgramData\Portainer:/data portainer/portainer

my error;
docker: Error response from daemon: invalid volume specification: '/var/run/docker.sock:/var/run/docker.sock'.

I would imagine that I need to change:
-v /var/run/docker.sock:/var/run/docker.sock
to
-v <some sort of Windows URI>:/var/run/docker.sock

but, that's where I'm stuck -- no idea what to put in <some sort of Windows URI>

The description of the admin-password option is inconsistent in the configuration document

This document say: --admin-password: Admin password in the form admin:<hashed_password>

But in the example usage it is:

 --admin-password='$2y$05$qFHAlNAH0A.6oCDe1/4W.ueCWC/iTfBMXIHBI97QYfMWlMCJ7N.a6'

One format is admin:<hashed_password>, the other format is <hashed_password>, I don't understand which format is correct.

api doc not available

https://portainer.readthedocs.io/en/stable/API.html

[Swaggerhub] (https://app.swaggerhub.com/apis/deviantony/Portainer/1.21.0/) is not avaliable, please help fix it. Thanks.

Documentation doesn't seem to explain why port 8000 is needed to be published

There are a lot of examples about running the Portainer container where both ports 8000 and 9000 are published and about how one can access Portainer via port 9000 but there doesn't seem to be anything about why port 8000 is published. I think such information should be present somewhere.

No documentation on running portainer in a subdirectory.

I can't find any documentation on how to configure portainer to run in a subdirectory.

For example my.domain.dom/portainer

Thanks!

Add a develop section

Explain how to build portainer locally in this section.

accessing traefik with portainer install

Hello,

I just installed portainer with traefik following this tutorial:
https://documentation.portainer.io/v2.0/ad/traefik/rp-traefik/
Everything went fine. Great tutorial.
My problem is that i cannot find how to get acces to the traefik UI. I tried adding a port 8080 on the traefik port list.

Can you help me ?

Conflicting info re: stack templates

Current docs state:

Stack templates can only be deployed inside Swarm clusters via docker stack deploy. Portainer is not compatible with docker-compose at the moment.

Yet they do offer a template type that's compatible with docker-compose (v2) stacks:

type - Template type, valid values are: 1 (container), 2 (Swarm stack) or 3 (Compose stack).

Might also be worth mentioning that type=3 (Compose stack) templates use the same template params as type=2 (Swarm stack) templates.

FAQ entry for LDAP configuration points to wrong URL

The FAQ entry for configuring Portainer with LDAP points to a URL that does not mention LDAP in any way.

I assume the URL should be to one of these two articles (preferably both since the first has more details on configuring groups and the second has more details on the LDAP configuration itself):
https://www.linkedin.com/pulse/ldap-usersgroups-portainer-neil-cresswell/
https://www.linkedin.com/pulse/how-enable-ldapad-authentication-portainerio-neil-cresswell/

Document how to downgrade from Portainer BE to Portainer CE

Downgrading from Portainer BE to CE requires some extra steps that should be documented.

Add a section on the Portainer HTTP API

Portainer HTTP API should be documented in a separated section.

portainer-templates

Hi.
Need for more detailed explanation in the Doc. I'm able to create a new nginx container that serves a templates.json but how/where do I setup this in portainer so it queries my own template repository ? I cloned the official one (as suggested in the doc) and I just changed some template titles to see if something changes but it seems to keep querying the online repository. Did I miss something ? Thx.

Document service webhoook usage

I read the code, found out that people can update their containers' image tags through a service webhook, this is awesome.

The nginx proxy example should change.

Using nginx version: nginx/1.13.7, the current config will show error: 404 Page not found

Using this config will solve this issue.
The proxy for api is not necessary anymore.

	location ~ ^/portainer/(.*)$ {
		proxy_pass              http://portainer/$1;
		proxy_redirect          off;
		proxy_set_header        Host            $host;
		proxy_set_header        X-Real-IP       $remote_addr;
		proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
		client_max_body_size    10m;
		client_body_buffer_size 128k;
		proxy_connect_timeout   90;
		proxy_send_timeout      90;
		proxy_read_timeout      90;
		proxy_buffers           32 4k;
	}

Insufficient UI / docs for planned deprecated features

Feel free to close this issue and tell me to submit to the main portainer repo if you feel this isn't the right place to discuss this.

Currently, features that are set to be deprecated have no UI elements as the docs claim here.

I am not sure if hidden-labels has been implemented into container creation under the labels section, or if those labels are not the same as hidden-labels?

My main issue is I cannot find a settings page, to change the logo or add another template file / endpoint. The docs suggest this is possible, but it doesn't seem to be.

Clarify the params for the service webhooks

From here:
https://documentation.portainer.io/v2.0/webhooks/create/
https://docs.docker.com/docker-hub/webhooks/

Seems like its implied that the data from the dockerhub web hook is compatible with the service webhook?
Is it possible to push other data than the tag for example?

Fix requirements for Docker

https://documentation.portainer.io/v2.0/deploy/requirements/

This doesn't look correct.

"The required Docker version to have full support is 1.9.1 or the newest. Docker 1.9 is partially supported. Older versions than indicated here, are not supported."

SSL paragraph in deployment section

portainer/portainer#679

PortainerCE and traefik reverse proxy

Hi, frontend and edge in traefik labels are deprecated in traefik:latest version

https://documentation.portainer.io/v2.0/ad/traefik/rp-traefik/ - Here use frontend and edge

https://doc.traefik.io/traefik/migration/v1-to-v2/#frontends-and-backends-are-dead-long-live-routers-middlewares-and-services - Proof

Add a limitations section

Add the limitations sections explaining Portainer support for Docker / Swarm versions.

Custom Templates -> How to use git repository

I refer to the official document: https://documentation.portainer.io/v2.0/stacks/create/

Gihub:

Error: “Get https://[email protected]:***@github.com/MrVBian/test//info/refs?service=git-upload-pack: EOF”

Password I use Personal access tokens

How do I use Docker Compose to create a Kubernetes env with Portainer

I have a docker-compose file but I need to create a K8s env with portainer, are there documentations and advice that I can use to go about this?

FAQ is out of date

The FAQ is out of date and could use an update as some of the links don't work or the examples are no longer correct

Is there docker origin api encapsulated by portainer agent ?

I want to update my service or container through portianer api, but can't find some useful api doc at https://app.swaggerhub.com/apis/deviantony/Portainer/1.21.0. Is it possible to call docker origin api（https://docs.docker.com/engine/api/v1.24/）through portainer ?
Please helps. Thanks.

persistent data hint

Hi, I never worked with docker before so you may find me very confused, please be patient.

I'm running docker for testing/dev purposes on my Arch Linux laptop and I'm following the Portainer docs, so I did this:

$ docker volume create portainer_data
$ docker run -d -p 9000:9000 --name portainer --restart always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer

Next, in the Persist Portainer data section I'm confused with "You’ll need to persist Portainer data to keep your changes after restart/upgrade of the Portainer container". But I don't want do a bind mount, I've created the volume which is located in /var/lib/docker/volumes/portainer_data. What do you mean by restart of the Portainer container? That means that docker will delete/recreate the volume every time when the service will be started/restarted (i.e. laptop reboot)? This makes on sense to me. Thanks for clarifying

Expanding on Docker for/on Windows difference

There are some fundamental differences between Docker on Windows vs Docker for Windows but I don't feel the documentation spells these out very well, for example, the on vs for distinction is still quite vague.

I would like to suggest some documentation changes to help with this:

1. Use the term Windows Containers (or something else that is far more distinguishable) to refer to the native docker engine on Windows and use Docker for Windows when referring to the Linux Containers in VM on Windows.

2. Add some links so people can get more information on the two different types of platforms for Docker.

3. Add a new page of documentation which goes into more depth about the differences between the two

4. Add information on how to determine which one a user has e.g. `do docker version. Look for the OS/Arch of the Server

5. Reference the Docker On Windows page in the quick start guide so that this will keep the quick start small, but still provide places to go to learn more.

Security Issue with mode=host for published ports

If I am not mistaken your documentation includes a huge security issue in regards to possibly opening up the agent port to the public internet:

--publish mode=host,target=9001,published=9001

    ports:
      - target: 9001
        published: 9001
        protocol: tcp
        mode: host

This is mentioned on the agent documentation page multiple times. Publishing a host port on each node does not mean that the port is only reachable via localhost on that node. I think there is a huge misunderstanding going on here. It just means that the port is published via iptables on that host and not via Swarm ingress loadbalancing. You are basically telling everyone to publish the agent port to possibly the whole internet if the node has a public IP.

Is this intended? Are other countermeasures taken inside the agent to block public traffic?

portainer/portainer:latest pulling 1.24.1

Looks like 2.0.1 is the latest version of portainer. Just pulled latest and getting 1.24.1.

is this expected?

Thanks

Current version

Hi Deviantoy, what is the last version of portainer?
I have 1.11 up and running since almost 1 year and I have a container which I use regularly.

In case there is a new version, would my current container based on image 1.11 be still valid or will it break?
Thanks

It isn't mentioned that app templates with type 3 are limited to version '2' syntax

Mention in the app template documentation that app templates using Type 3 (Compose stack) are limited to using the version 2 syntax