# Table of Contents - [CLI configuration options | Portainer Documentation](#cli-configuration-options-portainer-documentation) - [Welcome | Portainer Documentation](#welcome-portainer-documentation) - [What's new in version 2.33 | Portainer Documentation](#what-s-new-in-version-2-33-portainer-documentation) - [Install Portainer BE | Portainer Documentation](#install-portainer-be-portainer-documentation) - [Introduction | Portainer Documentation](#introduction-portainer-documentation) - [Lifecycle policy | Portainer Documentation](#lifecycle-policy-portainer-documentation) - [Portainer architecture | Portainer Documentation](#portainer-architecture-portainer-documentation) - [Install Portainer BE with Docker on WSL / Docker Desktop | Portainer Documentation](#install-portainer-be-with-docker-on-wsl-docker-desktop-portainer-documentation) - [Docker Swarm | Portainer Documentation](#docker-swarm-portainer-documentation) - [Set up a new Portainer BE Server installation | Portainer Documentation](#set-up-a-new-portainer-be-server-installation-portainer-documentation) - [Install Portainer BE with Docker Swarm on Linux | Portainer Documentation](#install-portainer-be-with-docker-swarm-on-linux-portainer-documentation) - [Docker Standalone | Portainer Documentation](#docker-standalone-portainer-documentation) - [Install Portainer BE with Docker on Windows Container Service | Portainer Documentation](#install-portainer-be-with-docker-on-windows-container-service-portainer-documentation) - [Install Portainer CE | Portainer Documentation](#install-portainer-ce-portainer-documentation) - [Install Portainer BE with Docker on Linux | Portainer Documentation](#install-portainer-be-with-docker-on-linux-portainer-documentation) - [Podman | Portainer Documentation](#podman-portainer-documentation) - [Set up a new Portainer CE Server installation | Portainer Documentation](#set-up-a-new-portainer-ce-server-installation-portainer-documentation) - [Initial setup | Portainer Documentation](#initial-setup-portainer-documentation) - [Kubernetes | Portainer Documentation](#kubernetes-portainer-documentation) - [Install Portainer BE with Docker Swarm on WSL / Docker Desktop | Portainer Documentation](#install-portainer-be-with-docker-swarm-on-wsl-docker-desktop-portainer-documentation) - [Docker Standalone | Portainer Documentation](#docker-standalone-portainer-documentation) - [Install Portainer BE with Docker Swarm on Windows Container Service | Portainer Documentation](#install-portainer-be-with-docker-swarm-on-windows-container-service-portainer-documentation) - [Install Portainer BE on your Kubernetes environment | Portainer Documentation](#install-portainer-be-on-your-kubernetes-environment-portainer-documentation) - [Install Portainer CE with Docker on Linux | Portainer Documentation](#install-portainer-ce-with-docker-on-linux-portainer-documentation) - [Add a Nomad environment | 2.27 LTS | Portainer Documentation](#add-a-nomad-environment-2-27-lts-portainer-documentation) - [Add an ACI environment | 2.27 LTS | Portainer Documentation](#add-an-aci-environment-2-27-lts-portainer-documentation) - [Provision KaaS Cluster | 2.27 LTS | Portainer Documentation](#provision-kaas-cluster-2-27-lts-portainer-documentation) - [Civo | 2.27 LTS | Portainer Documentation](#civo-2-27-lts-portainer-documentation) - [Google Cloud | 2.27 LTS | Portainer Documentation](#google-cloud-2-27-lts-portainer-documentation) - [DigitalOcean | 2.27 LTS | Portainer Documentation](#digitalocean-2-27-lts-portainer-documentation) - [Akamai Connected Cloud | 2.27 LTS | Portainer Documentation](#akamai-connected-cloud-2-27-lts-portainer-documentation) - [AWS | 2.27 LTS | Portainer Documentation](#aws-2-27-lts-portainer-documentation) - [Azure | 2.27 LTS | Portainer Documentation](#azure-2-27-lts-portainer-documentation) - [Create a Kubernetes cluster | 2.27 LTS | Portainer Documentation](#create-a-kubernetes-cluster-2-27-lts-portainer-documentation) - [Talos Kubernetes | 2.27 LTS | Portainer Documentation](#talos-kubernetes-2-27-lts-portainer-documentation) - [MicroK8s | 2.27 LTS | Portainer Documentation](#microk8s-2-27-lts-portainer-documentation) - [Helm chart configuration options | 2.27 LTS | Portainer Documentation](#helm-chart-configuration-options-2-27-lts-portainer-documentation) - [How Relative Path Support works in Portainer | 2.27 LTS | Portainer Documentation](#how-relative-path-support-works-in-portainer-2-27-lts-portainer-documentation) - [Deprecated and removed features | 2.27 LTS | Portainer Documentation](#deprecated-and-removed-features-2-27-lts-portainer-documentation) - [API documentation | 2.27 LTS | Portainer Documentation](#api-documentation-2-27-lts-portainer-documentation) - [Deploying Portainer behind nginx reverse proxy | 2.27 LTS | Portainer Documentation](#deploying-portainer-behind-nginx-reverse-proxy-2-27-lts-portainer-documentation) - [Accessing the Portainer API | 2.27 LTS | Portainer Documentation](#accessing-the-portainer-api-2-27-lts-portainer-documentation) - [API usage examples | 2.27 LTS | Portainer Documentation](#api-usage-examples-2-27-lts-portainer-documentation) - [Build instructions | 2.27 LTS | Portainer Documentation](#build-instructions-2-27-lts-portainer-documentation) - [Contribute | 2.27 LTS | Portainer Documentation](#contribute-2-27-lts-portainer-documentation) - [Kubernetes roles and bindings | 2.27 LTS | Portainer Documentation](#kubernetes-roles-and-bindings-2-27-lts-portainer-documentation) - [Privacy Policy | 2.27 LTS | Portainer Documentation](#privacy-policy-2-27-lts-portainer-documentation) - [Set up a macOS build environment | 2.27 LTS | Portainer Documentation](#set-up-a-macos-build-environment-2-27-lts-portainer-documentation) - [Set up a Linux build environment | 2.27 LTS | Portainer Documentation](#set-up-a-linux-build-environment-2-27-lts-portainer-documentation) - [Docker roles and permissions | 2.27 LTS | Portainer Documentation](#docker-roles-and-permissions-2-27-lts-portainer-documentation) - [What's new in version 2.35 | 2.35 STS | Portainer Documentation](#what-s-new-in-version-2-35-2-35-sts-portainer-documentation) - [Welcome | 2.35 STS | Portainer Documentation](#welcome-2-35-sts-portainer-documentation) - [Introduction | 2.35 STS | Portainer Documentation](#introduction-2-35-sts-portainer-documentation) - [Set up a new Portainer BE Server installation | 2.35 STS | Portainer Documentation](#set-up-a-new-portainer-be-server-installation-2-35-sts-portainer-documentation) - [Install Portainer BE | 2.35 STS | Portainer Documentation](#install-portainer-be-2-35-sts-portainer-documentation) - [Docker Standalone | 2.35 STS | Portainer Documentation](#docker-standalone-2-35-sts-portainer-documentation) - [Install Portainer BE with Docker on Linux | 2.35 STS | Portainer Documentation](#install-portainer-be-with-docker-on-linux-2-35-sts-portainer-documentation) - [Install Portainer BE with Docker on WSL / Docker Desktop | 2.35 STS | Portainer Documentation](#install-portainer-be-with-docker-on-wsl-docker-desktop-2-35-sts-portainer-documentation) - [Install Portainer BE with Docker Swarm on Linux | 2.35 STS | Portainer Documentation](#install-portainer-be-with-docker-swarm-on-linux-2-35-sts-portainer-documentation) - [Install Portainer BE with Docker Swarm on WSL / Docker Desktop | 2.35 STS | Portainer Documentation](#install-portainer-be-with-docker-swarm-on-wsl-docker-desktop-2-35-sts-portainer-documentation) - [Docker Swarm | 2.35 STS | Portainer Documentation](#docker-swarm-2-35-sts-portainer-documentation) - [Install Portainer BE with Docker on Windows Container Service | 2.35 STS | Portainer Documentation](#install-portainer-be-with-docker-on-windows-container-service-2-35-sts-portainer-documentation) - [Podman | 2.35 STS | Portainer Documentation](#podman-2-35-sts-portainer-documentation) - [Install Portainer BE with Docker Swarm on Windows Container Service | 2.35 STS | Portainer Documentation](#install-portainer-be-with-docker-swarm-on-windows-container-service-2-35-sts-portainer-documentation) - [Kubernetes | 2.35 STS | Portainer Documentation](#kubernetes-2-35-sts-portainer-documentation) - [Install Portainer BE with Podman on Linux | 2.35 STS | Portainer Documentation](#install-portainer-be-with-podman-on-linux-2-35-sts-portainer-documentation) - [Install Portainer CE with Docker on Linux | 2.35 STS | Portainer Documentation](#install-portainer-ce-with-docker-on-linux-2-35-sts-portainer-documentation) - [Install Portainer CE | 2.35 STS | Portainer Documentation](#install-portainer-ce-2-35-sts-portainer-documentation) - [Initial setup | 2.35 STS | Portainer Documentation](#initial-setup-2-35-sts-portainer-documentation) - [Docker Standalone | 2.35 STS | Portainer Documentation](#docker-standalone-2-35-sts-portainer-documentation) - [Install Portainer BE with Kubernetes on WSL / Docker Desktop | 2.35 STS | Portainer Documentation](#install-portainer-be-with-kubernetes-on-wsl-docker-desktop-2-35-sts-portainer-documentation) - [Install Portainer CE with Docker on WSL / Docker Desktop | 2.35 STS | Portainer Documentation](#install-portainer-ce-with-docker-on-wsl-docker-desktop-2-35-sts-portainer-documentation) - [Set up a new Portainer CE Server installation | 2.35 STS | Portainer Documentation](#set-up-a-new-portainer-ce-server-installation-2-35-sts-portainer-documentation) - [Install Portainer BE on your Kubernetes environment | 2.35 STS | Portainer Documentation](#install-portainer-be-on-your-kubernetes-environment-2-35-sts-portainer-documentation) - [Install Portainer CE with Docker on Windows Container Service | 2.35 STS | Portainer Documentation](#install-portainer-ce-with-docker-on-windows-container-service-2-35-sts-portainer-documentation) - [Install Portainer CE with Docker Swarm on Linux | 2.35 STS | Portainer Documentation](#install-portainer-ce-with-docker-swarm-on-linux-2-35-sts-portainer-documentation) - [Docker Swarm | 2.35 STS | Portainer Documentation](#docker-swarm-2-35-sts-portainer-documentation) - [Install Portainer CE with Docker Swarm on Windows Container Service | 2.35 STS | Portainer Documentation](#install-portainer-ce-with-docker-swarm-on-windows-container-service-2-35-sts-portainer-documentation) - [Install Portainer CE with Docker Swarm on WSL / Docker Desktop | 2.35 STS | Portainer Documentation](#install-portainer-ce-with-docker-swarm-on-wsl-docker-desktop-2-35-sts-portainer-documentation) - [Podman | 2.35 STS | Portainer Documentation](#podman-2-35-sts-portainer-documentation) - [Install Portainer CE with Podman on Linux | 2.35 STS | Portainer Documentation](#install-portainer-ce-with-podman-on-linux-2-35-sts-portainer-documentation) - [Initial setup | 2.35 STS | Portainer Documentation](#initial-setup-2-35-sts-portainer-documentation) - [Add an environment to an existing installation | 2.35 STS | Portainer Documentation](#add-an-environment-to-an-existing-installation-2-35-sts-portainer-documentation) - [Updating Portainer | 2.35 STS | Portainer Documentation](#updating-portainer-2-35-sts-portainer-documentation) - [Kubernetes | 2.35 STS | Portainer Documentation](#kubernetes-2-35-sts-portainer-documentation) - [Updating on Nomad | 2.35 STS | Portainer Documentation](#updating-on-nomad-2-35-sts-portainer-documentation) - [Updating on Docker Standalone | 2.35 STS | Portainer Documentation](#updating-on-docker-standalone-2-35-sts-portainer-documentation) - [Updating the Edge Agent | 2.35 STS | Portainer Documentation](#updating-the-edge-agent-2-35-sts-portainer-documentation) - [Updating from Portainer 1.x | 2.35 STS | Portainer Documentation](#updating-from-portainer-1-x-2-35-sts-portainer-documentation) - [Updating on Podman | 2.35 STS | Portainer Documentation](#updating-on-podman-2-35-sts-portainer-documentation) - [Switching to Portainer Business Edition | 2.35 STS | Portainer Documentation](#switching-to-portainer-business-edition-2-35-sts-portainer-documentation) - [Install Portainer CE with Kubernetes on WSL / Docker Desktop | 2.35 STS | Portainer Documentation](#install-portainer-ce-with-kubernetes-on-wsl-docker-desktop-2-35-sts-portainer-documentation) - [Install Portainer CE on your Kubernetes environment | 2.35 STS | Portainer Documentation](#install-portainer-ce-on-your-kubernetes-environment-2-35-sts-portainer-documentation) - [Updating on Docker Swarm | 2.35 STS | Portainer Documentation](#updating-on-docker-swarm-2-35-sts-portainer-documentation) - [Updating on Kubernetes | 2.35 STS | Portainer Documentation](#updating-on-kubernetes-2-35-sts-portainer-documentation) - [Upgrade to Business Edition from within Portainer Community Edition | 2.35 STS | Portainer Documentation](#upgrade-to-business-edition-from-within-portainer-community-edition-2-35-sts-portainer-documentation) - [Docker Standalone | 2.35 STS | Portainer Documentation](#docker-standalone-2-35-sts-portainer-documentation) - [Docker Swarm | 2.35 STS | Portainer Documentation](#docker-swarm-2-35-sts-portainer-documentation) - [Kubernetes | 2.35 STS | Portainer Documentation](#kubernetes-2-35-sts-portainer-documentation) - [Podman | 2.35 STS | Portainer Documentation](#podman-2-35-sts-portainer-documentation) - [Upgrading Agent-only deployments | 2.35 STS | Portainer Documentation](#upgrading-agent-only-deployments-2-35-sts-portainer-documentation) - [Home | 2.35 STS | Portainer Documentation](#home-2-35-sts-portainer-documentation) - [Snapshot browsing | 2.35 STS | Portainer Documentation](#snapshot-browsing-2-35-sts-portainer-documentation) - [OpenAMT | 2.35 STS | Portainer Documentation](#openamt-2-35-sts-portainer-documentation) - [Docker/Swarm/Podman | 2.35 STS | Portainer Documentation](#docker-swarm-podman-2-35-sts-portainer-documentation) - [Dashboard | 2.35 STS | Portainer Documentation](#dashboard-2-35-sts-portainer-documentation) - [Application | 2.35 STS | Portainer Documentation](#application-2-35-sts-portainer-documentation) - [Templates | 2.35 STS | Portainer Documentation](#templates-2-35-sts-portainer-documentation) - [Custom templates | 2.35 STS | Portainer Documentation](#custom-templates-2-35-sts-portainer-documentation) - [Deploy a stack | 2.35 STS | Portainer Documentation](#deploy-a-stack-2-35-sts-portainer-documentation) - [Deploy a container | 2.35 STS | Portainer Documentation](#deploy-a-container-2-35-sts-portainer-documentation) - [Stacks | 2.35 STS | Portainer Documentation](#stacks-2-35-sts-portainer-documentation) - [Inspect or edit a stack | 2.35 STS | Portainer Documentation](#inspect-or-edit-a-stack-2-35-sts-portainer-documentation) - [Add a new stack | 2.35 STS | Portainer Documentation](#add-a-new-stack-2-35-sts-portainer-documentation) - [Create a template from a deployed stack | 2.35 STS | Portainer Documentation](#create-a-template-from-a-deployed-stack-2-35-sts-portainer-documentation) - [Migrate or duplicate a stack | 2.35 STS | Portainer Documentation](#migrate-or-duplicate-a-stack-2-35-sts-portainer-documentation) - [Webhooks | 2.35 STS | Portainer Documentation](#webhooks-2-35-sts-portainer-documentation) - [Remove a stack | 2.35 STS | Portainer Documentation](#remove-a-stack-2-35-sts-portainer-documentation) - [Services | 2.35 STS | Portainer Documentation](#services-2-35-sts-portainer-documentation) - [Add a new service | 2.35 STS | Portainer Documentation](#add-a-new-service-2-35-sts-portainer-documentation) - [Configure service options | 2.35 STS | Portainer Documentation](#configure-service-options-2-35-sts-portainer-documentation) - [Scale a service | 2.35 STS | Portainer Documentation](#scale-a-service-2-35-sts-portainer-documentation) - [Troubleshooting | 2.35 STS | Portainer Documentation](#troubleshooting-2-35-sts-portainer-documentation) - [Access and authentication | 2.35 STS | Portainer Documentation](#access-and-authentication-2-35-sts-portainer-documentation) - [How do I renew my 5 nodes free license? | 2.35 STS | Portainer Documentation](#how-do-i-renew-my-5-nodes-free-license-2-35-sts-portainer-documentation) - [How can I switch back to internal authentication? | 2.35 STS | Portainer Documentation](#how-can-i-switch-back-to-internal-authentication-2-35-sts-portainer-documentation) - [How do I reset my Portainer password? | 2.35 STS | Portainer Documentation](#how-do-i-reset-my-portainer-password-2-35-sts-portainer-documentation) - [Why has my Environment IP not updated after I changed it? | 2.35 STS | Portainer Documentation](#why-has-my-environment-ip-not-updated-after-i-changed-it-2-35-sts-portainer-documentation) - [Unable to Authenticate After Portainer Update | 2.35 STS | Portainer Documentation](#unable-to-authenticate-after-portainer-update-2-35-sts-portainer-documentation) - [Client sent an HTTP request to an HTTPS server | 2.35 STS | Portainer Documentation](#client-sent-an-http-request-to-an-https-server-2-35-sts-portainer-documentation) - [I enabled "Force HTTPS only" and now I'm locked out of Portainer. How do I get back in? | 2.35 STS | Portainer Documentation](#i-enabled-force-https-only-and-now-i-m-locked-out-of-portainer-how-do-i-get-back-in-2-35-sts-portainer-documentation) - [Agents and environment management | 2.35 STS | Portainer Documentation](#agents-and-environment-management-2-35-sts-portainer-documentation) - [Why is my Portainer Edge Agent using a large amount of memory? | 2.35 STS | Portainer Documentation](#why-is-my-portainer-edge-agent-using-a-large-amount-of-memory-2-35-sts-portainer-documentation) - [Troubleshooting Edge Agent Connection Issues | 2.35 STS | Portainer Documentation](#troubleshooting-edge-agent-connection-issues-2-35-sts-portainer-documentation) - [How can I move existing Edge Agent deployments to a new Portainer Server instance? | 2.35 STS | Portainer Documentation](#how-can-i-move-existing-edge-agent-deployments-to-a-new-portainer-server-instance-2-35-sts-portainer-documentation) - [Why can't my agents communicate with Portainer on Swarm? | 2.35 STS | Portainer Documentation](#why-can-t-my-agents-communicate-with-portainer-on-swarm-2-35-sts-portainer-documentation) - [Unable to Login via LDAP in Portainer | 2.35 STS | Portainer Documentation](#unable-to-login-via-ldap-in-portainer-2-35-sts-portainer-documentation) - [How do I change the way I connect to an environment without losing my existing stacks? | 2.35 STS | Portainer Documentation](#how-do-i-change-the-way-i-connect-to-an-environment-without-losing-my-existing-stacks-2-35-sts-portainer-documentation) - [Stacks, deployments and updates | 2.35 STS | Portainer Documentation](#stacks-deployments-and-updates-2-35-sts-portainer-documentation) - [How does the image update notification icon work? | 2.35 STS | Portainer Documentation](#how-does-the-image-update-notification-icon-work-2-35-sts-portainer-documentation) - [How do automatic updates for stacks/applications work? | 2.35 STS | Portainer Documentation](#how-do-automatic-updates-for-stacks-applications-work-2-35-sts-portainer-documentation) - [Can I build an image while deploying a stack/application from Git? | 2.35 STS | Portainer Documentation](#can-i-build-an-image-while-deploying-a-stack-application-from-git-2-35-sts-portainer-documentation) - [Why don't custom standalone app templates show when using Docker Swarm? | 2.35 STS | Portainer Documentation](#why-don-t-custom-standalone-app-templates-show-when-using-docker-swarm-2-35-sts-portainer-documentation) - [How do I configure Portainer's GitOps features to authenticate to a Bitbucket repository? | 2.35 STS | Portainer Documentation](#how-do-i-configure-portainer-s-gitops-features-to-authenticate-to-a-bitbucket-repository-2-35-sts-portainer-documentation) - [Why are stack deployment times slow? | 2.35 STS | Portainer Documentation](#why-are-stack-deployment-times-slow-2-35-sts-portainer-documentation) - [Environment Variable Management in Docker: .env vs. stack.env | 2.35 STS | Portainer Documentation](#environment-variable-management-in-docker-env-vs-stack-env-2-35-sts-portainer-documentation) - [How do I recover orphaned stacks from a previously deleted environment? | 2.35 STS | Portainer Documentation](#how-do-i-recover-orphaned-stacks-from-a-previously-deleted-environment-2-35-sts-portainer-documentation) - [UI and features | 2.35 STS | Portainer Documentation](#ui-and-features-2-35-sts-portainer-documentation) - [Why can't I use the console with my container? | 2.35 STS | Portainer Documentation](#why-can-t-i-use-the-console-with-my-container-2-35-sts-portainer-documentation) - [Exposed ports in the container view redirect me to 0.0.0.0. What can I do? | 2.35 STS | Portainer Documentation](#exposed-ports-in-the-container-view-redirect-me-to-0-0-0-0-what-can-i-do-2-35-sts-portainer-documentation) - [Why is a feature only available in Portainer Business Edition? | 2.35 STS | Portainer Documentation](#why-is-a-feature-only-available-in-portainer-business-edition-2-35-sts-portainer-documentation) - [Runtime and Resource sliders are not showing the set value on ARM | 2.35 STS | Portainer Documentation](#runtime-and-resource-sliders-are-not-showing-the-set-value-on-arm-2-35-sts-portainer-documentation) - [Why doesn’t the Portainer UI load inside an iframe? | 2.35 STS | Portainer Documentation](#why-doesn-t-the-portainer-ui-load-inside-an-iframe-2-35-sts-portainer-documentation) - [Logs, errors and debugging | 2.35 STS | Portainer Documentation](#logs-errors-and-debugging-2-35-sts-portainer-documentation) - [Can you view deleted container logs in Portainer? | 2.35 STS | Portainer Documentation](#can-you-view-deleted-container-logs-in-portainer-2-35-sts-portainer-documentation) - [How can I get the logs for Portainer itself? | 2.35 STS | Portainer Documentation](#how-can-i-get-the-logs-for-portainer-itself-2-35-sts-portainer-documentation) - [Unable to Access Pod Logs in My k0s Cluster | 2.35 STS | Portainer Documentation](#unable-to-access-pod-logs-in-my-k0s-cluster-2-35-sts-portainer-documentation) - [Why do I see a lot of TLS handshake errors in my Portainer and/or Agent logs? | 2.35 STS | Portainer Documentation](#why-do-i-see-a-lot-of-tls-handshake-errors-in-my-portainer-and-or-agent-logs-2-35-sts-portainer-documentation) - [Why can't my users see anything in the environment they have access to? | 2.35 STS | Portainer Documentation](#why-can-t-my-users-see-anything-in-the-environment-they-have-access-to-2-35-sts-portainer-documentation) - ["Failed to get license info" or "Unable to retrieve license info" message with valid license | 2.35 STS | Portainer Documentation](#-failed-to-get-license-info-or-unable-to-retrieve-license-info-message-with-valid-license-2-35-sts-portainer-documentation) - [What does a 500 error code mean? | 2.35 STS | Portainer Documentation](#what-does-a-500-error-code-mean-2-35-sts-portainer-documentation) - [Why is my console closing after a certain time? | 2.35 STS | Portainer Documentation](#why-is-my-console-closing-after-a-certain-time-2-35-sts-portainer-documentation) - [“Failed logging user activity” error in Portainer | 2.35 STS | Portainer Documentation](#-failed-logging-user-activity-error-in-portainer-2-35-sts-portainer-documentation) - [Certificates and security | 2.35 STS | Portainer Documentation](#certificates-and-security-2-35-sts-portainer-documentation) - [How to enable/disable image Up-to-date indicator | 2.35 STS | Portainer Documentation](#how-to-enable-disable-image-up-to-date-indicator-2-35-sts-portainer-documentation) - [How can I use my custom certificate authority (CA) with Portainer? | 2.35 STS | Portainer Documentation](#how-can-i-use-my-custom-certificate-authority-ca-with-portainer-2-35-sts-portainer-documentation) - [Registry and image management | 2.35 STS | Portainer Documentation](#registry-and-image-management-2-35-sts-portainer-documentation) - [Why is my node count higher than it should be? | 2.35 STS | Portainer Documentation](#why-is-my-node-count-higher-than-it-should-be-2-35-sts-portainer-documentation) - [Contributing | 2.35 STS | Portainer Documentation](#contributing-2-35-sts-portainer-documentation) - [I am unable to push an image to an AWS Elastic Container Registry | 2.35 STS | Portainer Documentation](#i-am-unable-to-push-an-image-to-an-aws-elastic-container-registry-2-35-sts-portainer-documentation) - [How do I report a bug? | 2.35 STS | Portainer Documentation](#how-do-i-report-a-bug-2-35-sts-portainer-documentation) - [How do I raise a feature request? | 2.35 STS | Portainer Documentation](#how-do-i-raise-a-feature-request-2-35-sts-portainer-documentation) - [How do you decide which bugs and features to work on first? | 2.35 STS | Portainer Documentation](#how-do-you-decide-which-bugs-and-features-to-work-on-first-2-35-sts-portainer-documentation) - [How do I log a Support Request? | 2.35 STS | Portainer Documentation](#how-do-i-log-a-support-request-2-35-sts-portainer-documentation) - [Email Protection | Cloudflare](#email-protection-cloudflare) - [Known issues | 2.35 STS | Portainer Documentation](#known-issues-2-35-sts-portainer-documentation) - [Edge stacks do not support authenticating to deploy applications from private registries. | 2.35 STS | Portainer Documentation](#edge-stacks-do-not-support-authenticating-to-deploy-applications-from-private-registries-2-35-sts-portainer-documentation) - [Known issues with VMware | 2.35 STS | Portainer Documentation](#known-issues-with-vmware-2-35-sts-portainer-documentation) - [Resource limits in a compose file are not applying | 2.35 STS | Portainer Documentation](#resource-limits-in-a-compose-file-are-not-applying-2-35-sts-portainer-documentation) - [Groups info issue with OAuth using Microsoft AD | 2.35 STS | Portainer Documentation](#groups-info-issue-with-oauth-using-microsoft-ad-2-35-sts-portainer-documentation) - [Hardware Acceleration GPU button is missing | 2.35 STS | Portainer Documentation](#hardware-acceleration-gpu-button-is-missing-2-35-sts-portainer-documentation) - [Nomad Jobs only displays Service Jobs | 2.35 STS | Portainer Documentation](#nomad-jobs-only-displays-service-jobs-2-35-sts-portainer-documentation) - [Unable to update environment variables when running on Synology NAS | 2.35 STS | Portainer Documentation](#unable-to-update-environment-variables-when-running-on-synology-nas-2-35-sts-portainer-documentation) - ["Image not found on registry" error when upgrading from CE to BE or self-updating on Synology NAS | 2.35 STS | Portainer Documentation](#-image-not-found-on-registry-error-when-upgrading-from-ce-to-be-or-self-updating-on-synology-nas-2-35-sts-portainer-documentation) - [Unable to remove the Group Configuration from Active Directory authentication configuration | 2.35 STS | Portainer Documentation](#unable-to-remove-the-group-configuration-from-active-directory-authentication-configuration-2-35-sts-portainer-documentation) - [MicroK8s Known Issues | 2.35 STS | Portainer Documentation](#microk8s-known-issues-2-35-sts-portainer-documentation) - [Where can I find the documentation for Portainer? | 2.35 STS | Portainer Documentation](#where-can-i-find-the-documentation-for-portainer-2-35-sts-portainer-documentation) - [Which versions of Portainer do you provide support for? | 2.35 STS | Portainer Documentation](#which-versions-of-portainer-do-you-provide-support-for-2-35-sts-portainer-documentation) - [Access control | 2.35 STS | Portainer Documentation](#access-control-2-35-sts-portainer-documentation) - [Getting support | 2.35 STS | Portainer Documentation](#getting-support-2-35-sts-portainer-documentation) - [How to get support for Community Edition and 5 Nodes Free Users | 2.35 STS | Portainer Documentation](#how-to-get-support-for-community-edition-and-5-nodes-free-users-2-35-sts-portainer-documentation) - [Security and compliance | 2.35 STS | Portainer Documentation](#security-and-compliance-2-35-sts-portainer-documentation) - [Reset the admin user's password | 2.35 STS | Portainer Documentation](#reset-the-admin-user-s-password-2-35-sts-portainer-documentation) - [App templates | 2.35 STS | Portainer Documentation](#app-templates-2-35-sts-portainer-documentation) - ["Unauthorized" error when pushing images to ACR with Service Principal account | 2.35 STS | Portainer Documentation](#-unauthorized-error-when-pushing-images-to-acr-with-service-principal-account-2-35-sts-portainer-documentation) - [Known compatibility issues with Docker Engine 29.0.0 | 2.35 STS | Portainer Documentation](#known-compatibility-issues-with-docker-engine-29-0-0-2-35-sts-portainer-documentation) - [How to get support for Business Edition Customers with a subscription | 2.35 STS | Portainer Documentation](#how-to-get-support-for-business-edition-customers-with-a-subscription-2-35-sts-portainer-documentation) - [The Portainer Edge Agent | 2.35 STS | Portainer Documentation](#the-portainer-edge-agent-2-35-sts-portainer-documentation) - [Build and host your own app templates | 2.35 STS | Portainer Documentation](#build-and-host-your-own-app-templates-2-35-sts-portainer-documentation) - ["Invalid certificate file" error when browsing empty Azure Container Registry | 2.35 STS | Portainer Documentation](#-invalid-certificate-file-error-when-browsing-empty-azure-container-registry-2-35-sts-portainer-documentation) - [Stream auth and activity logs to an external provider | 2.35 STS | Portainer Documentation](#stream-auth-and-activity-logs-to-an-external-provider-2-35-sts-portainer-documentation) - [Using Portainer with reverse proxies | 2.35 STS | Portainer Documentation](#using-portainer-with-reverse-proxies-2-35-sts-portainer-documentation) - [Using your own SSL certificate with Portainer | 2.35 STS | Portainer Documentation](#using-your-own-ssl-certificate-with-portainer-2-35-sts-portainer-documentation) - [Privacy Policy | 2.35 STS | Portainer Documentation](#privacy-policy-2-35-sts-portainer-documentation) - [Build instructions | 2.35 STS | Portainer Documentation](#build-instructions-2-35-sts-portainer-documentation) - [Deprecated and removed features | 2.35 STS | Portainer Documentation](#deprecated-and-removed-features-2-35-sts-portainer-documentation) - [Deploying Portainer behind Traefik Proxy | 2.35 STS | Portainer Documentation](#deploying-portainer-behind-traefik-proxy-2-35-sts-portainer-documentation) - [Using mTLS with Portainer | 2.35 STS | Portainer Documentation](#using-mtls-with-portainer-2-35-sts-portainer-documentation) - [Accessing the Portainer API | 2.35 STS | Portainer Documentation](#accessing-the-portainer-api-2-35-sts-portainer-documentation) - [Encrypting the Portainer database | 2.35 STS | Portainer Documentation](#encrypting-the-portainer-database-2-35-sts-portainer-documentation) - [API documentation | 2.35 STS | Portainer Documentation](#api-documentation-2-35-sts-portainer-documentation) - [How Relative Path Support works in Portainer | 2.35 STS | Portainer Documentation](#how-relative-path-support-works-in-portainer-2-35-sts-portainer-documentation) - [Set up a macOS build environment | 2.35 STS | Portainer Documentation](#set-up-a-macos-build-environment-2-35-sts-portainer-documentation) - [Contribute | 2.35 STS | Portainer Documentation](#contribute-2-35-sts-portainer-documentation) - [Deploying Portainer behind nginx reverse proxy | 2.35 STS | Portainer Documentation](#deploying-portainer-behind-nginx-reverse-proxy-2-35-sts-portainer-documentation) - [Deprecated and removed features | Portainer Documentation](#deprecated-and-removed-features-portainer-documentation) - [Helm chart configuration options | 2.35 STS | Portainer Documentation](#helm-chart-configuration-options-2-35-sts-portainer-documentation) - [The Portainer Edge Agent | Portainer Documentation](#the-portainer-edge-agent-portainer-documentation) - [Access control | Portainer Documentation](#access-control-portainer-documentation) - [Security and compliance | Portainer Documentation](#security-and-compliance-portainer-documentation) - [API documentation | Portainer Documentation](#api-documentation-portainer-documentation) - [App template JSON format | 2.35 STS | Portainer Documentation](#app-template-json-format-2-35-sts-portainer-documentation) - [Using your own SSL certificate with Portainer | Portainer Documentation](#using-your-own-ssl-certificate-with-portainer-portainer-documentation) - [API usage examples | 2.35 STS | Portainer Documentation](#api-usage-examples-2-35-sts-portainer-documentation) - [Build and host your own app templates | Portainer Documentation](#build-and-host-your-own-app-templates-portainer-documentation) - [How Relative Path Support works in Portainer | Portainer Documentation](#how-relative-path-support-works-in-portainer-portainer-documentation) - [Set up a Linux build environment | 2.35 STS | Portainer Documentation](#set-up-a-linux-build-environment-2-35-sts-portainer-documentation) - [CLI configuration options | 2.35 STS | Portainer Documentation](#cli-configuration-options-2-35-sts-portainer-documentation) - [Encrypting the Portainer database | Portainer Documentation](#encrypting-the-portainer-database-portainer-documentation) - [Using mTLS with Portainer | Portainer Documentation](#using-mtls-with-portainer-portainer-documentation) - [Privacy Policy | Portainer Documentation](#privacy-policy-portainer-documentation) - [Reset the admin user's password | Portainer Documentation](#reset-the-admin-user-s-password-portainer-documentation) - [App templates | Portainer Documentation](#app-templates-portainer-documentation) - [Build instructions | Portainer Documentation](#build-instructions-portainer-documentation) - [Contribute | Portainer Documentation](#contribute-portainer-documentation) - [Stream auth and activity logs to an external provider | Portainer Documentation](#stream-auth-and-activity-logs-to-an-external-provider-portainer-documentation) --- # CLI configuration options | Portainer Documentation [](https://docs.portainer.io/advanced/cli#configuration-flags-available-at-the-command-line) Configuration flags available at the command line --------------------------------------------------------------------------------------------------------------------------------------------------- Flag Description `--admin-password` Specifies a bcrypt hashed password for the admin user. This can only be used when first creating the admin user (such as during installation) and not to change the admin user's password after installation. `--admin-password-file` Specifies the path to the file containing the plain text password for the admin user. This can only be used when first creating the admin user (such as during installation) and not to change the admin user's password after installation. `--base-url` Specifies the path that Portainer is running under if you are running Portainer within a subpath behind a reverse proxy (for example use `--base-url /portainer` if you are running Portainer at `https://yourdomain/portainer`). Defaults to `/`. **Note:** when using this option you will still need to ensure your reverse proxy configuration will strip the specified subpath. `--bind` `-p` Specifies the address and port from which to serve Portainer (default: `:9000`). `--bind-https` Specifies the address and port from which to serve Portainer via HTTPS (default: `:9443`). `--data` `-d` Specifes the directory where Portainer data will be stored (default: `/data` on Linux, `C:\data` on Windows). `--edge-compute` Automatically enables Edge Compute features. `--hide-label` `-l` Hides containers with a specific label in the UI. `--http-disabled` Serve Portainer only on HTTPS. Overrides `--http-enabled`. Ensure your HTTPS configuration is fully working and any agents are configured for HTTPS before enabling this. `--http-enabled` Serve Portainer on HTTP. If used in combination with `--http-disabled`, this is ignored. `--host` `-H` Specifies the Docker daemon endpoint. `--license-key` Specifies the license key to use. Only applicable to Portainer Business Edition. `--log-level` Set the log level of the Portainer application, for example `--log-level DEBUG`. This is useful when troubleshooting. Debug logging can also be enabled through [Settings](https://docs.portainer.io/admin/settings) . `--log-mode` Set the formatting for the Portainer log output, for example `--log-mode NOCOLOR`. Options are: `PRETTY` (default), `NOCOLOR` (disables color codes), `JSON` (JSON-formatted logs). `--logo` Specifies the URL to the image to be displayed as a logo in the UI. If not specified, the Portainer logo is used instead. `--mtlscacert` Specifies the path to the certificate authority (CA) certificate used for mTLS communication. (BE only) `--mtlscert` Specifies the path to the certificate used for mTLS communication. (BE only) `--mtlskey` Specifies the path to the certificate key used for mTLS communication. (BE only) `--snapshot-interval` Specifies the time interval between two environment snapshot jobs expressed as a string. For example 30s, 5m, 1h… Supported by the `time.ParseDuration` method (default: 5m). `--sslcacert` Specifies the path to the certificate authority (CA) certificate used to validate the Edge Agent certificate. (BE only, **deprecated**, use [mTLS](https://docs.portainer.io/advanced/mtls) instead) `--sslcert` Specifies the path to the SSL certificate used to secure the Portainer instance (default: `/certs/portainer.crt` on Linux, `C:\certs\portainer.crt` on Windows). `--sslkey` Specifies the path to the SSL key used to secure the Portainer instance (default: `/certs/portainer.key` on Linux, `C:\certs\portainer.key` on Windows). `--syslog-*` The `--syslog-*` options are used to configure auth and activity log streaming to an external Syslog-compatible provider. See the [SIEM documentation](https://docs.portainer.io/advanced/siem) for more on this experimental feature. `--templates` `-t` Specifies the URL to the templates (apps) definitions. `--tlscacert` Specifies the path to the CA used for Docker daemon connections (default: `/certs/ca.pem` on Linux, `C:\certs\ca.pem` on Windows). `--tlscert` Specifies the path to the TLS certificate file used for Docker daemon connections (default: `/certs/cert.pem`, `C:\certs\cert.pem` on Windows). `--tlskey` Specifies the path to the TLS key used for Docker daemon connections (default: `/certs/key.pem`, `C:\certs\key.pem` on Windows). `--tlsverify` TLS support (default: `false`). `--tlsskipverify` Disable TLS server verification. `--trusted-origins` Specify (in a comma-separated list) the domain(s) used to access Portainer when it is behind a reverse proxy. Use this option if Portainer is behind a reverse proxy and you are getting "Origin invalid" errors. `--tunnel-addr` Specifies the tunnel address to listen on for use with the Edge Agent. Defaults to `0.0.0.0` (all interfaces). `--tunnel-port` Specifies 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`. `--version` Display the version of Portainer. [](https://docs.portainer.io/advanced/cli#creating-an-admin-account-and-password) Creating an admin account and password ----------------------------------------------------------------------------------------------------------------------------- The commands in this section will automatically create an administrator account called `admin` with the password you specify. This can only be used when first creating the admin user (such as during installation) and not to change the admin user's password after installation. ### [](https://docs.portainer.io/advanced/cli#method-1-creating-the-account-from-the-command-line) Method 1: Creating the account from the command line You can specify a bcrypt-encrypted password from the command line for the admin account. If you have installed the `apache2-utils` package, create the password using the following command: Copy htpasswd -nb -B admin "your-password" | cut -d ":" -f 2 If your system does not have that command, use a container to run the command instead: Copy docker run --rm httpd:2.4-alpine htpasswd -nbB admin "your-password" | cut -d ":" -f 2 Once the password has been created, specify the admin password from the command line by starting Portainer with the `--admin-password` flag: Business Edition Community Edition Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ee:lts --admin-password='$2y$05$8oz75U8m5tI/xT4P0NbSHeE7WyRzOWKRBprfGotwDkhBOGP/u802u' Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ce:lts --admin-password='$2y$05$8oz75U8m5tI/xT4P0NbSHeE7WyRzOWKRBprfGotwDkhBOGP/u802u' ### [](https://docs.portainer.io/advanced/cli#method-2-creating-the-account-using-a-file) Method 2: Creating the account using a file You can also store a plain text password inside a file and use the `--admin-password-file` flag. First, add the password to a file using the following example command as a guide: Copy echo -n mypassword > /tmp/portainer_password Next, start the Portainer container: Business Edition Community Edition Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock -v /tmp/portainer_password:/tmp/portainer_password portainer/portainer-ee:lts --admin-password-file /tmp/portainer_password Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock -v /tmp/portainer_password:/tmp/portainer_password portainer/portainer-ce:lts --admin-password-file /tmp/portainer_password This also works well with Docker Swarm and Docker Secrets: Copy echo -n mypassword | docker secret create portainer-pass - Business Edition Community Edition Copy docker service create \ --name portainer \ --secret portainer-pass \ --publish 9443:9443 \ --publish 8000:8000 \ --replicas=1 \ --constraint 'node.role == manager' \ --mount type=bind,src=/var/run/docker.sock,dst=/var/run/docker.sock \ portainer/portainer-ee:lts \ --admin-password-file '/run/secrets/portainer-pass' \ -H unix:///var/run/docker.sock Copy docker service create \ --name portainer \ --secret portainer-pass \ --publish 9443:9443 \ --publish 8000:8000 \ --replicas=1 \ --constraint 'node.role == manager' \ --mount type=bind,src=/var/run/docker.sock,dst=/var/run/docker.sock \ portainer/portainer-ce:lts \ --admin-password-file '/run/secrets/portainer-pass' \ -H unix:///var/run/docker.sock [](https://docs.portainer.io/advanced/cli#hiding-specific-containers) Hiding specific containers ----------------------------------------------------------------------------------------------------- Portainer lets you hide containers with a specific label by using the `-l` flag. Here's an example showing a container labeled `owner=acme`: Copy docker run -d --label owner=acme nginx To hide this container, when starting Portainer add the `-l owner=acme` option on the CLI: Business Edition Community Edition Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ee:lts -l owner=acme Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ce:lts -l owner=acme To hide multiple containers, repeat the `-l` flag: Business Edition Community Edition Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ee:lts -l owner=acme -l service=secret Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ce:lts -l owner=acme -l service=secret [](https://docs.portainer.io/advanced/cli#using-your-own-logo) Using your own logo --------------------------------------------------------------------------------------- Images must be exactly 155px by 55px in size. Replace our logo with your own using the `--logo` flag to specify the location of the image file: Business Edition Community Edition Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ee:lts --logo "https://www.docker.com/sites/all/themes/docker/assets/images/brand-full.svg" Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ce:lts --logo "https://www.docker.com/sites/all/themes/docker/assets/images/brand-full.svg" You can also update the logo in the Portainer UI (**Settings** menu). [](https://docs.portainer.io/advanced/cli#defining-your-own-app-templates) Defining your own app templates --------------------------------------------------------------------------------------------------------------- We suggest hosting template files on [GitHub](https://www.github.com/) so Portainer can access them without authentication. Portainer allows you to rapidly [deploy containers using app templates](https://docs.portainer.io/user/docker/templates/deploy-container) . By default, Portainer templates will be used but you can also define your own. Templates are loaded once when Portainer is first started. If you already deployed a Portainer instance then decide to use your own templates, you’ll need to clear the default templates either in the user interface or through the HTTP API. Use the `--templates` flag to specify a URL where the template file can be accessed via HTTP. Business Edition Community Edition Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ee:lts --templates http://my-host.my-domain/templates.json Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ce:lts --templates http://my-host.my-domain/templates.json [PreviousWhich versions of Portainer do you provide support for?](https://docs.portainer.io/faqs/getting-support/which-versions-of-portainer-do-you-provide-support-for) [NextApp templates](https://docs.portainer.io/advanced/app-templates) Last updated 2 months ago Was this helpful? --- # Welcome | Portainer Documentation Welcome to Portainer's official documentation site. [](https://docs.portainer.io/#about-portainer) 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](https://docs.portainer.io/admin/user/roles) , [registry management](https://docs.portainer.io/admin/registries/browse) , and [dedicated support](https://docs.portainer.io/#getting-support) , Portainer BE is a powerful toolset that allows you to easily build and manage containers in Docker, Docker Swarm, Kubernetes, Podman and Azure ACI. 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](https://www.portainer.io/get-a-license) of Portainer Business Edition or [purchase a license](https://www.portainer.io/pricing) . 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](https://docs.portainer.io/#community-edition-five-three-node-free-and-home-and-student-users) , and paid Business customers through our [business support channels](https://docs.portainer.io/#business-edition-customers) . [](https://docs.portainer.io/#documentation) 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 raise a question in one of our [support channels](https://docs.portainer.io/#getting-support) . For more detailed step-by-step guides to Portainer, we're building out the [Portainer Academy](https://academy.portainer.io/) with more courses regularly. 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](https://www.youtube.com/channel/UC7diMJcrULjDseq5yhSUZgg) , we cover a lot of ground but there may be gaps. [](https://docs.portainer.io/#getting-support) Getting support ------------------------------------------------------------------- ### [](https://docs.portainer.io/#community-edition-five-three-node-free-and-home-and-student-users) 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](https://github.com/orgs/portainer/discussions/categories/help) forum or the [community Slack channel](https://portainer.io/slack) . Other platforms exist (Reddit, Discord, Stack Overflow) but we are less active in those spaces. * **Log bugs** in [GitHub Issues](https://github.com/portainer/portainer/issues) so they can be properly managed. * **Flag vulnerabilities** by emailing [\[email protected\]](https://docs.portainer.io/cdn-cgi/l/email-protection#0477616771766d707d44746b7670656d6a61762a6d6b) so we can deal with them immediately. * **Flag documentation issues** via our [GitHub documentation channel](https://github.com/portainer/portainer-docs/issues) (or start [contributing](https://docs.portainer.io/contribute/contribute) and make our documentation better!). ### [](https://docs.portainer.io/#business-edition-customers) 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](https://docs.portainer.io/cdn-cgi/l/email-protection#4f2d3a3c26212a3c3c3c3a3f3f203d3b0f3f203d3b2e26212a3d612620) or filling out the [Request Support form](https://www.portainer.io/portainer-business-support) . 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. [NextWhat's new in version 2.33](https://docs.portainer.io/whats-new) Last updated 27 days ago Was this helpful? --- # What's new in version 2.33 | Portainer Documentation Portainer version 2.33 includes a number of new fixes and updates, bringing the changes from the previous STS releases into the LTS stream. For a full list of changes, please refer to our [release notes](https://docs.portainer.io/release-notes) . [](https://docs.portainer.io/whats-new#long-term-support-lts) Long Term Support (LTS) ------------------------------------------------------------------------------------------ 2.33 is a Long Term Support, or "LTS", release of Portainer. LTS releases are intended to to be solid, tested, production-ready versions of Portainer, suitable for running in both testing and production environments. LTS releases generally do not have any additional features as compared to the previous STS release, but rather are a consolidation of all the new features and changes that have gone into the previous STS releases but with additional polishing and testing. You can read more about our release principles in our [lifecycle policy](https://docs.portainer.io/start/lifecycle) . [](https://docs.portainer.io/whats-new#new-features) New features ---------------------------------------------------------------------- ### [](https://docs.portainer.io/whats-new#a-new-look) A new look ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FpVQRQqVtoWyELrx2mP2t%2Fbutton_be.png&width=300&dpr=4&quality=100&sign=b5e853a3&sv=2) ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FhuKHYhtXudVV9aNqAZsq%2Fbutton_ce.png&width=300&dpr=4&quality=100&sign=e75b4336&sv=2) The first change you'll notice in this release is a new look. We've updated and modernized the Portainer branding alongside this release, both in the application and on our website. We launched this new look in 2.32 and we've now brought it into our LTS release. These are the first iterations of this new branding, so expect to see more adjustments to this in subsequent releases. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FmHq6wcwAUbduH2B98ILY%2F2.32-whatsnew-branding.png&width=768&dpr=4&quality=100&sign=79c038c3&sv=2) ### [](https://docs.portainer.io/whats-new#experimental-observability) Experimental: Observability ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FpVQRQqVtoWyELrx2mP2t%2Fbutton_be.png&width=300&dpr=4&quality=100&sign=b5e853a3&sv=2) We introduced a new experimental feature in 2.32 - [Observability](https://docs.portainer.io/user/observability) - and this feature is now available within the LTS stream as well. With this prototype feature enabled, you can configure notifications to be sent on various conditions affecting your environments through various mechanisms (for example Slack, email, or via a webhook). ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FyUgN1Xop4VabwsGOY1DU%2F2.32-whatsnew-alerting.png&width=768&dpr=4&quality=100&sign=c3a9bb4e&sv=2) This feature is very much an [experimental feature](https://docs.portainer.io/admin/settings/general#experimental-features) , and as such we highly advise against enabling this on a production environment. We're keen to [get your feedback](https://github.com/orgs/portainer/discussions/12793) on the feature around what we can add or improve with it in future releases. [](https://docs.portainer.io/whats-new#kubernetes) Kubernetes ------------------------------------------------------------------ ### [](https://docs.portainer.io/whats-new#helm-overhaul) Helm overhaul ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FpVQRQqVtoWyELrx2mP2t%2Fbutton_be.png&width=300&dpr=4&quality=100&sign=b5e853a3&sv=2) ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FhuKHYhtXudVV9aNqAZsq%2Fbutton_ce.png&width=300&dpr=4&quality=100&sign=e75b4336&sv=2) 2.33 brings a brand new view of Helm deployments to Portainer. Clicking on a Helm deployment within the Applications list takes you to the new [Helm details](https://docs.portainer.io/user/kubernetes/applications/inspect-helm) page, which provides a ton of information about the deployment's status and configuration. Here you can see the history of a Helm deployment through the Revisions list, upgrade your chart version, and roll back to a previous revision if things go wrong. You can now also compare the configuration between the current deployment and previous revisions to see exactly what has changed between deployments. We've expanded the options available when deploying a Helm chart from a repository. You can now choose the repository to list charts from when deploying an app, choose the specific version of a Helm chart to deploy, and more easily make changes to any default values using the comparison display. We've also streamlined the way that we retrieve charts from Helm repositories to improve load times, and we've added functionality around Helm chart versions to allow you to manually refresh the version list on-demand. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FbQKII4JBkvHguBfYRxDn%2F2.32-kubernetes-applications-helm-details-buttons.png&width=768&dpr=4&quality=100&sign=af189323&sv=2) You can now also select chart sources for your deployments, allowing you to easily track where they came from and what changes you have made to your configuration compared to upstream sources. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FavOGLqVlNKvlbG2NQq8x%2F2.32-whatsnew-helm-chart-source.png&width=768&dpr=4&quality=100&sign=5493fe68&sv=2) Behind the scenes, we've switched to integrating the Helm SDK with Portainer, rather than our previous method of leveraging the Helm binary. Like the move away from the Docker Compose binary in previous versions, this change means one less vector for CVEs as well as improved performance and functionality. ### [](https://docs.portainer.io/whats-new#support-for-oci-format-helm-charts) Support for OCI format Helm charts ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FpVQRQqVtoWyELrx2mP2t%2Fbutton_be.png&width=300&dpr=4&quality=100&sign=b5e853a3&sv=2) This release introduces support for OCI-format Helm charts via OCI registries to the LTS stream. These registries are configured in the same way as [image registries](https://docs.portainer.io/admin/registries) , and any registries you currently have configured (and have given access to the respective namespace) that contain OCI charts will appear in the new Helm chart source dropdown when creating a deployment from Helm. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FaQ1f975TM3JcyE3ro8OT%2F2.32-whatsnew-oci.png&width=768&dpr=4&quality=100&sign=761c5df4&sv=2) ### [](https://docs.portainer.io/whats-new#namespace-operator-role) Namespace Operator role ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FpVQRQqVtoWyELrx2mP2t%2Fbutton_be.png&width=300&dpr=4&quality=100&sign=b5e853a3&sv=2) There's a new RBAC role for Kubernetes users in this release: Namespace Operator. This role has the same permissions as the standard Operator role, but applied specifically to assigned namespaces instead of the entire cluster. This provides additional flexibility to administrators when providing access to resources on clusters. [](https://docs.portainer.io/whats-new#edge) Edge ------------------------------------------------------ ### [](https://docs.portainer.io/whats-new#update-and-rollback-overhaul) Update & Rollback overhaul ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FpVQRQqVtoWyELrx2mP2t%2Fbutton_be.png&width=300&dpr=4&quality=100&sign=b5e853a3&sv=2) This release sees an overhaul of the [Update & Rollback](https://docs.portainer.io/admin/environments/update) functionality for Edge devices. We've refreshed the UI and expanded the schedule detail view to provide much more information including per-device status reports so you can confirm that all devices in the group were updated as expected. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2Fcvfj9A7UeoeRhPEZIyuK%2F2.32-environments-update-details.png&width=768&dpr=4&quality=100&sign=cb1094fb&sv=2) ### [](https://docs.portainer.io/whats-new#mtls-improvements) mTLS improvements ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FpVQRQqVtoWyELrx2mP2t%2Fbutton_be.png&width=300&dpr=4&quality=100&sign=b5e853a3&sv=2) This release also brings a number of updates to our [mTLS functionality](https://docs.portainer.io/advanced/mtls) . We've added a new icon for environments on the dashboard that indicates the mTLS status where relevant. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2F3850702872-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FXI7douejaBgpZ6CP2zJf%252Fuploads%252FuufMXZFa7PrOGNQ9mKuK%252F2.33-whatsnew-mtls.png%3Falt%3Dmedia%26token%3D88eaebcb-cfa1-4ba4-9ee1-214bbeac04cf&width=768&dpr=4&quality=100&sign=293f4b81&sv=2) We've also improved the ability to view and manage your mTLS certificates from the UI rather than just the CLI, as well as fixed a few mTLS-related bugs. You can now view details of your mTLS certificates within the UI from the [Edge Compute settings](https://docs.portainer.io/admin/settings/edge) as well as the mTLS status (and any errors) on individual environments from the home page. [](https://docs.portainer.io/whats-new#docker) Docker ---------------------------------------------------------- ### [](https://docs.portainer.io/whats-new#code-completion-and-validation-for-docker-compose) Code completion and validation for Docker Compose ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FpVQRQqVtoWyELrx2mP2t%2Fbutton_be.png&width=300&dpr=4&quality=100&sign=b5e853a3&sv=2) ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FhuKHYhtXudVV9aNqAZsq%2Fbutton_ce.png&width=300&dpr=4&quality=100&sign=e75b4336&sv=2) To help users ensure their stack files are valid when being written and before deployment, we've introduced code completion and validation functionality to the [Web editor](https://docs.portainer.io/user/docker/stacks/add#option-1-web-editor) . If you've used Visual Studio Code or other IDEs that provide code hints, you'll be familiar with this kind of feature. At present this functionality is available for Docker Compose only, but we hope to extend this to include validation for Kubernetes manifests in a future release. [](https://docs.portainer.io/whats-new#enhancements-and-fixes) Enhancements and fixes ------------------------------------------------------------------------------------------ ### [](https://docs.portainer.io/whats-new#kerberos-support-for-active-directory-authentication) Kerberos support for Active Directory authentication ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FpVQRQqVtoWyELrx2mP2t%2Fbutton_be.png&width=300&dpr=4&quality=100&sign=b5e853a3&sv=2) Portainer now supports Kerberos when [configuring Active Directory authentication](https://docs.portainer.io/admin/settings/authentication/active-directory) . You can choose between Simple and Kerberos bindings and configure the connection as required. ### [](https://docs.portainer.io/whats-new#performance-optimizations) Performance optimizations ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FpVQRQqVtoWyELrx2mP2t%2Fbutton_be.png&width=300&dpr=4&quality=100&sign=b5e853a3&sv=2) ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FhuKHYhtXudVV9aNqAZsq%2Fbutton_ce.png&width=300&dpr=4&quality=100&sign=e75b4336&sv=2) With every release we try to make using Portainer more responsive and performant, and this release is no exception. We continue to migrate more of our views to the React framework, and have made changes to how often we pull raw Docker snapshots, resulting in significantly faster load times. We've also made some adjustments to how systems work to reduce double-handling of data and in some cases drastically improve the load time of elements and data. [PreviousWelcome](https://docs.portainer.io/) [NextRelease Notes](https://docs.portainer.io/release-notes) Last updated 2 months ago Was this helpful? --- # Install Portainer BE | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/start/install-ce) . Portainer Business Edition is straightforward to install. There are two options: installing new or adding an environment to an existing installation. For a detailed, step-by-step guide to setting up Portainer for production, have a look at our [Best Practice Install Guide](https://academy.portainer.io/install/) in the Portainer Academy. If you haven't already, please check that your environments meet [our requirements](https://docs.portainer.io/start/requirements-and-prerequisites) before proceeding. [Set up a new Portainer BE Server installation](https://docs.portainer.io/start/install/server) [Add an environment to an existing installation](https://docs.portainer.io/start/agent) [PreviousRequirements and prerequisites](https://docs.portainer.io/start/requirements-and-prerequisites) [NextSet up a new Portainer BE Server installation](https://docs.portainer.io/start/install/server) Was this helpful? --- # Introduction | Portainer Documentation This section explains the Portainer architecture and how to install it. We recommend that you read the entire section to ensure your installation goes smoothly. Learn about the [architecture](https://docs.portainer.io/start/architecture) first, get familiar with the [prerequisites to installation](https://docs.portainer.io/start/requirements-and-prerequisites) , then finally, step through how to [install the product](https://docs.portainer.io/start/install) in your environment. [Portainer architecture](https://docs.portainer.io/start/architecture) [PreviousRelease Notes](https://docs.portainer.io/release-notes) [NextPortainer architecture](https://docs.portainer.io/start/architecture) Was this helpful? --- # Lifecycle policy | Portainer Documentation Portainer makes this policy public so customers and partners can effectively plan, deploy, and support their container management infrastructure effectively using Portainer. It is published in an effort to provide as much transparency as possible but Portainer has the discretion to make exceptions from this policy should that be in Portainer’s or our customer’s best interests. Any release dates are provided for guidance only and the exact dates may change. [](https://docs.portainer.io/start/lifecycle#the-portainer-lifecycle) The Portainer lifecycle -------------------------------------------------------------------------------------------------- Portainer releases approximately follow a monthly cadence for minor releases (X.Y) which can introduce feature enhancements and new features but endeavor to maintain backward compatibility. Micro or patch releases (X.Y.z) are released as needed and are limited to backward compatible bug fixes only. Major versions (X) will be much less frequent, will include potential breaking changes, and may require an upgrade or migration process from previous versions. All releases are cumulative - all previous enhancements and fixes are included in each release. [](https://docs.portainer.io/start/lifecycle#terminology) Terminology -------------------------------------------------------------------------- ### [](https://docs.portainer.io/start/lifecycle#supported-versus-maintained) Supported versus maintained When we say “supported”, we are referring to the commercial support that is included with Portainer Business Edition subscriptions at the Scale and Enterprise level. This includes access to all STS and LTS releases and patches. Our [support terms](https://www.portainer.io/support-terms) have more detail on what is and isn’t covered by our support. For Starter, Home & Student, our free Business Edition offerings, and our Community Edition, support is provided through our [community support channels](https://www.portainer.io/get-support-for-portainer) . The term “maintained” refers to the act of releasing updated versions of our releases, for example patches to resolve bugs or security issues. All editions of Business Edition and Community Edition will be maintained according to each release’s respective lifecycle. Portainer always recommends updating to the latest version in the release stream to ensure you have the latest security fixes, bug fixes, and performance improvements. It is at Portainer’s discretion to backport fixes to any version outside of the supported version window. ### [](https://docs.portainer.io/start/lifecycle#sts-versus-lts) STS versus LTS Portainer has two release streams, STS and LTS and it’s important you know the differences so you can choose accordingly. #### [](https://docs.portainer.io/start/lifecycle#short-term-support-sts-releases) **Short Term Support (STS) releases** Short Term Support releases are identified with an “STS” suffix. These are supported and maintained until the release of the next STS or LTS version. Use STS versions if you are interested in getting the latest features faster and don’t mind upgrading more frequently. #### [](https://docs.portainer.io/start/lifecycle#long-term-support-lts-releases) **Long Term Support (LTS) releases** Long Term Support releases are identified with an “LTS” suffix. These releases are supported and maintained until the release of the next LTS version plus a three month migration window so are more suitable for environments where adding new features on a frequent basis is less desirable. Portainer LTS releases focus less on new features and more on stability so Portainer recommends LTS releases for production workloads. [](https://docs.portainer.io/start/lifecycle#current-and-planned-releases) Current and planned releases ------------------------------------------------------------------------------------------------------------ Each stream (LTS and STS) will have a number of patch releases throughout it’s life. ### [](https://docs.portainer.io/start/lifecycle#current-releases) Current releases Release Release Date End of support/maintenance 2.27 LTS Feb 2025 Jan 2026 2.32 STS Jul 2025 Aug 2025 **2.33 LTS** **Aug 2025** **Jul 2026** ### [](https://docs.portainer.io/start/lifecycle#planned-releases) Planned releases Release Release Date End of support/maintenance 2.34 STS Sep 2025 Oct 2025 2.35 STS Oct 2025 Nov 2025 2.36 STS Nov 2025 Dec 2025 2.37 STS Dec 2025 Jan 2026 2.38 STS Jan 2026 Feb 2026 **2.39 LTS** **Feb 2026** **Jan 2027** ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2F3850702872-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FXI7douejaBgpZ6CP2zJf%252Fuploads%252FcdMU9UMPXzgd8AppXdhx%252F2.33-lifecycle-timetable.png%3Falt%3Dmedia%26token%3D08f55b50-fdaf-403b-bad5-7949e747f25d&width=768&dpr=4&quality=100&sign=538ab9b7&sv=2) Sitting on an older release that is no longer maintained or supported is strongly discouraged and customers take full responsibility for doing so. Customers are strongly encouraged to ensure they are running the latest patch release for a given stream. [](https://docs.portainer.io/start/lifecycle#older-releases-that-are-no-longer-supported-or-maintained) Older releases that are no longer supported or maintained ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- The following releases have passed the end of support date and are no longer maintained or supported. If you are using one of these versions (or older), we recommend that you [update](https://docs.portainer.io/start/upgrade) as soon as possible. Release Release Date End of support/maintenance 2.17 Feb 2023 Apr 2023 2.18 Apr 2023 Aug 2023 2.19 Aug 2023 Aug 2024 2.20 STS Mar 2024 Aug 2024 2.22 STS Sep 2024 Oct 2024 2.23 STS Oct 2024 Nov 2024 2.24 STS Nov 2024 Dec 2024 2.25 STS Dec 2024 Jan 2025 2.26 STS Jan 2025 Feb 2025 2.28 STS Mar 2025 Apr 2025 2.29 STS Apr 2025 May 2025 2.30 STS May 2025 Jun 2025 2.31 STS Jun 2025 Jul 2025 2.32 STS Jul 2025 Aug 2025 [](https://docs.portainer.io/start/lifecycle#notes) Notes -------------------------------------------------------------- Portainer uses the [semantic versioning scheme](https://semver.org/) and while Portainer endeavors to follow best practices, we reserve the right to make exceptions should that be in Portainer’s and our customer’s best interests. For information on the available options and best practices for updating Portainer deployments, [refer to our update documentation](https://docs.portainer.io/start/upgrade) . [Requirements and prerequisites](https://docs.portainer.io/start/requirements-and-prerequisites) [PreviousPortainer architecture](https://docs.portainer.io/start/architecture) [NextRequirements and prerequisites](https://docs.portainer.io/start/requirements-and-prerequisites) Last updated 3 months ago Was this helpful? --- # Portainer architecture | Portainer Documentation [](https://docs.portainer.io/start/architecture#overview-of-portainer-architecture) Overview of Portainer architecture --------------------------------------------------------------------------------------------------------------------------- Portainer consists of two elements: the Portainer Server and the Portainer Agent. Both run as lightweight containers on your existing containerized infrastructure. The Portainer Agent should be deployed to each node in your cluster and configured to report back to the Portainer Server container. For a deeper dive into the architecture of Portainer, have a look at our [reference architecture](https://academy.portainer.io/architecture) . A single Portainer Server will accept connections from any number of Portainer Agents, providing the ability to manage multiple clusters from one centralized interface. To do this, the Portainer Server container requires data persistence. The Portainer Agents are stateless, with data being shipped back to the Portainer Server container. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2F3850702872-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FXI7douejaBgpZ6CP2zJf%252Fuploads%252Fu8y7KhDgTuX7sAgDYzhq%252F2.33-portainer-architecture-detailed.png%3Falt%3Dmedia%26token%3D00bca304-b341-4d2c-9d03-6ade54a66928&width=768&dpr=4&quality=100&sign=a3cab813&sv=2) We don't currently support running multiple instances of the Portainer Server container to manage the same clusters. We recommend running the Portainer Server on a specific management node, with Portainer Agents deployed across the remaining nodes. [](https://docs.portainer.io/start/architecture#agent-vs-edge-agent) Agent vs Edge Agent --------------------------------------------------------------------------------------------- In standard deployments, the central Portainer Server instance and any environments it manages are assumed to be on the same network, that is, Portainer Server and the Portainer Agents are able to seamlessly communicate with one another. However, in configurations where the remote environments are on a completely separate network to Portainer Server, say, across the internet, historically we would have been unable to centrally manage these devices. With the new Edge Agent, we altered the architecture. Rather than the Portainer Server needing seamless access to the remote environment, only the remote environments need to be able to access the Portainer Server. This communication is performed over an encrypted TLS tunnel. This is important in Internet-connected configurations where there is no desire to expose the Portainer Agent to the internet. [](https://docs.portainer.io/start/architecture#security-and-compliance) Security and compliance ----------------------------------------------------------------------------------------------------- Portainer runs exclusively on your servers, within your network, behind your own firewalls. As a result, we do not currently hold any SOC or PCI/DSS compliance because we do not host any of your infrastructure. You can even run Portainer completely disconnected (air-gapped) without any impact on functionality. While we do (optionally) collect anonymous usage analytics from Portainer installations, we remain compliant with GDPR. Data collection can be disabled when you install the product, or at any time after that. If your installation is air-gapped, collection will silently fail without any adverse effects. [Lifecycle policy](https://docs.portainer.io/start/lifecycle) [PreviousIntroduction](https://docs.portainer.io/start/intro) [NextLifecycle policy](https://docs.portainer.io/start/lifecycle) Last updated 2 months ago Was this helpful? --- # Install Portainer BE with Docker on WSL / Docker Desktop | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/start/install-ce/server/docker/wsl) . [](https://docs.portainer.io/start/install/server/docker/wsl#introduction) Introduction -------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_, and the _Portainer Agent_. Both elements run as lightweight Docker containers on a Docker engine. This document will help you install the Portainer Server container on your Windows environment with WSL and Docker Desktop. To add a new WSL / Docker Desktop environment to an existing Portainer Server installation, please refer to the [Portainer Agent installation instructions](https://docs.portainer.io/admin/environments/add/docker/agent) . To get started, you will need: * The latest version of Docker Desktop installed and working. * Administrator access on the machine that will host your Portainer Server instance. * Windows Subsystem for Linux (WSL) installed and a Linux distribution selected. For a new installation we recommend WSL2. * By default, Portainer Server will expose the UI over port `9443` and expose a TCP tunnel server over port `8000`. The latter is optional and is only required if you plan to use the Edge compute features with Edge agents. * A license key for Portainer Business Edition. The installation instructions also make the following assumptions about your environment: * Your environment meets [our requirements](https://docs.portainer.io/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. * You are accessing Docker via Unix sockets. Alternatively, you can also connect via TCP. * SELinux is disabled within the Linux distribution used by WSL. If you require SELinux, you will need to pass the `--privileged` flag to Docker when deploying Portainer. * Docker is running as root. Portainer with rootless Docker has some limitations, and requires additional configuration. [](https://docs.portainer.io/start/install/server/docker/wsl#deployment) Deployment ---------------------------------------------------------------------------------------- First, create the volume that Portainer Server will use to store its database: Copy docker volume create portainer_data Then, download and install the Portainer Server container: Copy docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ee:lts By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/advanced/ssl#using-your-own-ssl-certificate-on-docker-standalone) or [via the Portainer UI](https://docs.portainer.io/admin/settings#ssl-certificate) after installation is complete. If you require HTTP port `9000` open for legacy reasons, add the following to your `docker run` command: `-p 9000:9000` Portainer Server has now been installed. You can check to see whether the Portainer Server container has started by running `docker ps`: Copy root@server:~# docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES f4ab79732007 portainer/portainer-ee:lts "/portainer" 2 weeks ago Up 29 hours 0.0.0.0:8000->8000/tcp, :::8000->8000/tcp, 0.0.0.0:9443->9000/tcp, :::9443->9443/tcp portainer [](https://docs.portainer.io/start/install/server/docker/wsl#logging-in) Logging In ---------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance by opening a web browser and going to: Copy https://localhost:9443 Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/start/install/server/setup) [PreviousInstall Portainer BE with Docker on Linux](https://docs.portainer.io/start/install/server/docker/linux) [NextInstall Portainer BE with Docker on Windows Container Service](https://docs.portainer.io/start/install/server/docker/wcs) Last updated 3 months ago Was this helpful? --- # Docker Swarm | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/start/install-ce/server/swarm) . Installation instructions can differ between platforms. Please choose your platform below: [Install Portainer BE with Docker Swarm on Linux](https://docs.portainer.io/start/install/server/swarm/linux) [Install Portainer BE with Docker Swarm on WSL / Docker Desktop](https://docs.portainer.io/start/install/server/swarm/wsl) [Install Portainer BE with Docker Swarm on Windows Container Service](https://docs.portainer.io/start/install/server/swarm/wcs) [PreviousInstall Portainer BE with Docker on Windows Container Service](https://docs.portainer.io/start/install/server/docker/wcs) [NextInstall Portainer BE with Docker Swarm on Linux](https://docs.portainer.io/start/install/server/swarm/linux) Was this helpful? --- # Set up a new Portainer BE Server installation | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/start/install-ce/server) . Select the environment for your new Portainer installation: [Docker Standalone](https://docs.portainer.io/start/install/server/docker) [Docker Swarm](https://docs.portainer.io/start/install/server/swarm) [Podman](https://docs.portainer.io/start/install/server/podman) [Kubernetes](https://docs.portainer.io/start/install/server/kubernetes) [PreviousInstall Portainer BE](https://docs.portainer.io/start/install) [NextDocker Standalone](https://docs.portainer.io/start/install/server/docker) Was this helpful? --- # Install Portainer BE with Docker Swarm on Linux | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/start/install-ce/server/swarm/linux) . [](https://docs.portainer.io/start/install/server/swarm/linux#introduction) Introduction --------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_ and the _Portainer Agent_. Both elements run as lightweight Docker containers on a Docker engine. This document will help you deploy the Portainer Server and Agent containers on your Linux environment. To add a new Linux Swarm environment to an existing Portainer Server installation, please refer to the [Portainer Agent installation instructions](https://docs.portainer.io/admin/environments/add/swarm/agent) . To get started, you will need: * The latest version of Docker installed and working. We recommend following the [official installation instructions](https://docs.docker.com/engine/install/) for Docker - in particular, we advise _against_ installing Docker via snap on Ubuntu distributions as you may run into compatibility issues. * Swarm mode [enabled](https://docs.docker.com/engine/swarm/swarm-mode/) and working, including the overlay network for the swarm service communication * `sudo` access on the manager node of your swarm cluster * By default, Portainer will expose the UI over port `9443` and expose a TCP tunnel server over port `8000`. The latter is optional and is only required if you plan to use the Edge compute features with Edge agents. * The manager and worker nodes must be able to communicate with each other over port `9001`. * A license key for Portainer Business Edition. The installation instructions also make the following assumptions about your environment: * Your environment meets [our requirements](https://docs.portainer.io/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. * You are accessing Docker via Unix sockets. Connecting via TCP is not supported in Docker Swarm. * SELinux is disabled on the machine running Docker. * Docker is running as root. Portainer with rootless Docker has some limitations, and requires additional configuration. * You are running a single manager node in your swarm. If you have more than one, please [read this knowledge base article](https://portal.portainer.io/knowledge/how-can-i-ensure-portainers-configuration-is-retained) before proceeding. * If your nodes are using DNS records to communicate, that all records are resolvable across the cluster. [](https://docs.portainer.io/start/install/server/swarm/linux#deployment) Deployment ----------------------------------------------------------------------------------------- Portainer can be directly deployed as a service in your Docker cluster. Note that this method will automatically deploy a single instance of the Portainer Server, and deploy the Portainer Agent as a global service on every node in your cluster. Only do this **once** for your environment, regardless of how many nodes are in the cluster. You **do not** need to add each node in your cluster as a separate environment in Portainer. Deploying the manifest to your swarm will include every node in the cluster automatically. Adding each node as a separate environment will also consume more of your licensed node count than you may expect. First, retrieve the stack YML manifest: Copy curl -L https://downloads.portainer.io/ee-lts/portainer-agent-stack.yml -o portainer-agent-stack.yml Then use the downloaded YML manifest to deploy your stack: Copy docker stack deploy -c portainer-agent-stack.yml portainer By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/advanced/ssl#using-your-own-ssl-certificate-on-docker-swarm) or [via the Portainer UI](https://docs.portainer.io/admin/settings#ssl-certificate) after installation is complete. Portainer Server and the Agents have now been installed. You can check to see whether the Portainer Server and Agent containers have started by running `docker ps`: Copy root@manager01:~# docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 59ee466f6b15 portainer/agent:lts "./agent" About a minute ago Up About a minute portainer_agent.xbb8k6r7j1tk9gozjku7e43wr.5sa6b3e8cl6hyu0snlt387sgv 2db7dd4bfba0 portainer/portainer-ee:lts "/portainer -H tcp:/…" About a minute ago Up About a minute 8000/tcp, 9443/tcp portainer_portainer.1.gpuvu3pqmt1m19zxfo44v7izx [](https://docs.portainer.io/start/install/server/swarm/linux#logging-in) Logging In ----------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance by opening a web browser and going to: Copy https://localhost:9443 Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/start/install/server/setup) [PreviousDocker Swarm](https://docs.portainer.io/start/install/server/swarm) [NextInstall Portainer BE with Docker Swarm on WSL / Docker Desktop](https://docs.portainer.io/start/install/server/swarm/wsl) Last updated 3 months ago Was this helpful? --- # Docker Standalone | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/start/install-ce/server/docker) . Installation instructions can differ between platforms. Please choose your platform below: [Install Portainer BE with Docker on Linux](https://docs.portainer.io/start/install/server/docker/linux) [Install Portainer BE with Docker on WSL / Docker Desktop](https://docs.portainer.io/start/install/server/docker/wsl) [Install Portainer BE with Docker on Windows Container Service](https://docs.portainer.io/start/install/server/docker/wcs) [PreviousSet up a new Portainer BE Server installation](https://docs.portainer.io/start/install/server) [NextInstall Portainer BE with Docker on Linux](https://docs.portainer.io/start/install/server/docker/linux) Was this helpful? --- # Install Portainer BE with Docker on Windows Container Service | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/start/install-ce/server/docker/wcs) . [](https://docs.portainer.io/start/install/server/docker/wcs#introduction) Introduction -------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_, and the _Portainer Agent_. Both elements run as lightweight Docker containers on a Docker engine. This document will help you install the Portainer Server container on your Windows server with Windows Containers. To add a new WCS environment to an existing Portainer Server installation, please refer to the [Portainer Agent installation instructions](https://docs.portainer.io/admin/environments/add/docker/agent) . To get started, you will need: * Administrator access on the machine that will host your Portainer Server instance * By default, Portainer Server will expose the UI over port `9443` and expose a TCP tunnel server over port `8000`. The latter is optional and is only required if you plan to use the Edge compute features with Edge agents. * A license key for Portainer Business Edition. The installation instructions also make the following assumption about your environment: * Your environment meets [our requirements](https://docs.portainer.io/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. [](https://docs.portainer.io/start/install/server/docker/wcs#preparation) Preparation ------------------------------------------------------------------------------------------ To run Portainer Server in a Windows Server/Desktop Environment you need to create exceptions in the firewall. These can easily be added through PowerShell by running the following commands: Copy netsh advfirewall firewall add rule name="cluster_management" dir=in action=allow protocol=TCP localport=2377 netsh advfirewall firewall add rule name="node_communication_tcp" dir=in action=allow protocol=TCP localport=7946 netsh advfirewall firewall add rule name="node_communication_udp" dir=in action=allow protocol=UDP localport=7946 netsh advfirewall firewall add rule name="overlay_network" dir=in action=allow protocol=UDP localport=4789 netsh advfirewall firewall add rule name="swarm_dns_tcp" dir=in action=allow protocol=TCP localport=53 netsh advfirewall firewall add rule name="swarm_dns_udp" dir=in action=allow protocol=UDP localport=53 You will also need to install the Windows Container Host Service and install Docker. Microsoft have [provided](https://learn.microsoft.com/en-us/virtualization/windowscontainers/quick-start/set-up-environment?tabs=dockerce#windows-server-1) a PowerShell script to perform the necessary actions. You can download the script and run it with the following commands: Copy Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/microsoft/Windows-Containers/Main/helpful_tools/Install-DockerCE/install-docker-ce.ps1" -o install-docker-ce.ps1 .\install-docker-ce.ps1 Once this is complete you will need to restart your Windows server. After the restart completes, you're ready to install Portainer itself. [](https://docs.portainer.io/start/install/server/docker/wcs#deployment) Deployment ---------------------------------------------------------------------------------------- First, create the volume that Portainer Server will use to store its database. Using PowerShell: Copy docker volume create portainer_data Then, download and install the Portainer Server container: Copy docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart always -v \\.\pipe\docker_engine:\\.\pipe\docker_engine -v portainer_data:C:\data portainer/portainer-ee:lts By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/advanced/ssl) or [via the Portainer UI](https://docs.portainer.io/admin/settings#ssl-certificate) after installation is complete. If you see an error message similar to: `"\\.\pipe\dockerDesktopEngine" includes invalid characters for a local volume name` then you may not have Windows containers properly enabled. If you are using Docker Desktop, right click the icon in your tray and select **Switch to Windows Containers**. If you require HTTP port `9000` open for legacy reasons, add the following to your `docker run` command: `-p 9000:9000` [](https://docs.portainer.io/start/install/server/docker/wcs#logging-in) Logging In ---------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance by opening a web browser and going to: Copy https://localhost:9443 Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/start/install/server/setup) [PreviousInstall Portainer BE with Docker on WSL / Docker Desktop](https://docs.portainer.io/start/install/server/docker/wsl) [NextDocker Swarm](https://docs.portainer.io/start/install/server/swarm) Last updated 3 months ago Was this helpful? --- # Install Portainer CE | Portainer Documentation These installation instructions are for Portainer Community Edition (CE). For Portainer Business Edition (BE) refer to the [BE install documentation](https://docs.portainer.io/start/install) . Portainer Community Edition is straightforward to install. There are two options: installing new or adding an environment to an existing installation. If you haven't already, please check that your environments meet [our requirements](https://docs.portainer.io/start/requirements-and-prerequisites) before proceeding. [Set up a new Portainer CE Server installation](https://docs.portainer.io/start/install-ce/server) [Add an environment to an existing installation](https://docs.portainer.io/start/agent) [PreviousInitial setup](https://docs.portainer.io/start/install/server/setup) [NextSet up a new Portainer CE Server installation](https://docs.portainer.io/start/install-ce/server) Last updated 2 months ago Was this helpful? --- # Install Portainer BE with Docker on Linux | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/start/install-ce/server/docker/linux) . [](https://docs.portainer.io/start/install/server/docker/linux#introduction) Introduction ---------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_, and the _Portainer Agent_. Both elements run as lightweight Docker containers on a Docker engine. This document will help you install the Portainer Server container on your Linux environment. To add a new Linux environment to an existing Portainer Server installation, please refer to the [Portainer Agent installation instructions](https://docs.portainer.io/admin/environments/add/docker/agent) . To get started, you will need: * The latest version of Docker installed and working. We recommend following the [official installation instructions](https://docs.docker.com/engine/install/) for Docker - in particular, we advise _against_ installing Docker via snap on Ubuntu distributions as you may run into compatibility issues. * sudo access on the machine that will host your Portainer Server instance * By default, Portainer Server will expose the UI over port `9443` and expose a TCP tunnel server over port `8000`. The latter is optional and is only required if you plan to use the Edge compute features with Edge agents. * A license key for Portainer Business Edition. The installation instructions also make the following assumptions about your environment: * Your environment meets [our requirements](https://docs.portainer.io/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. * You are accessing Docker via Unix sockets. Alternatively, you can also connect via TCP. * SELinux is disabled on the machine running Docker. If you require SELinux, you will need to pass the `--privileged` flag to Docker when deploying Portainer. * Docker is running as root. Portainer with rootless Docker has some limitations, and requires additional configuration. [](https://docs.portainer.io/start/install/server/docker/linux#deployment) Deployment ------------------------------------------------------------------------------------------ You can choose to deploy Portainer using `docker run` or via Docker Compose. docker run Docker Compose To install using `docker run`, first create the volume that Portainer Server will use to store its database: Copy docker volume create portainer_data Then, download and install the Portainer Server container: Copy docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ee:lts By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/advanced/ssl#using-your-own-ssl-certificate-on-docker-standalone) or [via the Portainer UI](https://docs.portainer.io/admin/settings#ssl-certificate) after installation is complete. If you require HTTP port `9000` open for legacy reasons, add the following to your `docker run` command: `-p 9000:9000` Portainer Server has now been installed. You can check to see whether the Portainer Server container has started by running `docker ps`: Copy root@server:~# docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 7963585688a9 portainer/portainer-ee:lts "/portainer" 8 seconds ago Up 8 seconds 0.0.0.0:8000->8000/tcp, [::]:8000->8000/tcp, 0.0.0.0:9443->9443/tcp, [::]:9443->9443/tcp, 9000/tcp portainer To install using Docker Compose, download the compose file using the following `curl` command: Copy curl -L https://downloads.portainer.io/ee-lts/portainer-compose.yaml -o portainer-compose.yaml Alternatively, create a `portainer-compose.yaml` file with the following contents: Copy services: portainer: container_name: portainer image: portainer/portainer-ee:lts restart: always volumes: - /var/run/docker.sock:/var/run/docker.sock - portainer_data:/data ports: - 9443:9443 - 8000:8000 # Remove if you do not intend to use Edge Agents volumes: portainer_data: name: portainer_data networks: default: name: portainer_network Once you have created or downloaded the compose file, you can deploy it with the following command: Copy docker compose -f portainer-compose.yaml up -d Docker Compose will create the necessary resources and deploy Portainer. You can check to see whether the Portainer Server container has started by running `docker ps`: Copy root@server:~# docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 7963585688a9 portainer/portainer-ee:lts "/portainer" 8 seconds ago Up 8 seconds 0.0.0.0:8000->8000/tcp, [::]:8000->8000/tcp, 0.0.0.0:9443->9443/tcp, [::]:9443->9443/tcp, 9000/tcp portainer [](https://docs.portainer.io/start/install/server/docker/linux#logging-in) Logging In ------------------------------------------------------------------------------------------ Now that the installation is complete, you can log into your Portainer Server instance by opening a web browser and going to: Copy https://localhost:9443 Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/start/install/server/setup) [PreviousDocker Standalone](https://docs.portainer.io/start/install/server/docker) [NextInstall Portainer BE with Docker on WSL / Docker Desktop](https://docs.portainer.io/start/install/server/docker/wsl) Last updated 1 month ago Was this helpful? --- # Podman | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/start/install-ce/server/podman) . Installation instructions can differ between platforms. Please choose your platform below: [Install Portainer BE with Podman on Linux](https://docs.portainer.io/start/install/server/podman/linux) [PreviousInstall Portainer BE with Docker Swarm on Windows Container Service](https://docs.portainer.io/start/install/server/swarm/wcs) [NextInstall Portainer BE with Podman on Linux](https://docs.portainer.io/start/install/server/podman/linux) Was this helpful? --- # Set up a new Portainer CE Server installation | Portainer Documentation These installation instructions are for Portainer Community Edition (CE). For Portainer Business Edition (BE) refer to the [BE install documentation](https://docs.portainer.io/start/install/server) . Select the environment for your new Portainer installation: [Docker Standalone](https://docs.portainer.io/start/install-ce/server/docker) [Docker Swarm](https://docs.portainer.io/start/install-ce/server/swarm) [Podman](https://docs.portainer.io/start/install-ce/server/podman) [Kubernetes](https://docs.portainer.io/start/install-ce/server/kubernetes) [PreviousInstall Portainer CE](https://docs.portainer.io/start/install-ce) [NextDocker Standalone](https://docs.portainer.io/start/install-ce/server/docker) Was this helpful? --- # Initial setup | Portainer Documentation Once the Portainer Server has been deployed, and you have navigated to the instance's URL, you are ready for the initial setup. [](https://docs.portainer.io/start/install/server/setup#creating-the-first-user) Creating the first user ------------------------------------------------------------------------------------------------------------- Your first user will be an administrator. The username defaults to `admin` but you can change it if you prefer. The password must be at least 12 characters long and meet the listed password requirements. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FnNR4InVfHQ3iUqIInTAP%2F2.32-initial-setup-username.png&width=768&dpr=4&quality=100&sign=53f28ee7&sv=2) [](https://docs.portainer.io/start/install/server/setup#enabling-or-disabling-the-collection-of-statistics) Enabling or disabling the collection of statistics ------------------------------------------------------------------------------------------------------------------------------------------------------------------- We use a tool called [Matomo](https://matomo.org/) to collect anonymous information about how Portainer is used. We recommend enabling this option so we can make improvements based on usage. For more about what we do with the information we collect, read our [privacy policy](https://www.portainer.io/privacy-policy) . During installation, you can enable or disable connection statistics using the checkbox. If you change your mind later, you can easily update this option under [Settings](https://docs.portainer.io/admin/settings/general#allow-the-collection-of-anonymous-statistics) in the Portainer UI. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FzScp6UVlgkXTgKqfTL5b%2F2.15-install-server-setup-matomo.png&width=768&dpr=4&quality=100&sign=e4119240&sv=2) [](https://docs.portainer.io/start/install/server/setup#add-your-license-key) Add your license key ------------------------------------------------------------------------------------------------------- You will now be asked to provide your license key. You will have been provided this when signing up for Business Edition or the free trial. If you don't have a license key, you can either click the **Don't have a license?** link or [get in touch with our team](https://docs.portainer.io/cdn-cgi/l/email-protection#0a797f69696f79794a7a65787e6b63646f78246365) . Paste the license key you were provided into the box and click **Submit**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FrJAYMtRQ2RjtD337fMWE%2F2.32-initial-setup-license.png&width=768&dpr=4&quality=100&sign=33112717&sv=2) [](https://docs.portainer.io/start/install/server/setup#connecting-portainer-to-your-environments) Connecting Portainer to your environments ------------------------------------------------------------------------------------------------------------------------------------------------- Once the admin user has been created, the **Environment Wizard** will automatically launch. The wizard will help get you started with Portainer. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2F0B7ZCiVtVdjwm4ajBcYf%2F2.32-initial-setup-welcome.png&width=768&dpr=4&quality=100&sign=2f8d30d6&sv=2) The installation process automatically detects your local environment and sets it up for you. If you want to add additional environments to manage with this Portainer instance, click **Add Environments**. Otherwise, click **Get Started** to start using Portainer! [PreviousInstall Portainer BE with Kubernetes on WSL / Docker Desktop](https://docs.portainer.io/start/install/server/kubernetes/wsl) [NextInstall Portainer CE](https://docs.portainer.io/start/install-ce) Was this helpful? --- # Kubernetes | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/start/install-ce/server/kubernetes) . Installation instructions can differ between platforms. Please choose your platform below: [Install Portainer BE on your Kubernetes environment](https://docs.portainer.io/start/install/server/kubernetes/baremetal) [Install Portainer BE with Kubernetes on WSL / Docker Desktop](https://docs.portainer.io/start/install/server/kubernetes/wsl) [PreviousInstall Portainer BE with Podman on Linux](https://docs.portainer.io/start/install/server/podman/linux) [NextInstall Portainer BE on your Kubernetes environment](https://docs.portainer.io/start/install/server/kubernetes/baremetal) Last updated 2 months ago Was this helpful? --- # Install Portainer BE with Docker Swarm on WSL / Docker Desktop | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/start/install-ce/server/swarm/wsl) . [](https://docs.portainer.io/start/install/server/swarm/wsl#introduction) Introduction ------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_, and the _Portainer Agent_. Both elements run as lightweight Docker containers on a Docker engine. This document will help you install the Portainer Server container on your Windows environment with WSL and Docker Desktop. To add a new WSL / Docker Desktop Swarm environment to an existing Portainer Server installation, please refer to the [Portainer Agent installation instructions](https://docs.portainer.io/admin/environments/add/swarm/agent) . To get started, you will need: * The latest version of Docker Desktop installed and working. * Swarm mode [enabled](https://docs.docker.com/engine/swarm/swarm-mode/) and working, including the overlay network for the swarm service communication. * Administrator access on the manager node of your Swarm cluster. * Windows Subsystem for Linux (WSL) installed and a Linux distribution selected. For a new installation we recommend WSL2. * By default, Portainer will expose the UI over port `9443` and expose a TCP tunnel server over port `8000`. The latter is optional and is only required if you plan to use the Edge compute features with Edge agents. * The manager and worker nodes must be able to communicate with each other over port `9001`. * A license key for Portainer Business Edition. The installation instructions also make the following assumptions about your environment: * Your environment meets [our requirements](https://docs.portainer.io/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. * You are accessing Docker via Unix sockets. Alternatively, you can also connect via TCP. * SELinux is disabled within the Linux distribution used by WSL. * Docker is running as root. Portainer with rootless Docker has some limitations, and requires additional configuration. * You are running a single manager node in your swarm. If you have more than one, please [read this article](https://docs.portainer.io/faqs/installing/how-can-i-ensure-portainers-configuration-is-retained) before proceeding. * If your nodes are using DNS records to communicate, that all records are resolvable across the cluster. [](https://docs.portainer.io/start/install/server/swarm/wsl#deployment) Deployment --------------------------------------------------------------------------------------- Portainer can be directly deployed as a service in your Docker Swarm cluster. Note that this method will automatically deploy a single instance of the Portainer Server, and deploy the Portainer Agent as a global service on every node in your cluster. Only do this **once** for your environment, regardless of how many nodes are in the cluster. You **do not** need to add each node in your cluster as a separate environment in Portainer. Deploying the manifest to your swarm will include every node in the cluster automatically. Adding each node as a separate environment will also consume more of your licensed node count than you may expect. To begin the installation, first retrieve the stack YML manifest: Copy curl -L https://downloads.portainer.io/ee-lts/portainer-agent-stack.yml -o portainer-agent-stack.yml Then use the downloaded YML manifest to deploy your stack: Copy docker stack deploy -c portainer-agent-stack.yml portainer By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/advanced/ssl#using-your-own-ssl-certificate-on-docker-swarm) or [via the Portainer UI](https://docs.portainer.io/admin/settings#ssl-certificate) after installation is complete. [](https://docs.portainer.io/start/install/server/swarm/wsl#logging-in) Logging In --------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance by opening a web browser and going to: Copy https://localhost:9443 Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/start/install/server/setup) [PreviousInstall Portainer BE with Docker Swarm on Linux](https://docs.portainer.io/start/install/server/swarm/linux) [NextInstall Portainer BE with Docker Swarm on Windows Container Service](https://docs.portainer.io/start/install/server/swarm/wcs) Last updated 2 months ago Was this helpful? --- # Docker Standalone | Portainer Documentation These installation instructions are for Portainer Community Edition (CE). For Portainer Business Edition (BE) refer to the [BE install documentation](https://docs.portainer.io/start/install/server/docker) . Installation instructions can differ between platforms. Please choose your platform below: [Install Portainer CE with Docker on Linux](https://docs.portainer.io/start/install-ce/server/docker/linux) [Install Portainer CE with Docker on WSL / Docker Desktop](https://docs.portainer.io/start/install-ce/server/docker/wsl) [Install Portainer CE with Docker on Windows Container Service](https://docs.portainer.io/start/install-ce/server/docker/wcs) [PreviousSet up a new Portainer CE Server installation](https://docs.portainer.io/start/install-ce/server) [NextInstall Portainer CE with Docker on Linux](https://docs.portainer.io/start/install-ce/server/docker/linux) Was this helpful? --- # Install Portainer BE with Docker Swarm on Windows Container Service | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/start/install-ce/server/swarm/wcs) . [](https://docs.portainer.io/start/install/server/swarm/wcs#introduction) Introduction ------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_, and the _Portainer Agent_. Both elements run as lightweight Docker containers on a Docker engine. This document will help you install the Portainer Server container on your Windows server with Windows Containers. To add a new WCS environment to an existing Portainer Server installation, please refer to the [Portainer Agent installation instructions](https://docs.portainer.io/admin/environments/add/swarm/agent) . To get started, you will need: * The latest version of Docker installed and working. * Swarm mode [enabled](https://docs.docker.com/engine/swarm/swarm-mode/) and working, including the overlay network for the swarm service communication. * Administrator access on the manager node of your Swarm cluster. * By default, Portainer will expose the UI over port `9443` and expose a TCP tunnel server over port `8000`. The latter is optional and is only required if you plan to use the Edge compute features with Edge agents. * The manager and worker nodes must be able to communicate with each other over port `9001`. * A license key for Portainer Business Edition. The installation instructions also make the following assumptions about your environment: * Your environment meets [our requirements](https://docs.portainer.io/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. * You are running a single manager node in your swarm. If you have more than one, please [read this article](https://docs.portainer.io/faqs/installing/how-can-i-ensure-portainers-configuration-is-retained) before proceeding. * If your nodes are using DNS records to communicate, that all records are resolvable across the cluster. [](https://docs.portainer.io/start/install/server/swarm/wcs#preparation) Preparation ----------------------------------------------------------------------------------------- To run Portainer Server in a Windows Server/Desktop Environment you need to create exceptions in the firewall. These can easily be added through PowerShell by running the following commands: Copy netsh advfirewall firewall add rule name="cluster_management" dir=in action=allow protocol=TCP localport=2377 netsh advfirewall firewall add rule name="node_communication_tcp" dir=in action=allow protocol=TCP localport=7946 netsh advfirewall firewall add rule name="node_communication_udp" dir=in action=allow protocol=UDP localport=7946 netsh advfirewall firewall add rule name="overlay_network" dir=in action=allow protocol=UDP localport=4789 netsh advfirewall firewall add rule name="swarm_dns_tcp" dir=in action=allow protocol=TCP localport=53 netsh advfirewall firewall add rule name="swarm_dns_udp" dir=in action=allow protocol=UDP localport=53 You will also need to install the Windows Container Host Service and install Docker. Microsoft have [provided](https://learn.microsoft.com/en-us/virtualization/windowscontainers/quick-start/set-up-environment?tabs=dockerce#windows-server-1) a PowerShell script to perform the necessary actions. You can download the script and run it with the following commands: Copy Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/microsoft/Windows-Containers/Main/helpful_tools/Install-DockerCE/install-docker-ce.ps1" -o install-docker-ce.ps1 .\install-docker-ce.ps1 Once this is complete you will need to restart your Windows server. After the restart completes, you're ready to install Portainer itself. [](https://docs.portainer.io/start/install/server/swarm/wcs#deployment) Deployment --------------------------------------------------------------------------------------- Portainer can be directly deployed as a service in your Docker cluster. Note that this method will automatically deploy a single instance of the Portainer Server, and deploy the Portainer Agent as a global service on every node in your cluster. Only do this **once** for your environment, regardless of how many nodes are in the cluster. You **do not** need to add each node in your cluster as a separate environment in Portainer. Deploying the manifest to your swarm will include every node in the cluster automatically. Adding each node as a separate environment will also consume more of your licensed node count than you may expect. You can use our YML manifest to run Portainer in Windows using Windows Containers. In PowerShell, run: Copy curl https://downloads.portainer.io/ee-lts/portainer_windows_stack.yml -o portainer-windows-stack.yml Then use the downloaded YML manifest to deploy your stack: Copy docker stack deploy --compose-file=portainer-windows-stack.yml portainer By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/advanced/ssl#using-your-own-ssl-certificate-on-docker-swarm) or [via the Portainer UI](https://docs.portainer.io/admin/settings#ssl-certificate) after installation is complete. [](https://docs.portainer.io/start/install/server/swarm/wcs#logging-in) Logging In --------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance by opening a web browser and going to: Copy https://localhost:9443 Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/start/install/server/setup) [PreviousInstall Portainer BE with Docker Swarm on WSL / Docker Desktop](https://docs.portainer.io/start/install/server/swarm/wsl) [NextPodman](https://docs.portainer.io/start/install/server/podman) Last updated 2 months ago Was this helpful? --- # Install Portainer BE on your Kubernetes environment | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/start/install-ce/server/kubernetes/baremetal) . [](https://docs.portainer.io/start/install/server/kubernetes/baremetal#introduction) Introduction ------------------------------------------------------------------------------------------------------ Portainer consists of two elements, the _Portainer Server_ and the _Portainer Agent_. Both elements run as lightweight containers on Kubernetes. To get started, you will need: * A working and up to date Kubernetes cluster. * Access to run `helm` or `kubectl` commands on your cluster. * Cluster Admin rights on your Kubernetes cluster. This is so Portainer can create the necessary `ServiceAccount` and `ClusterRoleBinding` for it to access the Kubernetes cluster. * A `default` StorageClass configured (see below). * A license key for Portainer Business Edition. The installation instructions also make the following assumptions about your environment: * Your environment meets [our requirements](https://docs.portainer.io/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. * Kubernetes RBAC is enabled and working (this is required for the access control functionality in Portainer). * You will be using the `portainer` namespace for Portainer. At present this is a requirement - other namespaces are currently unsupported. * Kubernetes' metrics server is installed and working (if you wish to use the metrics within Portainer). [](https://docs.portainer.io/start/install/server/kubernetes/baremetal#data-persistence) Data Persistence -------------------------------------------------------------------------------------------------------------- Portainer requires data persistence, and as a result needs at least one StorageClass available to use. Portainer will attempt to use the default StorageClass during deployment. If you do not have a StorageClass tagged as `default` the deployment will likely fail. We recommend using block storage for Kubernetes rather than network storage for the best performance and reliability, but do pay attention to the IOPS of your block storage devices when choosing the volume to use as some options are slower than others. You can check if you have a default StorageClass by running the following command on your cluster: Copy kubectl get sc and looking for a StorageClass with `(default)` after its name: Copy root@kubemaster01:~# kubectl get sc NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE ALLOWVOLUMEEXPANSION AGE managed-nfs-storage (default) k8s-sigs.io/nfs-subdir-external-provisioner Delete Immediate false 11d To set a StorageClass as default, you can use the following: Copy kubectl patch storageclass -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}' replacing `` with the name of your StorageClass. PowerShell interprets quotes differently. Use escaped quotes inside the JSON string like this: Copy kubectl patch storageclass -p '{\"metadata\": {\"annotations\":{\"storageclass.kubernetes.io/is-default-class\":\"true\"}}}' Alternatively, if you are installing using our Helm chart, you can pass the following parameter in your helm install command to specify the StorageClass to use for Portainer: Copy --set persistence.storageClass= In some Kubernetes clusters (for example microk8s), the default StorageClass simply creates hostPath volumes, which are not explicitly tied to a particular node. In a multi-node cluster, this can create an issue when the pod is terminated and rescheduled on a different node, "leaving" all the persistent data behind and starting the pod with an "empty" volume. While this behavior is inherently a limitation of using hostPath volumes, a suitable workaround is to use add a nodeSelector to the deployment, which effectively "pins" the Portainer pod to a particular node. You can do this by editing your own values.yaml file to set the nodeSelector value: `nodeSelector: kubernetes.io/hostname: \` or alternatively follow the instructions below for each deployment method. [](https://docs.portainer.io/start/install/server/kubernetes/baremetal#deployment) Deployment -------------------------------------------------------------------------------------------------- To deploy Portainer within a Kubernetes cluster you can use our provided Helm charts or YAML manifests. ### [](https://docs.portainer.io/start/install/server/kubernetes/baremetal#deploy-using-helm) Deploy using Helm Ensure you're using at least Helm v3.2, which includes support for the `--create-namespace` argument. First add the Portainer Helm repository by running the following commands: Copy helm repo add portainer https://portainer.github.io/k8s/ helm repo update Once the update completes, you're ready to begin the installation. Which method you choose will depend on how you wish to expose the Portainer service: Expose via NodePort Expose via Ingress Expose via Load Balancer Using the following command, Portainer will be available on port `30779` for HTTPS: Copy helm upgrade --install --create-namespace -n portainer portainer portainer/portainer \ --set enterpriseEdition.enabled=true \ --set enterpriseEdition.image.tag=lts \ --set tls.force=true By default, Portainer generates and uses a self-signed SSL certificate to secure port `30779`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) or [via the Portainer UI](https://docs.portainer.io/admin/settings#ssl-certificate) after installation is complete. If you need to access Portainer via HTTP on port `30777`, remove the `--set tls.force=true` option. In this example, Portainer will be deployed to your cluster and assigned a Cluster IP, with an nginx Ingress Controller at the defined hostname. For more on Ingress options, refer to the list of [Chart Configuration Options](https://docs.portainer.io/advanced/helm-chart-configuration-options) . Copy helm upgrade --install --create-namespace -n portainer portainer portainer/portainer \ --set enterpriseEdition.enabled=true \ --set enterpriseEdition.image.tag=lts \ --set service.type=ClusterIP \ --set tls.force=true \ --set ingress.enabled=true \ --set ingress.ingressClassName= \ --set ingress.annotations."nginx\.ingress\.kubernetes\.io/backend-protocol"=HTTPS \ --set ingress.hosts[0].host= \ --set ingress.hosts[0].paths[0].path="/" If you need to access Portainer via HTTP, remove the `--set tls.force=true` option. Using the following command, Portainer will be available at an assigned Load Balancer IP on port `9443` for HTTPS: Copy helm upgrade --install --create-namespace -n portainer portainer portainer/portainer \ --set service.type=LoadBalancer \ --set enterpriseEdition.enabled=true \ --set enterpriseEdition.image.tag=lts \ --set tls.force=true By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) or [via the Portainer UI](https://docs.portainer.io/admin/settings#ssl-certificate) after installation is complete. If you need to access Portainer via HTTP on port `9000`, remove the `--set tls.force=true` option. If you want to explicitly set the target node when deploying the Helm chart on the CLI, include `--set nodeSelector.kubernetes\.io/hostname=` in your `helm install` command. ### [](https://docs.portainer.io/start/install/server/kubernetes/baremetal#deploy-using-yaml-manifests) Deploy using YAML manifests Our YAML manifests support exposing Portainer via either NodePort or Load Balancer. Expose via NodePort Expose via Load Balancer To expose via NodePort, you can use the following command (Portainer will be available on port `30777` for HTTP and `30779` for HTTPS): Copy kubectl apply -n portainer -f https://downloads.portainer.io/ee-lts/portainer.yaml By default, Portainer generates and uses a self-signed SSL certificate to secure port `30779`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) or [via the Portainer UI](https://docs.portainer.io/admin/settings#ssl-certificate) after installation is complete. To expose via Load Balancer, use the following command to provision Portainer at an assigned Load Balancer IP on port `9000` for HTTP and `9443` for HTTPS: Copy kubectl apply -n portainer -f https://downloads.portainer.io/ee-lts/portainer-lb.yaml By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) or [via the Portainer UI](https://docs.portainer.io/admin/settings#ssl-certificate) after installation is complete. If you want to explicitly set the target node when deploying using YAML manifests, run the following one-liner to "patch" the deployment, forcing the pod to always be scheduled on the node it's currently running on: Copy kubectl patch deployments -n portainer portainer -p '{"spec": {"template": {"spec": {"nodeSelector": {"kubernetes.io/hostname": "'$(kubectl get pods -n portainer -o jsonpath='{ ..nodeName }')'"}}}}}' || (echo Failed to identify current node of portainer pod; exit 1) [](https://docs.portainer.io/start/install/server/kubernetes/baremetal#logging-in) Logging In -------------------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance. Depending on how you chose to expose your Portainer installation, open a web browser and navigate to the following URL: NodePort Ingress Load Balancer Copy https://localhost:30779/ or http://localhost:30777/ Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. Copy https:/// Replace `` with the FQDN of your Portainer instance. Copy https://:9443/ or http://:9000/ Replace `` with the IP address or FQDN of the load balancer, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/start/install/server/setup) [PreviousKubernetes](https://docs.portainer.io/start/install/server/kubernetes) [NextInstall Portainer BE with Kubernetes on WSL / Docker Desktop](https://docs.portainer.io/start/install/server/kubernetes/wsl) Last updated 1 month ago Was this helpful? --- # Install Portainer CE with Docker on Linux | Portainer Documentation These installation instructions are for Portainer Community Edition (CE). For Portainer Business Edition (BE) refer to the [BE install documentation](https://docs.portainer.io/start/install/server/docker/linux) . [](https://docs.portainer.io/start/install-ce/server/docker/linux#introduction) Introduction ------------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_, and the _Portainer Agent_. Both elements run as lightweight Docker containers on a Docker engine. This document will help you install the Portainer Server container on your Linux environment. To add a new Linux environment to an existing Portainer Server installation, please refer to the [Portainer Agent installation instructions](https://docs.portainer.io/admin/environments/add/docker/agent) . To get started, you will need: * The latest version of Docker installed and working. We recommend following the [official installation instructions](https://docs.docker.com/engine/install/) for Docker - in particular, we advise _against_ installing Docker via snap on Ubuntu distributions as you may run into compatibility issues. * sudo access on the machine that will host your Portainer Server instance * By default, Portainer Server will expose the UI over port `9443` and expose a TCP tunnel server over port `8000`. The latter is optional and is only required if you plan to use the Edge compute features with Edge agents. The installation instructions also make the following assumptions about your environment: * Your environment meets [our requirements](https://docs.portainer.io/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. * You are accessing Docker via Unix sockets. Alternatively, you can also connect via TCP. * SELinux is disabled on the machine running Docker. If you require SELinux, you will need to pass the `--privileged` flag to Docker when deploying Portainer. * Docker is running as root. Portainer with rootless Docker has some limitations, and requires additional configuration. [](https://docs.portainer.io/start/install-ce/server/docker/linux#deployment) Deployment --------------------------------------------------------------------------------------------- You can choose to deploy Portainer using `docker run` or via Docker Compose. docker run Docker Compose To install using `docker run`, first create the volume that Portainer Server will use to store its database: Copy docker volume create portainer_data Then, download and install the Portainer Server container: Copy docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:lts By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/advanced/ssl#using-your-own-ssl-certificate-on-docker-standalone) or [via the Portainer UI](https://docs.portainer.io/admin/settings#ssl-certificate) after installation is complete. If you require HTTP port `9000` open for legacy reasons, add the following to your `docker run` command: `-p 9000:9000` Portainer Server has now been installed. You can check to see whether the Portainer Server container has started by running `docker ps`: Copy root@server:~# docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 7963585688a9 portainer/portainer-ce:lts "/portainer" 8 seconds ago Up 8 seconds 0.0.0.0:8000->8000/tcp, [::]:8000->8000/tcp, 0.0.0.0:9443->9443/tcp, [::]:9443->9443/tcp, 9000/tcp portainer To install using Docker Compose, download the compose file using the following `curl` command: Copy curl -L https://downloads.portainer.io/ce-lts/portainer-compose.yaml -o portainer-compose.yaml Alternatively, create a `portainer-compose.yaml` file with the following contents: Copy services: portainer: container_name: portainer image: portainer/portainer-ce:lts restart: always volumes: - /var/run/docker.sock:/var/run/docker.sock - portainer_data:/data ports: - 9443:9443 - 8000:8000 # Remove if you do not intend to use Edge Agents volumes: portainer_data: name: portainer_data networks: default: name: portainer_network Once you have created or downloaded the compose file, you can deploy it with the following command: Copy docker compose -f portainer-compose.yaml up -d Docker Compose will create the necessary resources and deploy Portainer. You can check to see whether the Portainer Server container has started by running `docker ps`: Copy root@server:~# docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 7963585688a9 portainer/portainer-ce:lts "/portainer" 8 seconds ago Up 8 seconds 0.0.0.0:8000->8000/tcp, [::]:8000->8000/tcp, 0.0.0.0:9443->9443/tcp, [::]:9443->9443/tcp, 9000/tcp portainer [](https://docs.portainer.io/start/install-ce/server/docker/linux#logging-in) Logging In --------------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance by opening a web browser and going to: Copy https://localhost:9443 Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/start/install-ce/server/setup) [PreviousDocker Standalone](https://docs.portainer.io/start/install-ce/server/docker) [NextInstall Portainer CE with Docker on WSL / Docker Desktop](https://docs.portainer.io/start/install-ce/server/docker/wsl) Last updated 1 month ago Was this helpful? --- # Add a Nomad environment | 2.27 LTS | Portainer Documentation As of Portainer version 2.20.0, Nomad is no longer a supported platform by Portainer. [PreviousAdd an ACI environment](https://docs.portainer.io/2.27/admin/environments/add/aci) [NextProvision KaaS Cluster](https://docs.portainer.io/2.27/admin/environments/add/kaas) Was this helpful? --- # Add an ACI environment | 2.27 LTS | Portainer Documentation Before connecting to your Azure subscription, you need to create an Azure AD application. For more information on this please refer to the [official Microsoft documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-create-service-principal-portal) . The following ACI features are not currently supported: * ACI Persistent Storage * Private networks To add an ACI environment, from the menu expand **Environment-related**, click **Environments**, then click **Add environment**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FHEuwt08SZ1rBtbdRzD3O%2F2.22-environments-add.gif&width=768&dpr=4&quality=100&sign=e7836614&sv=2) Select **ACI** as your environment type and click **Start Wizard**. Enter the **environment details** using the table below as a guide. Field Overview Name Enter a name for your environment. Application ID Enter the application ID for the app you created in your Azure account. This can be found on the **Overview** page of your app within the Azure Portal. Tenant ID Enter the tenant ID for your app. This can be found on the **Overview** page of your app within the Azure Portal. Authentication Key Enter the client secret for your app. This can be created under **Certificates & secrets** within your application in the Azure Portal. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2F4Bfw69sWWbG6BtCeqWIP%2F2.15-aci_env.png&width=768&dpr=4&quality=100&sign=46036d20&sv=2) As an optional step you can expand the **More settings** section and categorize the environment by adding it to a [group](https://docs.portainer.io/2.27/admin/environments/groups) or [tagging](https://docs.portainer.io/2.27/admin/environments/tags) it for better searchability. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FpXbNGrbls2wibQlFFZRD%2F2.15-aci_more-settings.png&width=768&dpr=4&quality=100&sign=622d6b44&sv=2) When you're ready, click **Connect**. If you have other environments to configure click **Next** to proceed, otherwise click **Close** to return to the list of environments. [PreviousImport an existing Kubernetes environment](https://docs.portainer.io/2.27/admin/environments/add/kubernetes/import) [NextAdd a Nomad environment](https://docs.portainer.io/2.27/admin/environments/add/nomad) Was this helpful? --- # Provision KaaS Cluster | 2.27 LTS | Portainer Documentation Portainer supports the provisioning of new Kubernetes environments on select cloud providers directly from within the interface, allowing you to spin up a new cloud Kubernetes environment and deploy the Portainer Agent with a few clicks. This feature is only available in [Portainer Business Edition](https://www.portainer.io/business-upsell?from=kaas-provisioning) . To get started, from the menu expand **Environment-related**, click **Environments**, then click **Add environment**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FHEuwt08SZ1rBtbdRzD3O%2F2.22-environments-add.gif&width=768&dpr=4&quality=100&sign=e7836614&sv=2) From the wizard select the **Provision KaaS Cluster** option and click **Start Wizard**. Then, select your provider. We currently support the following providers: [](https://docs.portainer.io/2.27/admin/environments/add/kaas/civo) ![Cover](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2Fc9Cc1XyNbEjr38PdqKJc%2Fcard-civo-large.png&width=490&dpr=4&quality=100&sign=6cf8c28&sv=2) **Civo** Civo Kubernetes [](https://docs.portainer.io/2.27/admin/environments/add/kaas/linode) ![Cover](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FvSY8xiLfMpQLLrKJW7Kn%2Fakamai-logo-circle-tile.png&width=490&dpr=4&quality=100&sign=bed51d00&sv=2) **Akamai Connected Cloud** Linode Kubernetes Engine (LKE) [](https://docs.portainer.io/2.27/admin/environments/add/kaas/digitalocean) ![Cover](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FdmyMYRCKVmqbBjHrRreQ%2Fcard-digitalocean-large.png&width=490&dpr=4&quality=100&sign=f322b23e&sv=2) **DigitalOcean** DigitalOcean Kubernetes (DOKS) [](https://docs.portainer.io/2.27/admin/environments/add/kaas/gke) ![Cover](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FZj61benktVzNpAGENdH4%2Fcard-googlecloud-large.png&width=490&dpr=4&quality=100&sign=a04c26d2&sv=2) **Google Cloud** Google Kubernetes Engine (GKE) [](https://docs.portainer.io/2.27/admin/environments/add/kaas/eks) ![Cover](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FdSRcyp1sQvDWx77CkX0g%2Fcard-aws-large.png&width=490&dpr=4&quality=100&sign=9710d3b9&sv=2) **Amazon Web Services (AWS)** Elastic Kubernetes Service (EKS) [](https://docs.portainer.io/2.27/admin/environments/add/kaas/aks) ![Cover](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FOrt3nIx1Q5HHTWw8S5BY%2Fcard-azure-large.png&width=490&dpr=4&quality=100&sign=935c805c&sv=2) **Microsoft Azure** Azure Kubernetes Service (AKS) [PreviousAdd a Nomad environment](https://docs.portainer.io/2.27/admin/environments/add/nomad) [NextCivo](https://docs.portainer.io/2.27/admin/environments/add/kaas/civo) Was this helpful? --- # Civo | 2.27 LTS | Portainer Documentation Select the **Civo** option from the list of providers. If you haven't already provided your Civo API token you'll be asked to provide credential details. Provide a **name** for your credentials and paste your Civo API token into the **API key** field and click **Add credentials**. You can find more details on [setting up access to your Civo account](https://docs.portainer.io/2.27/admin/settings/credentials/civo) in the [shared credentials documentation](https://docs.portainer.io/2.27/admin/settings/credentials) . ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2F4R1jK3QIVxB2JvxJmDdk%2F2.21.2-kaas-create-civo-creds.png&width=768&dpr=4&quality=100&sign=ee4f71a7&sv=2) Once you have added your credentials (or if you already had them set up) select your cluster options from the fields below. Field/Option Overview Name Enter a name for your cluster. Credentials Select the set of credentials to use for the provision. Region Select the region to deploy your cluster in. Node size Select the size of the individual nodes in your cluster. Node count Enter the number of nodes to provision in your cluster. Network ID Select the network to add your cluster to. Kubernetes version Select the version of Kubernetes you want to deploy on your cluster. You can manually refresh the options available from Civo by clicking **Reload cluster details** in the **Actions** section. ### [](https://docs.portainer.io/2.27/admin/environments/add/kaas/civo#a-note-about-civo-versions) A note about Civo versions Civo clusters using Kubernetes version 1.27 or above on a node size of Extra Small may fail to complete provisioning as the compute resources are too limited for required workloads. Versions prior to 1.27 do not have this resource requirement, so can be used with the Extra Small node size. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FcZT4NtVOkcl51ne1b2Q5%2F2.21.2-kaas-create-civo-cluster.png&width=768&dpr=4&quality=100&sign=d07cb89f&sv=2) You can also expand the **More settings** section and set groups and tags for your environment now or you can do this later. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FRrebZXgHomMW2mvLuorJ%2F2.15-kaas-provision-moresettings.png&width=768&dpr=4&quality=100&sign=bae81fca&sv=2) Once you have made your selections, click **Provision environment** to begin the provision. If you have other environments to configure click **Next** to proceed, otherwise click **Close** to return to the list of environments where you will see the progress of your provision. [PreviousProvision KaaS Cluster](https://docs.portainer.io/2.27/admin/environments/add/kaas) [NextAkamai Connected Cloud](https://docs.portainer.io/2.27/admin/environments/add/kaas/linode) Was this helpful? --- # Google Cloud | 2.27 LTS | Portainer Documentation Select the **Google Cloud** option from the list of providers. If you haven't already configured credentials for Google Cloud you'll be asked to provide them now. Enter a **name** for your credentials then click **Upload file** and select your JSON private key. Once this is done, click **Save**. You can find more details on [setting up access to your Google Cloud account](https://docs.portainer.io/2.27/admin/settings/credentials/gke) in the [shared credentials documentation](https://docs.portainer.io/2.27/admin/settings/credentials) . ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FAQskQ7McX63yJP03KVMO%2F2.21.2-kaas-create-googlecloud-creds.png&width=768&dpr=4&quality=100&sign=f745956f&sv=2) Once you have added your credentials (or if you already had them set up) select your cluster options from the fields below. Field/Option Overview Name Enter a name for your cluster. Credentials Select the set of credentials to use for the provision. Region Select the region to deploy your cluster in. Node size Select the size of the individual nodes in your cluster. Node disk space (GB) Enter the amount of disk space to provision on each node. Node count Enter the number of nodes to provision in your cluster. Subnet Select the subnet to attach to the cluster. Kubernetes version Select the version of Kubernetes you want to deploy on your cluster You can manually refresh the options available from Google Cloud by clicking **Reload cluster details** under the **Actions** section. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2F2VmxF9bUHsmRRq2huNIo%2F2.21.2-kaas-create-googlecloud-cluster.png&width=768&dpr=4&quality=100&sign=d54b07d&sv=2) You can also expand the **More settings** section and set groups and tags for your environment now or you can do this later. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FRrebZXgHomMW2mvLuorJ%2F2.15-kaas-provision-moresettings.png&width=768&dpr=4&quality=100&sign=bae81fca&sv=2) Once you have made your selections, click **Provision environment** to begin the provision. If you have other environments to configure click **Next** to proceed, otherwise click **Close** to return to the list of environments where you will see the progress of your provision. [PreviousDigitalOcean](https://docs.portainer.io/2.27/admin/environments/add/kaas/digitalocean) [NextAWS](https://docs.portainer.io/2.27/admin/environments/add/kaas/eks) Was this helpful? --- # DigitalOcean | 2.27 LTS | Portainer Documentation Select the **DigitalOcean** option from the list of providers. If you haven't already provided your DigitalOcean API token you'll be asked to provide credentials. Provide a **name** for your credentials and paste your DigitalOcean API token into the **API key** field and click **Add credentials**. You can find more details on [setting up access to your DigitalOcean account](https://docs.portainer.io/2.27/admin/settings/credentials/digitalocean) in the [shared credentials documentation](https://docs.portainer.io/2.27/admin/settings/credentials) . ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FN2XeX6r6G1MYTgTJGQ39%2F2.21.2-kaas-create-digitalocean-creds.png&width=768&dpr=4&quality=100&sign=127de5bb&sv=2) Once you have added your credentials (or if you already had them set up) select your cluster options from the fields below. Field/Option Overview Name Enter a name for your cluster. Credentials Select the set of credentials to use for the provision. Region Select the region to deploy your cluster in. Node size Select the size of the individual nodes in your cluster. Node count Enter the number of nodes to provision in your cluster. Kubernetes version Select the version of Kubernetes you want to deploy on your cluster. You can manually refresh the options available from DigitalOcean by clicking **Reload cluster details** under the **Actions** section. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FoAp8sTcDqYzmWOZyr9Oa%2F2.21.2-kaas-create-digitalocean-cluster.png&width=768&dpr=4&quality=100&sign=d2de3029&sv=2) You can also expand the **More settings** section and set groups and tags for your environment now or you can do this later. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FRrebZXgHomMW2mvLuorJ%2F2.15-kaas-provision-moresettings.png&width=768&dpr=4&quality=100&sign=bae81fca&sv=2) Once you have made your selections, click **Provision environment** to begin the provision. If you have other environments to configure click **Next** to proceed, otherwise click **Close** to return to the list of environments where you will see the progress of your provision. [PreviousAkamai Connected Cloud](https://docs.portainer.io/2.27/admin/environments/add/kaas/linode) [NextGoogle Cloud](https://docs.portainer.io/2.27/admin/environments/add/kaas/gke) Was this helpful? --- # Akamai Connected Cloud | 2.27 LTS | Portainer Documentation Select the **Akamai Connected Cloud** option from the list of providers. If you haven't already provided your API token you'll be asked to provide credentials. Provide a **name** for your credentials and paste your API token into the **API key** field and click **Add credentials**. You can find more details on [setting up access to your Akamai account](https://docs.portainer.io/2.27/admin/settings/credentials/linode) in the [shared credentials documentation](https://docs.portainer.io/2.27/admin/settings/credentials) . ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FLLHdUnDAJVas4DCdSS2b%2F2.21.2-kaas-create-akamai-creds.png&width=768&dpr=4&quality=100&sign=a7d679ea&sv=2) Once you have added your credentials (or if you already had them set up) select your cluster options from the fields below. Field/Option Overview Name Enter a name for your cluster. Credentials Select the set of credentials to use for the provision. Region Select the region to deploy your cluster in. Node size Select the size of the individual nodes in your cluster. Node count Enter the number of nodes to provision in your cluster. Kubernetes version Select the version of Kubernetes you want to deploy on your cluster. You can manually refresh the options available from Akamai by clicking **Reload cluster details** under the **Actions** section. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2Fwh66mxzA83kTlmUjzHnl%2F2.21.2-kaas-create-akamai-cluster.png&width=768&dpr=4&quality=100&sign=687069e3&sv=2) You can also expand the **More settings** section and set groups and tags for your environment now or you can do this later. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FRrebZXgHomMW2mvLuorJ%2F2.15-kaas-provision-moresettings.png&width=768&dpr=4&quality=100&sign=bae81fca&sv=2) Once you have made your selections, click **Provision environment** to begin the provision. If you have other environments to configure click **Next** to proceed, otherwise click **Close** to return to the list of environments where you will see the progress of your provision. [PreviousCivo](https://docs.portainer.io/2.27/admin/environments/add/kaas/civo) [NextDigitalOcean](https://docs.portainer.io/2.27/admin/environments/add/kaas/digitalocean) Was this helpful? --- # AWS | 2.27 LTS | Portainer Documentation Select the **AWS** option from the list of providers. If you haven't already configured credentials for AWS you'll be asked to provide them now. Enter a **name** for your credentials then enter your **Access key ID** and **Secret access key**. Once this is done, click **Save**. You can find more details on [setting up access to your AWS account](https://docs.portainer.io/2.27/admin/settings/credentials/eks) in the [shared credentials documentation](https://docs.portainer.io/2.27/admin/settings/credentials) . ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FdlgE18SaKpcuhAAyYMXP%2F2.21.2-kaas-create-aws-creds.png&width=768&dpr=4&quality=100&sign=7eb628b1&sv=2) Once you have added your credentials (or if you already had them set up) select your cluster options from the fields below. Field/Option Overview Name Enter a name for your cluster. Credentials Select the set of credentials to use for the provision. Region Select the region to deploy your cluster in. AMI type Select the AMI type to use for your nodes. Instance type Select the instance type to use for your nodes. You will need to make sure that the instance type you choose is available in the region you choose or the provision will fail. Node disk size (GiB) Enter the amount of disk space to provision on each node. Node count Enter the number of nodes to provision in your cluster. Kubernetes version Select the version of Kubernetes you want to deploy on your cluster You can manually refresh the options available from AWS by clicking **Reload cluster details** under the **Actions** section. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FZ3NmNxEaLzHwQ3TtUx59%2F2.15-kaas-provision-eks.png&width=768&dpr=4&quality=100&sign=131e7978&sv=2) You can also expand the **More settings** section and set groups and tags for your environment now or you can do this later. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FRrebZXgHomMW2mvLuorJ%2F2.15-kaas-provision-moresettings.png&width=768&dpr=4&quality=100&sign=bae81fca&sv=2) Once you have made your selections, click **Provision environment** to begin the provision. If you have other environments to configure click **Next** to proceed, otherwise click **Close** to return to the list of environments where you will see the progress of your provision. [PreviousGoogle Cloud](https://docs.portainer.io/2.27/admin/environments/add/kaas/gke) [NextAzure](https://docs.portainer.io/2.27/admin/environments/add/kaas/aks) Was this helpful? --- # Azure | 2.27 LTS | Portainer Documentation Select the **Azure** option from the list of providers. If you haven't already configured credentials for Azure you'll be asked to provide them now. Enter a **name** for your credentials then enter your **Subscription ID**, **Tenant ID**, **Client ID** and **Client Secret**. Once this is done, click **Save**. You can find more details on [setting up access to your Azure account](https://docs.portainer.io/2.27/admin/settings/credentials/aks) in the [shared credentials documentation](https://docs.portainer.io/2.27/admin/settings/credentials) . ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2Fb23huoURA081bdz2lovO%2F2.21.2-kaas-create-azure-creds.png&width=768&dpr=4&quality=100&sign=5ab434e4&sv=2) Once you have added your credentials (or if you already had them set up) select your cluster options from the fields below. Field/Option Overview Name Enter a name for your cluster. Credentials Select the set of credentials to use for the provision. Region Select the region to deploy your cluster in. Resource group Select an existing resource group or add a new resource group for your cluster. Node pool name Enter a name for your node pool. Node size Select the size of the individual nodes in your cluster. Node count Enter the number of nodes to provision in your cluster. Availability zones Select the availability zones to use for your cluster. API server availability Select the uptime SLA you require for your cluster. DNS name prefix Enter the DNS name prefix to use with your cluster. You will use this to connect to the Kubernetes API when managing containers after creating the cluster. Kubernetes version Select the version of Kubernetes you want to deploy on your cluster You can manually refresh the options available from Azure by clicking **Reload cluster details** under the **Actions** section. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FzqQiJwITJyiiKHuq70Or%2F2.21.2-kaas-create-azure-cluster.png&width=768&dpr=4&quality=100&sign=f8cbdc4a&sv=2) You can also expand the **More settings** section and set groups and tags for your environment now or you can do this later. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FRrebZXgHomMW2mvLuorJ%2F2.15-kaas-provision-moresettings.png&width=768&dpr=4&quality=100&sign=bae81fca&sv=2) Once you have made your selections, click **Provision environment** to begin the provision. If you have other environments to configure click **Next** to proceed, otherwise click **Close** to return to the list of environments where you will see the progress of your provision. [PreviousAWS](https://docs.portainer.io/2.27/admin/environments/add/kaas/eks) [NextCreate a Kubernetes cluster](https://docs.portainer.io/2.27/admin/environments/add/kube-create) Was this helpful? --- # Create a Kubernetes cluster | 2.27 LTS | Portainer Documentation With Portainer Business Edition you can create a Kubernetes cluster on your existing infrastructure directly from the Portainer UI. Portainer connects to your infrastructure and deploy Kubernetes and the Portainer Agent. You can provide your credentials during the deployment or set them up ahead of time in [Shared credentials](https://docs.portainer.io/2.27/admin/settings/credentials) . At present, we support deploying Talos Kubernetes via Omni and MicroK8s via SSH: [Talos Kubernetes](https://docs.portainer.io/2.27/admin/environments/add/kube-create/omni) [MicroK8s](https://docs.portainer.io/2.27/admin/environments/add/kube-create/microk8s) [PreviousAzure](https://docs.portainer.io/2.27/admin/environments/add/kaas/aks) [NextTalos Kubernetes](https://docs.portainer.io/2.27/admin/environments/add/kube-create/omni) Was this helpful? --- # Talos Kubernetes | 2.27 LTS | Portainer Documentation [](https://docs.portainer.io/2.27/admin/environments/add/kube-create/omni#introduction) Introduction --------------------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_ and the _Portainer Agent_. Both elements run as lightweight containers on Kubernetes. This document will outline how to create a Talos Kubernetes cluster via Omni and install the Portainer Edge Agent. If you do not have a working Portainer Server instance yet, please refer to the [Portainer Server installation guide](https://docs.portainer.io/2.27/start/install/server/kubernetes/baremetal) first. [](https://docs.portainer.io/2.27/admin/environments/add/kube-create/omni#prerequisites) Prerequisites ----------------------------------------------------------------------------------------------------------- In order to connect to Omni and deploy a Talos Kubernetes cluster and the Portainer Edge Agent, you will need: * An installation of Omni. You can use the [SaaS option](https://www.siderolabs.com/platform/saas-for-kubernetes/) or alternatively [self-host](https://omni.siderolabs.com/how-to-guides/self_hosted) an Omni installation. Note that while we believe that self-hosted installations will work fine, we have not extensively tested them in this initial release of this feature. * A service account on your Omni installation for Portainer to use. This service account should have Admin access. You can learn more about how to create a service account in our [credentials documentation](https://docs.portainer.io/2.27/admin/settings/credentials/omni) . * Machines registered within your Omni installation to be used for your Talos cluster. Documentation on registering these machines can be found in [Sidero's documentation](https://omni.siderolabs.com/how-to-guides/registering-machines) . * The machines you intend to use for your Talos Kubernetes cluster must be able to communicate with the Portainer Server deployment on API port (by default `9443`) and the tunnel server port (by default `8000`). This is so that the Edge Agent that is deployed on the cluster can communicate with the Portainer server. [](https://docs.portainer.io/2.27/admin/environments/add/kube-create/omni#deployment) Deployment ----------------------------------------------------------------------------------------------------- To create your Talos Kubernetes cluster and deploy the Portainer Edge Agent to your machines, from the menu expand **Environment-related**, click **Environments**, then click **Add environment**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FHEuwt08SZ1rBtbdRzD3O%2F2.22-environments-add.gif&width=768&dpr=4&quality=100&sign=e7836614&sv=2) Select **Create a Kubernetes cluster** and click **Start wizard**, then ensure **Talos Kubernetes** is selected. If you have not yet [configured a set of credentials for your Omni installation](https://docs.portainer.io/2.27/admin/settings/credentials/omni) , you will be asked to provide them now. If you already have a credential set configured, you can skip to [cluster configuration](https://docs.portainer.io/2.27/admin/environments/add/kube-create/omni#configure-your-cluster) . ### [](https://docs.portainer.io/2.27/admin/environments/add/kube-create/omni#credential-details) Credential details Fill in the fields based on the table below: Field/Option Overview Credentials name Enter a name for this credential set. This is how it will be listed in Portainer. Endpoint URL Enter the endpoint URL of your Omni installation. This is generally the same URL you would be using to access the Omni web UI. Service account key Paste your service account key into this field. You can create a service account through the Omni web UI or using `omnictl`. You can find more information on how to do this in our [Omni credentials documentation](https://docs.portainer.io/2.27/admin/settings/credentials/omni) . ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2F7wjp7tKqoy2GwGKujHTn%2F2.26-environments-add-kube-create-omni-creds.png&width=768&dpr=4&quality=100&sign=cd4920ab&sv=2) Once you have entered your credentials click **Add credentials**. The credential set will be saved under the name you entered, and you will be taken to the cluster configuration. ### [](https://docs.portainer.io/2.27/admin/environments/add/kube-create/omni#configure-your-cluster) Configure your cluster Once you have a set of credentials configured, you can proceed to configuring your cluster. Enter a **Name** for your cluster and fill out the rest of the fields based on the tables below. #### [](https://docs.portainer.io/2.27/admin/environments/add/kube-create/omni#portainer-server-details) Portainer server details Here you can provide the details for Portainer so that the agent can be deployed once the cluster has been created. Note that the URLs here should be the URLs that Portainer is accessible on from the perspective of the machines in the cluster. Field/Option Overview Portainer API server URL The URL to your Portainer server. This should generally be pre-populated with the correct value. Portainer tunnel server address The address to the Portainer tunnel server. This should generally be pre-populated with the correct value. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FTbrpfQPNn9uuN7vtnT0E%2F2.26-environments-add-kube-create-omni-portainer.png&width=768&dpr=4&quality=100&sign=7f4aeb40&sv=2) #### [](https://docs.portainer.io/2.27/admin/environments/add/kube-create/omni#omni-cluster-summary) Omni cluster summary Here you can select the credentials to use to connect to Omni as well as the versions of Talos and Kubernetes to deploy. Field/Option Overview Credentials Select the set of Omni credentials to use from the dropdown. Talos version Select the version of Talos to deploy on your cluster machines. The options here may be limited by the machines you select later in the process. Kubernetes version Select the version of Kubernetes to install on your cluster machines. The options here may be restricted based on the version of Talos chosen above. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FPuqERarGg3amPvv5kBuv%2F2.26-environments-add-kube-create-omni-clustersummary.png&width=768&dpr=4&quality=100&sign=6ad874de&sv=2) #### [](https://docs.portainer.io/2.27/admin/environments/add/kube-create/omni#cluster-machines) Cluster machines Here you can specify the machines to use for your cluster. The dropdowns will display the list of available machines alongside any labels on each machine to help with identification. Field/Option Overview Control Plane Select the machine(s) to use as your control plane nodes. You will need to choose at least one, and an odd number of control plane nodes is recommended. Main worker pool Select the machine(s) to use as your worker nodes. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FbH2ORyPzuFU4pPH10NXR%2F2.26-environments-add-kube-create-omni-machines.png&width=768&dpr=4&quality=100&sign=2a465791&sv=2) Once you have selected machines here you can tweak the networking configuration for each machine individually if necessary by clicking the cog icon next to the individual machine. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FP39vpRXHoU3bOHAjZ5ET%2F2.26-environments-add-kube-create-omni-machines-customconfig-form.png&width=768&dpr=4&quality=100&sign=b0367fa2&sv=2) Machines that have had their networking configuration adjusted in this way will have an orange dot on the cog icon: ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FBlB5B8oGGGC44VZKuPkf%2F2.26-environments-add-kube-create-omni-machines-customconfig.png&width=768&dpr=4&quality=100&sign=1aacf1f9&sv=2) talos-w1e-4a0 has a modified network configuration whereas talos-y3d-vuj does not. #### [](https://docs.portainer.io/2.27/admin/environments/add/kube-create/omni#cluster-configuration-patch) Cluster Configuration patch This section allows you to apply a custom YAML configuration to your cluster if required. You can click **Cluster Configuration patch** to display the section and provide your YAML in the editor. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FjotnlPa3L1JN7oGEBfaY%2F2.26-environments-add-kube-create-omni-clusterpatch.png&width=768&dpr=4&quality=100&sign=236754cc&sv=2) #### [](https://docs.portainer.io/2.27/admin/environments/add/kube-create/omni#more-settings) More settings As an optional step you can expand the More settings section to customize the deployment further. Field/Option Overview Initial deployment This section lets you select a custom template to deploy after cluster creation. Stack Optionally enter a stack name for your initial deployment. Custom template Select the template to deploy from the dropdown. Metadata This section lets you specify metadata for the environment for use within Portainer. Group Select the group to add the environment to. Tags Select the tags to apply to your environment. These tags apply only to Portainer, and not to the cluster within Omni itself. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FA9pA13FoZRQxlNFcAjYD%2F2.26-environments-add-kube-create-omni-moresettings.png&width=768&dpr=4&quality=100&sign=59b1eb5e&sv=2) Once you have entered your cluster configuration details, click **Provision environment** to begin the provision. Portainer will start provisioning your cluster with the options you selected. If you have other environments to configure click **Next** to proceed, otherwise click **Close** to return to the list of environments. ### [](https://docs.portainer.io/2.27/admin/environments/add/kube-create/omni#provision-progress) Provision progress From the Environments page you will be able to see the progress of any running Kubernetes environment provisions. The status will be updated as the provision completes, and if the provision runs into problems an error will be displayed here. You can hover over the status or error for additional detail. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2Fkv2vtMy9GRVI6yBBVnah%2F2.26-environments-add-kube-create-omni-progress.png&width=768&dpr=4&quality=100&sign=4d76d88b&sv=2) Once the provision completes, you will be able to access the environment as you would any other Portainer-configured environment. [PreviousCreate a Kubernetes cluster](https://docs.portainer.io/2.27/admin/environments/add/kube-create) [NextMicroK8s](https://docs.portainer.io/2.27/admin/environments/add/kube-create/microk8s) Was this helpful? --- # MicroK8s | 2.27 LTS | Portainer Documentation [](https://docs.portainer.io/2.27/admin/environments/add/kube-create/microk8s#introduction) Introduction ------------------------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_ and the _Portainer Agent_. Both elements run as lightweight containers on Kubernetes. This document will outline how to connect Portainer to your existing infrastructure to deploy MicroK8s and install the Portainer Agent. If you do not have a working Portainer Server instance yet, please refer to the [Portainer Server installation guide](https://docs.portainer.io/2.27/start/install/server/kubernetes/baremetal) first. [](https://docs.portainer.io/2.27/admin/environments/add/kube-create/microk8s#prerequisites) Prerequisites --------------------------------------------------------------------------------------------------------------- In order to connect to and deploy MicroK8s and the Portainer Agent on your existing infrastructure, you will need: * One or more Linux-based machines on which MicroK8s will be deployed. We have primarily tested on Ubuntu 20.04 LTS but most comparable Linux distributions should work. These machines can be bare metal servers or virtual machines. * Root or passwordless sudo SSH access to the above machines on port `22`. This is needed in order to install MicroK8s. Portainer supports both password-based and key-based authentication. * The `snap` tool installed on the above machines. You can find installation instructions for most Linux distributions [at the Snapcraft website](https://snapcraft.io/docs/installing-snapd) . The `snap` tool is used to install MicroK8s and any selected addons. * Communication between the Portainer Server and the above machines, as well as communication between the individual machines in the cluster. This is to ensure the Portainer Server can reach the machines both for the initial installation and for communication with the Portainer Agent once the cluster is up and running, and so that the cluster nodes can communicate with each other. * For the standard installation, internet access (specifically to Docker Hub and registry.k8s.io) from the machines where MicroK8s will be deployed. If internet access is not available you can perform an offline installation, though there are some [prerequisite steps](https://docs.portainer.io/2.27/admin/environments/add/kube-create/microk8s/offline) that must be completed. In addition, operating offline may affect enabling of some addons. [](https://docs.portainer.io/2.27/admin/environments/add/kube-create/microk8s#what-to-expect) What to expect ----------------------------------------------------------------------------------------------------------------- By necessity, our MicroK8s deployment makes some configuration decisions for you. * The Portainer Agent is deployed using NodePort, on port `30778`. * There may be some configuration differences between versions of MicroK8s deployed. One notable difference is from version 1.25, if the `ingress` addon is installed an additional ingress named `nginx` is configured. This does not occur on version 1.24. We recommend referring to the [MicroK8s release notes](https://microk8s.io/docs/release-notes) for further detail. * The deployment does not configure any storage classes on your cluster (unless the `hostpath-storage` addon is installed, though this is not recommended for multiple node clusters). Due to the vast amount of potential storage class configurations, this is not something we currently provide automatically. We recommend configuring a storage class once provision completes. [](https://docs.portainer.io/2.27/admin/environments/add/kube-create/microk8s#deployment) Deployment --------------------------------------------------------------------------------------------------------- To create and deploy MicroK8s and the Portainer Agent to your machines, from the menu expand **Environment-related**, click **Environments**, then click **Add environment**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FHEuwt08SZ1rBtbdRzD3O%2F2.22-environments-add.gif&width=768&dpr=4&quality=100&sign=e7836614&sv=2) Select **Create a Kubernetes cluster** and click **Start wizard**, then select **MicroK8s**. If you have not yet [configured a set of SSH credentials](https://docs.portainer.io/2.27/admin/settings/credentials/ssh) , you will be asked to provide them now. If you already have a credential set configured, you can skip to [cluster configuration](https://docs.portainer.io/2.27/admin/environments/add/kube-create/microk8s#configure-your-cluster) . ### [](https://docs.portainer.io/2.27/admin/environments/add/kube-create/microk8s#add-ssh-credentials) Add SSH credentials Fill in the fields based on the table below: Field/Option Overview Credentials name Enter a name for this credential set. This is how it will be listed in Portainer. SSH username Enter the username for your SSH account. SSH password Enter the password for your SSH account. You can leave this field blank if you intend to use SSH key authentication. Use SSH key authentication Enable this toggle to use SSH key authentication instead of password authentication. SSH private key passphrase If your SSH private key is encrypted, provide the passphrase here. SSH private key Paste your SSH private key in this field. You can also choose to generate a new SSH key pair by clicking the **Generate new RSA SSH key pair** button, or upload an existing private key by clicking the **Upload SSH private key** button. You can find more detailed instructions for generating a new SSH key in our [SSH credentials documentation](https://docs.portainer.io/2.27/admin/settings/credentials/ssh#generate-a-new-key-pair) . ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FgYhVHXHkJHYgu8kgyIJO%2F2.26-environments-add-kube-create-microk8s-creds.png&width=768&dpr=4&quality=100&sign=c0934751&sv=2) Once you have entered your credentials click **Add credentials**. The credential set will be saved under the name you entered, and you will be taken to the [cluster configuration](https://docs.portainer.io/2.27/admin/environments/add/kube-create/microk8s#configure-your-cluster) . ### [](https://docs.portainer.io/2.27/admin/environments/add/kube-create/microk8s#configure-your-cluster) Configure your cluster Once you have a set of credentials configured, you can proceed to configuring your cluster. Fill out the fields based on the table below: Field/Option Overview Name Enter a name for your environment. This is how the environment will appear in Portainer. Credentials Select the set of SSH credentials to use from the dropdown. Control plane nodes Enter a comma-separated or line-separated list of the IP addresses for the machines that will be the **control plane nodes** for your cluster. You can also specify a range of IP addresses with a hyphen. Worker nodes Enter a comma-separated or line-separated list of the IP addresses for the machines that will be the **worker nodes** for your cluster. You can also specify a range of IP addresses with a hyphen. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FIeYjt1UzbHFh7AmITd6K%2F2.19-environments-create-microk8s-nodes.png&width=768&dpr=4&quality=100&sign=48eba5c8&sv=2) Once you have selected a credential set and entered the node IPs, you can click **Test connections** to ensure the credentials work for all the IP addresses and that they are reachable from the Portainer Server instance. If there are any issues connecting to the nodes they will be displayed. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FepnXOzM1UdXq7PoRpHBR%2F2.19-environments-create-microk8s-test.png&width=768&dpr=4&quality=100&sign=912dc181&sv=2) You can now proceed to configuring MicroK8s itself. Fill out the fields based on the table below: Field/Option Overview Kubernetes version Select the version of MicroK8s to deploy on your cluster. This field is disabled if **Offline install** is enabled. Offline install Enable this toggle if you are performing an installation on an environment that has no internet access. You must complete [pre-configuration of your nodes](https://docs.portainer.io/2.27/admin/environments/add/kube-create/microk8s/offline) for offline installation. Addons Optionally click the **Add addon** button to select one or more addons to deploy alongside the MicroK8s installation. You can also specify any arguments needed for each addon. This is disabled if **Offline install** is enabled. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FmIkmiyp1Oco3XylhQP5x%2F2.20.3-environments-add-k8s-create-version.png&width=768&dpr=4&quality=100&sign=f7ebe116&sv=2) As an optional step you can expand the **More settings** section to customize the deployment further. Field/Option Overview Custom Template Select a custom template to deploy on your cluster once the MicroK8s and Portainer Agent installations are complete. This is handy for pre-loading a new environment with your applications. The template will be deployed in the default namespace unless the template specifies a namespace to use. You can also set any variables the template requires. Group Select a [group](https://docs.portainer.io/2.27/admin/environments/groups) to add the new environment to once provisioning completes. Tags Select any [tags](https://docs.portainer.io/2.27/admin/environments/tags) to add to the environment. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FayudKdLsfzqwgKQCr40l%2F2.19-environments-create-microk8s-moresettings.png&width=768&dpr=4&quality=100&sign=40d2a550&sv=2) Once you have entered your cluster configuration details, click **Provision environment** to begin the provision. Portainer will start provisioning your cluster with the options you selected. If you have other environments to configure click **Next** to proceed, otherwise click **Close** to return to the list of environments. ### [](https://docs.portainer.io/2.27/admin/environments/add/kube-create/microk8s#provision-progress) Provision progress From the Environments page you will be able to see the progress of any running Kubernetes environment provisions. The status will be updated as the provision completes, and if the provision runs into problems an error will be displayed here. You can hover over the status or error for additional detail. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FUVm06lPZvNME1ofKh32r%2F2.18-environments-add-k8sinstall-creating.png&width=768&dpr=4&quality=100&sign=4b1f0861&sv=2) Once the provision completes, you will be able to access the environment as you would any other Portainer-configured environment. [PreviousTalos Kubernetes](https://docs.portainer.io/2.27/admin/environments/add/kube-create/omni) [NextOffline installation](https://docs.portainer.io/2.27/admin/environments/add/kube-create/microk8s/offline) Was this helpful? --- # Helm chart configuration options | 2.27 LTS | Portainer Documentation The following table lists the configurable parameters of the Portainer Helm chart and their default values. Find the values file under `deploy/helm/portainer/values.yaml`. Parameter Description Default `replicaCount` Number of Portainer service replicas (always set to 1). `1` `image.repository` Portainer Docker Hub repository. `portainer/portainer-ce` `image.tag` Tag for the Portainer image. `latest` `image.pullPolicy` Portainer image-pulling policy. `IfNotPresent` `imagePullSecrets` If the Portainer image needs to be in a private repository. `nil` `nodeSelector` Used to apply a nodeSelector to the deployment. `{}` `serviceAccount.annotations` Annotations to add to the service account. `null` `serviceAccount.name` The name of the service account to use. `portainer-sa-clusteradmin` `service.type` Service type for the main Portainer Service. Valid values: `ClusterIP`, `NodePort`, `LoadBalancer`. `LoadBalancer` `service.httpPort` HTTP port for accessing the Portainer web interface. `9000` `service.httpNodePort` Static NodePort for accessing the Portainer web interface. Specify only if the type is `NodePort`. `30777` `service.edgePort` TCP port for accessing Portainer Edge. `8000` `service.edgeNodePort` Static NodePort for accessing Portainer Edge. Specify only if the type is `NodePort`. `30776` `service.annotations` Annotations to add to the service. `{}` `ingress.enabled` Creates an ingress for Portainer. `false` `ingress.annotations` Annotations to add to the ingress. For example: `kubernetes.io/ingress.class: nginx` `{}` `ingress.hosts.host` URL for Portainer Web. For example, `portainer.example.io`. `nil` `ingress.hosts.paths.path` Path for the Portainer web interface. `/` `ingress.hosts.paths.port` Port for the Portainer web interface. `9000` `ingress.tls` TLS support on ingress. Must create a secret with TLS certificates in advance. `[]` `resources` Portainer resource requests and limits. `{}` `persistence.enabled` Whether or not to enable data persistence. `true` `persistence.existingClaim` Name of an existing PVC to use for data persistence. `nil` `persistence.size` Size of the PVC used for persistence. `10Gi` `persistence.annotations` Annotations to apply to PVC used for persistence. `{}` `persistence.storageClass` StorageClass to apply to PVC used for persistence. `default` `persistence.accessMode` AccessMode for persistence. `ReadWriteOnce` `persistence.selector` Selector for persistence. `nil` [PreviousHow Relative Path Support works in Portainer](https://docs.portainer.io/2.27/advanced/relative-paths) [NextDocker roles and permissions](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions) Was this helpful? --- # How Relative Path Support works in Portainer | 2.27 LTS | Portainer Documentation The relative path volumes support in Portainer Business Edition is intended to provide you with a way to reference files and directories that are supplied within the Git repository alongside your compose file without needing to know the absolute path at which they will appear when they are deployed to your environment. Relative path support is only present in Portainer Business Edition, and needs to be [enabled when deploying your stack from Git](https://docs.portainer.io/2.27/user/docker/stacks/add#relative-path-volumes) for this article to apply. In the background the way this works is as follows: 1. In Portainer, a stack deployment is initiated where the stack is located in a Git repository, **Enable relative path volumes** is selected and a **Local (or Network) filesystem path** is specified. 2. Portainer creates a temporary unpacker container that bind mounts the path specified in the Local (or Network) filesystem path field. 3. The unpacker container clones the Git repository to a subdirectory under the bind mounted path. 4. Portainer creates the stack using the compose file provided, specifying the working directory as where the specified compose file is located within where the Git repo was cloned. 5. Now that the stack has been deployed, the temporary unpacker container is removed. To take advantage of this with your compose file, you can specify any references to files that are within your repository in a _relative_ manner to your compose file. For example, imagine this simple nginx deployment: Copy . ├── docker-compose.yml └── static └── index.html In this example, the `docker-compose.yml` file is at the base directory of the repository. Alongside it there is a directory named `static`, and within that directory is an `index.html` file. The `docker-compose.yml` file looks like this: Copy version: '3.1' services: webapp: image: nginx:latest restart: always ports: - "3002:80" volumes: - ./static:/usr/share/nginx/html The last line is the important one here - you'll note that we're referencing the static directory with a leading `.` and `/` - this tells compose that the path specified is _relative_ to the working directory, which Portainer specified during deployment. If we excluded the leading `.` this would be an _absolute_ path, and would refer to `/static` at the root of the host filesystem. Let's look at an example where you had your compose file in a subdirectory of your repository, and your content in a different subdirectory: Copy . ├── nginx │ └── docker-compose.yml └── static └── index.html In this scenario, you would specify the compose file when deploying as `nginx/docker-compose.yml`. Portainer will pull the contents of the repository to the specified location and set the working directory to the location of the compose file (ie, within the `nginx` subdirectory). As such, relative references within the compose need to be aware of this. To mount the contents of the `static` directory, your compose file would look like: Copy version: '3.1' services: webapp: image: nginx:latest restart: always ports: - "3002:80" volumes: - ../static:/usr/share/nginx/html The double dots (`..`) indicate that the files are at a directory level above the working directory. ### [](https://docs.portainer.io/2.27/advanced/relative-paths#a-note-about-the-local-or-network-filesystem-path) A note about the local (or network) filesystem path The path on the local (or network) filesystem that the Git repository is cloned to will be in: Copy portainer-compose-unpacker/stacks/yourstackname/ For example, if you deployed a stack named `nginx` and specified the local filesystem path as: Copy /mnt/stacks/ it would result in: Copy /mnt/stacks/portainer-compose-unpacker/stacks/nginx/ This is generally not relevant for relative path referencing as the definition of the working directory avoids needing to be aware of this full path, but it does mean the same local (or network) filesystem path can be used to deploy multiple stacks without worrying about collisions (as long as they don't share the same stack name). This path is where your stack's mounted files will be sourced from, so you will want to ensure this path remains intact and unchanged. When a stack deployed with this method is removed, the file and directory structure for that stack are removed as well. [PreviousDeploying Portainer behind nginx reverse proxy](https://docs.portainer.io/2.27/advanced/reverse-proxy/nginx) [NextHelm chart configuration options](https://docs.portainer.io/2.27/advanced/helm-chart-configuration-options) Was this helpful? --- # Deprecated and removed features | 2.27 LTS | Portainer Documentation This table lists deprecated and removed features and functionality that are no longer supported and should not be used. The **Deprecated** column shows the release in which the feature was tagged as deprecated. The **Remove** column shows the release in which the feature was or will be removed (TBD means 'to be decided'). Feature Deprecated Remove `PUT /kubernetes/{id}/namespaces` API endpoint 2.25.0 TBD Nomad support 2.20.0 2.20.0 Enabling SSL via `--ssl` (now enabled by default) 2.9.0 TBD Disabling analytics via `--no-analytics` 2.0 TBD Kompose deployments 2.15.0 2.17.0 Specifying external environments in JSON via `--external-endpoints` 2.0 Setting time between environment synchronization requests via `--sync-interval` 2.0 Disabling Portainer internal authentication via `--no-auth` 2.0 Specifying a templates file to load on first run via `--templates-file` 2.0 Preventing Portainer from running a snapshot of environments via `--no-snapshot` 2.0 [PreviousKubernetes roles and bindings](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings) [NextAccessing the Portainer API](https://docs.portainer.io/2.27/api/access) Was this helpful? --- # API documentation | 2.27 LTS | Portainer Documentation Portainer exposes an HTTP API that you can use to automate everything you do via the Portainer UI. You can also use Portainer as a gateway (HTTP queries against the Portainer API) to the underlying Docker/Kubernetes API. You will need an access token in order to use the Portainer API. If you have not already set up an access token for the API, we have [instructions on how to do so](https://docs.portainer.io/2.27/api/access) . You can find our API documentation at SwaggerHub: * [Business Edition (BE) 2.27.9 API Documentation](https://app.swaggerhub.com/apis/portainer/portainer-ee/2.27.9) * [Community Edition (CE) 2.27.9 API Documentation](https://app.swaggerhub.com/apis/portainer/portainer-ce/2.27.9) We have also provided some examples of API usage. [API usage examples](https://docs.portainer.io/2.27/api/examples) [PreviousAccessing the Portainer API](https://docs.portainer.io/2.27/api/access) [NextAPI usage examples](https://docs.portainer.io/2.27/api/examples) Last updated 4 months ago Was this helpful? --- # Deploying Portainer behind nginx reverse proxy | 2.27 LTS | Portainer Documentation [](https://docs.portainer.io/2.27/advanced/reverse-proxy/nginx#deploying-in-a-docker-standalone-scenario) Deploying in a Docker Standalone scenario -------------------------------------------------------------------------------------------------------------------------------------------------------- To deploy Portainer behind an nginx proxy in a Docker standalone scenario you must use a Docker Compose file. In the following docker-compose.yml you will find the configuration of the nginx proxy and the Portainer Server. This example uses the excellent [nginxproxy/nginx-proxy](https://hub.docker.com/r/nginxproxy/nginx-proxy) image as the proxy container, which requires no additional configuration beyond the two environment variables added to the `portainer` container's definition. Business Edition Community Edition Copy version: "2" services: nginx-proxy: image: nginxproxy/nginx-proxy restart: always ports: - "80:80" volumes: - "/var/run/docker.sock:/tmp/docker.sock:ro" portainer: image: portainer/portainer-ee:lts command: -H unix:///var/run/docker.sock restart: always environment: - VIRTUAL_HOST=portainer.yourdomain.com - VIRTUAL_PORT=9000 ports: - 8000:8000 volumes: - /var/run/docker.sock:/var/run/docker.sock - portainer_data:/data volumes: portainer_data: Copy version: "2" services: nginx-proxy: image: nginxproxy/nginx-proxy restart: always ports: - "80:80" volumes: - "/var/run/docker.sock:/tmp/docker.sock:ro" portainer: image: portainer/portainer-ce:lts command: -H unix:///var/run/docker.sock restart: always environment: - VIRTUAL_HOST=portainer.yourdomain.com - VIRTUAL_PORT=9000 ports: - 8000:8000 volumes: - /var/run/docker.sock:/var/run/docker.sock - portainer_data:/data volumes: portainer_data: To start working with this recipe, change the `VIRTUAL_HOST` value then deploy Portainer by running the following: Copy docker-compose up -d When this has finished, run `docker ps` . You should see an output similar to this: Copy CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 8c8f2eac7c9a portainer/portainer-ee:lts "/portainer -H unix:…" 4 minutes ago Up 4 minutes 9000/tcp, 0.0.0.0:8000->8000/tcp, :::8000->8000/tcp, 9443/tcp portainer_portainer_1 3e7c8b5d71d7 nginxproxy/nginx-proxy "/app/docker-entrypo…" 4 minutes ago Up 4 minutes 0.0.0.0:80->80/tcp, :::80->80/tcp portainer_nginx-proxy_1 Once the deployment has finished you can browse `portainer.yourdomain.com`. [](https://docs.portainer.io/2.27/advanced/reverse-proxy/nginx#deploying-in-a-docker-swarm-scenario) Deploying in a Docker Swarm scenario ---------------------------------------------------------------------------------------------------------------------------------------------- Deploying Portainer in Docker Swarm behind nginx has similar steps to the Docker Standalone scenario. Before deploying, you need to create two elements: networks and volumes. This deployment assumes you are running one manager node. If you are using multiple managers we advise [reading this knowledge base article](https://portal.portainer.io/knowledge/how-can-i-ensure-portainers-configuration-is-retained) before proceeding. First, create two networks: * One for the agent and the communication with the Portainer Server. * One to 'expose' the Portainer container to the same network as the reverse proxy. Copy docker network create -d overlay proxy Copy docker network create -d overlay agent_network Next, create the volume: Copy docker volume create portainer_data And finally, save the following recipe as `portainer.yml`: Business Edition Community Edition Copy version: '3.2' services: nginx-proxy: image: nginxproxy/nginx-proxy networks: - proxy ports: - "80:80" volumes: - "/var/run/docker.sock:/tmp/docker.sock:ro" - "./vhost.d:/etc/nginx/vhost.d:ro" agent: image: portainer/agent:lts environment: # REQUIRED: Should be equal to the service name prefixed by "tasks." when # deployed inside an overlay network AGENT_CLUSTER_ADDR: tasks.agent # AGENT_PORT: 9001 # LOG_LEVEL: DEBUG volumes: - /var/run/docker.sock:/var/run/docker.sock - /var/lib/docker/volumes:/var/lib/docker/volumes networks: - agent_network deploy: mode: global placement: constraints: [node.platform.os == linux] portainer: image: portainer/portainer-ee:lts command: -H tcp://tasks.agent:9001 --tlsskipverify volumes: - data:/data environment: - VIRTUAL_HOST=portainer.yourdomain.com - VIRTUAL_PORT=9000 ports: - 8000:8000 networks: - proxy - agent_network deploy: mode: replicated replicas: 1 placement: constraints: [node.role == manager] networks: proxy: external: true agent_network: external: true volumes: data: Copy version: '3.2' services: nginx-proxy: image: nginxproxy/nginx-proxy networks: - proxy ports: - "80:80" volumes: - "/var/run/docker.sock:/tmp/docker.sock:ro" - "./vhost.d:/etc/nginx/vhost.d:ro" agent: image: portainer/agent:lts environment: # REQUIRED: Should be equal to the service name prefixed by "tasks." when # deployed inside an overlay network AGENT_CLUSTER_ADDR: tasks.agent # AGENT_PORT: 9001 # LOG_LEVEL: DEBUG volumes: - /var/run/docker.sock:/var/run/docker.sock - /var/lib/docker/volumes:/var/lib/docker/volumes networks: - agent_network deploy: mode: global placement: constraints: [node.platform.os == linux] portainer: image: portainer/portainer-ce:lts command: -H tcp://tasks.agent:9001 --tlsskipverify volumes: - data:/data environment: - VIRTUAL_HOST=portainer.yourdomain.com - VIRTUAL_PORT=9000 ports: - 8000:8000 networks: - proxy - agent_network deploy: mode: replicated replicas: 1 placement: constraints: [node.role == manager] networks: proxy: external: true agent_network: external: true volumes: data: To start working with this recipe, change the `VIRTUAL_HOST` value then deploy Portainer by running the following: Copy docker stack deploy portainer -c portainer.yml To check the deployment, run `docker service ls`. You should see an output similar to the following: Copy ID NAME MODE REPLICAS IMAGE PORTS gy2bjxid0g4p portainer_agent global 1/1 portainer/agent:lts jwvjp5bux4sz portainer_nginx-proxy replicated 1/1 nginxproxy/nginx-proxy:latest *:80->80/tcp 5nflcvoxl3c7 portainer_portainer replicated 1/1 portainer/portainer-ee:lts *:8000->8000/tcp Once the services are running, you will be able to access Portainer from the URL you defined earlier, for example: `portainer.yourdomain.com`. [PreviousDeploying Portainer behind Traefik Proxy](https://docs.portainer.io/2.27/advanced/reverse-proxy/traefik) [NextHow Relative Path Support works in Portainer](https://docs.portainer.io/2.27/advanced/relative-paths) Last updated 8 months ago Was this helpful? --- # Accessing the Portainer API | 2.27 LTS | Portainer Documentation To access the Portainer API, you will need a few things: * A user in Portainer * An access token for that user * The ability to make HTTPS requests to the Portainer server on port `9443` (or `9000` for legacy HTTP) [](https://docs.portainer.io/2.27/api/access#creating-a-new-user) Creating a new user ------------------------------------------------------------------------------------------ API access is provided on a per-user basis, with each users' API access dependent on that user's permissions within Portainer. For example, if your user had access to only one environment, API calls for that user would also be restricted to that environment. To create a new user within Portainer, refer to our documentation: [Add a new user](https://docs.portainer.io/2.27/admin/user/add) Once the user has been created, log in to Portainer as that user to create an API access token. [](https://docs.portainer.io/2.27/api/access#creating-an-access-token) Creating an access token ---------------------------------------------------------------------------------------------------- Once the user has been created, you can add an access token to that user. The access token will provide the same level of access to Portainer functionality as would be available to that user had they logged into the Portainer UI. Once logged in as the user, click on your username in the top right and then select **My account**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FWrGUJiPWTAbcQPuBrW4B%2F2.20-api-access-myaccount.gif&width=768&dpr=4&quality=100&sign=1bf19fe2&sv=2) Scroll down to the **Access tokens** section. Here you can see any access tokens that exist for the user. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FyZSXpFqBgcB6TuPb9dkb%2F2.15-accountsettings-apitokens.png&width=768&dpr=4&quality=100&sign=36bda9fd&sv=2) To add a new access token, click the **Add access token** button. You will be taken to a new page where you can set a **Description** for your access token. We recommend making this something recognizable for future reference. For security we require you to re-enter your password when creating an access token. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2Fv5Sep4K5CnElpEY1SpKq%2F2.20-api-access-createtoken.png&width=768&dpr=4&quality=100&sign=e830e92a&sv=2) Once you have provided a description, click the **Add access token** button to generate your access token. Your new access token will now be displayed. Please copy the access token and keep it in a safe place, as you will not be able to view the token again after creation. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2F3roAECKwSfowCXNw8RZR%2Fblobs%2FxKD0dQIDxoSD0Nfbq4cZ%2F2.20-api-access-createdtoken.png&width=768&dpr=4&quality=100&sign=63a7b9b0&sv=2) When you have copied the access token, click the **Done** button to return to the User settings page. Your access token is ready to use. [](https://docs.portainer.io/2.27/api/access#using-your-access-token) Using your access token -------------------------------------------------------------------------------------------------- Now that you have created a user and access token, you are ready to access the API. The Portainer API follows the RESTful architecture, accepting `GET` / `POST` / `PUT` / `DELETE` requests and responding with JSON objects. The following examples use [httpie](https://httpie.org/) to execute API calls against Portainer. Feel free to replace this with your method of choice. To make an API request, you will need to include your access token in the `X-API-Key` header to authenticate your request. For example, you can use the `/stacks` endpoint to list the stacks you have access to: Copy http GET https://portainer-url:9443/api/stacks X-API-Key:your_api_key_here This will return a JSON object listing your stacks: Copy [\ {\ "AdditionalFiles": null,\ "AutoUpdate": null,\ "CreatedBy": "admin",\ "CreationDate": 1631852794,\ "EndpointId": 4,\ "EntryPoint": "docker-compose.yml",\ "Env": null,\ "GitConfig": {\ "Authentication": null,\ "ConfigFilePath": "docker-compose.yml",\ "ConfigHash": "2e71920bf1ee1bbac976d320f8f274411fba3bad",\ "ReferenceName": "refs/heads/master",\ "URL": "https://github.com/mygithubaccount/wordpress-stack"\ },\ "Id": 5,\ "IsComposeFormat": true,\ "Name": "",\ "Namespace": "my-namespace",\ "ProjectPath": "/data/compose/5",\ "ResourceControl": null,\ "Status": 1,\ "SwarmId": "",\ "Type": 3,\ "UpdateDate": 0,\ "UpdatedBy": ""\ },\ ] If a user tries to access an area they do not have permission to access, an error message will be returned. For example, assume that a non-administrator user attempted to access the `/settings` endpoint, which requires administrator access: Copy http GET https://portainer:9443/api/settings X-API-Key:your_api_key_here The user would be presented with the following response: Copy { "details": "Unauthorized", "message": "Access denied" } Now that you have access to the Portainer API, you can learn more about how to use it from the [API documentation](https://docs.portainer.io/2.27/api/docs) and our [usage examples](https://docs.portainer.io/2.27/api/examples) . [PreviousDeprecated and removed features](https://docs.portainer.io/2.27/advanced/deprecated) [NextAPI documentation](https://docs.portainer.io/2.27/api/docs) Was this helpful? --- # API usage examples | 2.27 LTS | Portainer Documentation Portainer exposes an HTTP API that you can use to automate everything you do via the Portainer UI. You can also use Portainer as a gateway (HTTP queries against the Portainer API) to the underlying Docker/Kubernetes API. The following examples use [httpie](https://httpie.org/) to execute API calls against Portainer. [](https://docs.portainer.io/2.27/api/examples#initialize-the-admin-password) Initialize the admin password ---------------------------------------------------------------------------------------------------------------- On a fresh install of Portainer, you need to create an admin account to initialize Portainer. You will be asked for this when you visit the Portainer URL for the first time. You can achieve the same outcome using this API call: Copy http POST /api/users/admin/init Username="" Password="" [](https://docs.portainer.io/2.27/api/examples#authenticate-against-the-api-using-the-admin-account) Authenticate against the API using the admin account -------------------------------------------------------------------------------------------------------------------------------------------------------------- Copy http POST /api/auth Username="" Password="" The response is a JSON object containing the JWT token inside the `jwt` field. You will need to pass this token inside the authorization header when executing an authentication query against the API. Copy { "jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGUiOjEsImV4cCI6MTQ5OTM3NjE1NH0.NJ6vE8FY1WG6jsRQzfMqeatJ4vh2TWAeeYfDhP71YEE" } The value of the authorization header must be of the form `Bearer `: Copy Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGUiOjEsImV4cCI6MTQ5OTM3NjE1NH0.NJ6vE8FY1WG6jsRQzfMqeatJ4vh2TWAeeYfDhP71YEE This token is valid for 8 hours. Once it expires, you will need to generate another token to execute authenticated queries. [](https://docs.portainer.io/2.27/api/examples#adding-a-new-environment) Adding a new environment ------------------------------------------------------------------------------------------------------ On a fresh install, Portainer has no environments configured. You will first need to add an environment for Portainer to manage. You can add an environment to manage [via the Portainer API](https://docs.portainer.io/2.27/admin/environments/add/api) , or via the web interface both during the initial setup and after setup is complete. [](https://docs.portainer.io/2.27/api/examples#execute-docker-queries-against-a-specific-environment) Execute Docker queries against a specific environment ---------------------------------------------------------------------------------------------------------------------------------------------------------------- The Portainer HTTP API endpoint acts as a reverse-proxy to the Docker HTTP API and can be used to execute any of the Docker HTTP API requests: `/api/endpoints//docker` Read [Docker's API documentation](https://docs.docker.com/engine/api/) to learn how to query the Docker Engine. ### [](https://docs.portainer.io/2.27/api/examples#list-all-containers) **List all containers** This call lists all of the containers available in a specific environment: Copy http GET /api/endpoints/1/docker/containers/json \ X-API-Key:your_access-token \ all==true The response is identical to that returned by the `ContainerList` operation of the Docker API. See [Docker's documentation about this operation](https://docs.docker.com/engine/api/v1.41/#operation/ContainerList) . ### [](https://docs.portainer.io/2.27/api/examples#create-a-container) **Create a container** You can create a container in a specific environment using the Portainer HTTP API as a gateway. The following query will create a new Docker container inside the environment using ID 1. The container will be named `web01` and will use the `nginx:latest` Docker image. It will publish container port `80` on port `8080` on the host. Copy http POST /api/endpoints/1/docker/containers/create \ X-API-Key:your_access-token \ name=="web01" Image="nginx:latest" \ ExposedPorts:='{ "80/tcp": {} }' \ HostConfig:='{ "PortBindings": { "80/tcp": [{ "HostPort": "8080" }] } }' The response is identical to that returned by the `ContainerCreate` operation of the Docker API. See [Docker's documentation about this operation](https://docs.docker.com/engine/api/v1.41/#operation/ContainerCreate) . Here is an example response: Copy { "Id": "5fc2a93d7a3d426a1c3937436697fc5e5343cc375226f6110283200bede3b107", "Warnings": null } You will need the container ID in order to execute actions against that container. ### [](https://docs.portainer.io/2.27/api/examples#start-a-container) **Start a container** Using the ID you retrieved previously, you can start your new container using this endpoint: `/api/endpoints//docker/containers//start` Copy http POST /api/endpoints/1/docker/containers/5fc2a93d7a3d426a1c3937436697fc5e5343cc375226f6110283200bede3b107/start \ X-API-Key:your_access-token The response is identical to that returned by the `ContainerStart` operation of the Docker API. See [Docker's documentation about this operation](https://docs.docker.com/engine/api/v1.41/#operation/ContainerStart) . ### [](https://docs.portainer.io/2.27/api/examples#delete-a-container) **Delete a container** You can create a container using the endpoint `/api/endpoints//docker/containers/`: Copy http DELETE /api/endpoints/1/docker/containers/5fc2a93d7a3d426a1c3937436697fc5e5343cc375226f6110283200bede3b107 \ X-API-Key:your_access-token \ force==true The response is identical to that returned by the `ContainerDelete` operation of the Docker API. See [Docker's documentation about this operation](https://docs.docker.com/engine/api/v1.41/#operation/ContainerDelete) . [PreviousAPI documentation](https://docs.portainer.io/2.27/api/docs) [NextContribute](https://docs.portainer.io/2.27/contribute/contribute) Was this helpful? --- # Build instructions | 2.27 LTS | Portainer Documentation This article explains how to set up your local development environment so you can contribute to the Portainer codebase. Make sure you have installed the dependencies for this project on your [Mac](https://docs.portainer.io/2.27/contribute/build/mac) or [Linux](https://docs.portainer.io/2.27/contribute/build/linux) machine before continuing. Windows is currently not supported by the Portainer development environment. [](https://docs.portainer.io/2.27/contribute/build#instructions) Instructions ---------------------------------------------------------------------------------- Navigate to the folder where you will store Portainer project code. This can be anywhere such as on your desktop or in your downloads folder. Now, download the Portainer project: Copy git clone https://github.com/portainer/portainer.git Next, navigate into the Portainer project you downloaded: Copy cd portainer Install the development dependencies: Copy make deps And finally, build and run the project: Copy make dev You should now be able to access Portainer at `https://localhost:9443` and UI dev server runs on `http://localhost:8999`. For additional commands, run `make help`. The frontend application will update and refresh when you save your changes to any of the sources. [](https://docs.portainer.io/2.27/contribute/build#contribution-guidelines) Contribution Guidelines -------------------------------------------------------------------------------------------------------- When contributing to the Portainer codebase, please follow [our contribution guidelines](https://github.com/portainer/portainer/blob/develop/CONTRIBUTING.md) . [PreviousContribute](https://docs.portainer.io/2.27/contribute/contribute) [NextSet up a macOS build environment](https://docs.portainer.io/2.27/contribute/build/mac) Was this helpful? --- # Contribute | 2.27 LTS | Portainer Documentation [](https://docs.portainer.io/2.27/contribute/contribute#reporting-bugs) Reporting bugs ------------------------------------------------------------------------------------------- If you find a bug, please tell us so we can triage it. All bugs are managed in this [GitHub repo](https://github.com/portainer/portainer/issues/new?assignees=&labels=bug%2Fneed-confirmation%2C+kind%2Fbug&template=Bug_report.md&title=) . When you click through, our template makes it easy to record all of the details. Before you report a bug, please check our list of [open bugs](https://github.com/portainer/portainer/labels/kind%2Fbug) in case someone else has already reported it. [This knowledge base article](https://portal.portainer.io/knowledge/how-do-you-decide-which-bugs-and-features-to-work-on-first) covers how we prioritize bug fixes. [](https://docs.portainer.io/2.27/contribute/contribute#feature-requests) Feature requests ----------------------------------------------------------------------------------------------- You can request new features by posting an Idea in our [GitHub Discussions](https://github.com/orgs/portainer/discussions/categories/ideas) forum. Please check to see if someone has already requested the feature you want, and give it an upvote if so. Learn how we prioritize feature development [in this knowledge base article](https://portal.portainer.io/knowledge/how-do-you-decide-which-bugs-and-features-to-work-on-first) . [](https://docs.portainer.io/2.27/contribute/contribute#contributing-to-the-portainer-ce-codebase) Contributing to the Portainer CE codebase ------------------------------------------------------------------------------------------------------------------------------------------------- The Portainer CE codebase is available in [GitHub](https://github.com/portainer/portainer) . Please follow our build instructions and [contribution guidelines](https://github.com/portainer/portainer/blob/develop/CONTRIBUTING.md) when making a contribution. [PreviousAPI usage examples](https://docs.portainer.io/2.27/api/examples) [NextBuild instructions](https://docs.portainer.io/2.27/contribute/build) Was this helpful? --- # Kubernetes roles and bindings | 2.27 LTS | Portainer Documentation Role-Based Access Control is only available in Portainer Business Edition. When managing a Kubernetes environment with Portainer, the Role-Based Access Control (RBAC) configuration is based on two components: * Kubernetes' cluster roles and namespace roles (which restrict access to Kubernetes itself) * Portainer's authorization flags (which [restrict access](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#portainer-access-restrictions) to Portainer's functionality) The following tables provide a reference for how our Portainer roles map to capabilities within Kubernetes. [](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#role-allocations) Role Allocations ---------------------------------------------------------------------------------------------------------------- Portainer Role Cluster Role Binding Namespace Role Binding Environment Administrator cluster-admin (k8s system) N/A Operator [portainer-operator](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#portainer-operator) , [portainer-helpdesk](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#portainer-helpdesk) [portainer-view](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#portainer-view) (all non-system namespaces) User [portainer-basic](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#portainer-basic) [portainer-edit](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#portainer-edit) , [portainer-view](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#portainer-view) (only assigned namespaces) Helpdesk [portainer-helpdesk](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#portainer-helpdesk) [portainer-view](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#portainer-view) (all non-system namespaces) Read-Only [portainer-basic](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#portainer-basic) [portainer-view](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#portainer-view) (only assigned namespaces) [](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#cluster-roles) Cluster Roles ---------------------------------------------------------------------------------------------------------- ### [](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#portainer-basic) portainer-basic API Group Resources Verbs (Empty) namespaces, nodes get, list storage.k8s.io storageclasses list metrics.k8s.io namespaces, pods, nodes get, list networking.k8s.io ingressclasses list ### [](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#portainer-helpdesk) portainer-helpdesk API Group Resources Verbs (Empty) componentstatuses, endpoints, events, namespaces, nodes get, list, watch storage.k8s.io storageclasses get, list, watch networking.k8s.io ingresses get, watch networking.k8s.io ingressclasses list metrics.k8s.io pods, nodes, nodes/stats, namespace get, list, watch ### [](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#portainer-operator) portainer-operator API Group Resources Verbs (Empty) configmaps update (Empty) pods delete apps daemonsets, deployments, statefulsets patch metrics.k8s.io pods, nodes, nodes/stats, namespaces get, list, watch [](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#namespace-roles) Namespace Roles -------------------------------------------------------------------------------------------------------------- ### [](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#portainer-edit) portainer-edit API Group Resources Verbs (Empty) configmaps, endpoints, persistentvolumeclaims, pods, pods/attach, pods/exec, pods/portforward, pods/proxy, replicationcontrollers, replicationcontrollers/scale, secrets, serviceaccounts, services, services/proxy create, delete, deletecollection, patch, update (Empty) pods/attach, pods/exec, pods/portforward, pods/proxy, secrets, services/proxy get, list, watch apps daemonsets, deployments, deployments/rollback, deployments/scale, replicasets, replicasets/scale, statefulsets, statefulsets/scale create, delete, deletecollection, patch, update autoscaling horizontalpodautoscalers create, delete, deletecollection, patch, update batch cronjobs, jobs create, delete, deletecollection, patch, update extensions daemonsets, deployments, deployments/rollback, deployments/scale, ingresses, networkpolicies, replicasets, replicasets/scale, replicationcontrollers/scale create, delete, deletecollection, patch, update networking.k8s.io ingresses, networkpolicies create, delete, deletecollection, patch, update policy poddisruptionbudgets create, delete, deletecollection, patch, update ### [](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#portainer-view) portainer-view API Group Resources Verbs (Empty) bindings, componentstatuses, configmaps, endpoints, events, limitranges, namespaces, namespaces/status, persistentvolumeclaims, persistentvolumeclaims/status, pods, pods/log, pods/status, replicationcontrollers, replicationcontrollers/scale, replicationcontrollers/status, resourcequotas, resourcequotas/status, secrets, serviceaccounts, services, services/status get, list, watch apps controllerrevisions, daemonsets, daemonsets/status, deployments, deployments/scale, deployments/status, replicasets, replicasets/scale, replicasets/status, statefulsets, statefulsets/scale, statefulsets/status get, list, watch autoscaling horizontalpodautoscalers, horizontalpodautoscalers/status get, list, watch batch cronjobs, cronjobs/status, jobs, jobs/status get, list, watch extensions daemonsets, daemonsets/status, deployments, deployments/scale, deployments/status, ingresses, ingresses/status, networkpolicies, replicasets, replicasets/scale, replicasets/status, replicationcontrollers/scale get, list, watch networking.k8s.io ingresses, ingresses/status, networkpolicies get, list, watch policy poddisruptionbudgets, poddisruptionbudgets/status get, list, watch [](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#portainer-access-restrictions) Portainer Access Restrictions ------------------------------------------------------------------------------------------------------------------------------------------ Function Endpoint admin Operator Helpdesk Standard User Read-only User Namespace Scope All All, EXCEPT System All, EXCEPT System Default + Assigned Default + Assigned Namespaces RW R R R R Namespace Details RW R R R R Namespace Access Management RW Applications RW R R RW R Application Details RW R R RW R Pod Delete Yes Yes Application Console RW RW Advanced Deployment RW RW ConfigMaps & Secrets RW R R RW R ConfigMap & Secret Details RW RW R RW R Volumes RW R R RW R Volume Details RW R R RW R Cluster RW R R Cluster Node View RW R R Cluster Setup RW Application Error Details R R R Storage Class Disabled R R R [](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#community-edition) Community Edition ------------------------------------------------------------------------------------------------------------------ The following tables cover the two roles available in Portainer Community Edition (CE). Note there is no Portainer access restriction in Portainer CE. Portainer Role Cluster Role Binding Namespace Role Binding Admin (no restriction) (no restriction) User [portainer-cr-user](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#portainer-cr-user) edit (default k8s role, only assigned namespaces) ### [](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings#portainer-cr-user) portainer-cr-user API Group Resources Verbs (Empty) namespaces, nodes list storage.k8s.io storageclasses list networking.k8s.io ingresses list [PreviousDocker roles and permissions](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions) [NextDeprecated and removed features](https://docs.portainer.io/2.27/advanced/deprecated) Was this helpful? --- # Privacy Policy | 2.27 LTS | Portainer Documentation You can find our privacy policy [on our website](https://www.portainer.io/legal/privacy-policy) . [PreviousSet up a Linux build environment](https://docs.portainer.io/2.27/contribute/build/linux) Last updated 3 months ago Was this helpful? --- # Set up a macOS build environment | 2.27 LTS | Portainer Documentation As an open source product, we encourage users to edit our code and submit patches to it. This article explains how to set up a local environment on Mac so you can build your own copy of Portainer and test your changes. We tested these instructions on macOS 10.14.3 (Mojave). [](https://docs.portainer.io/2.27/contribute/build/mac#dependencies) Dependencies -------------------------------------------------------------------------------------- * [Docker for Mac](https://www.docker.com/products/docker-desktop) installs the Docker application and other Docker tools. The latest version is not a requirement for this development stack, however we recommend staying up to date with the latest improvements and security fixes. * [Yarn](https://yarnpkg.com/en/docs/install#mac-stable) is a package manager for installing new software packages on your system, and is used to run the Portainer development environment. * [Node.JS](https://nodejs.org/en/download/) is a JavaScript package used when building applications that leverage networking, such as Portainer. Version 18 or later is required. * ​[Golang](https://golang.org/dl/) is the open source language that we use to build the majority of Portainer software. Version 1.18 of Golang is required. * Wget is a package used to retrieve files using common internet protocols such as HTTP and FTP. [](https://docs.portainer.io/2.27/contribute/build/mac#part-1-installing-docker-for-macos) Part 1: Installing Docker for macOS ----------------------------------------------------------------------------------------------------------------------------------- Docker for macOS requires OSX Mountain Lion or later or it will not work. Please check that you have the right version before you begin. ### [](https://docs.portainer.io/2.27/contribute/build/mac#step-1-install-docker) Step 1: Install Docker We always recommend installing software using the most up-to-date instructions from the official vendor. This step is based on Docker's own [installation instructions for Docker on macOS](https://runnable.com/docker/install-docker-on-macos) . [Download Docker](https://www.docker.com/products/docker-desktop) then navigate to the `Docker.dmg` file and double-click to open. Drag and drop Docker into your applications folder. Authorize the installation using your system password then wait for Docker to finish installing. To check that Docker installed successfully, double-click Docker inside your applications folder to start it. The whale icon should appear in your status bar, indicating Docker is running and accessible. ### [](https://docs.portainer.io/2.27/contribute/build/mac#step-2-check-the-installed-docker-version) Step 2: Check the installed Docker version Click the Docker icon in the status bar then select **About Docker Desktop** from the menu (or a similarly named menu item, depending on your Docker version). A window should open, displaying the current version of Docker and its supporting software. [](https://docs.portainer.io/2.27/contribute/build/mac#part-2-installing-yarn) Part 2: Installing Yarn ----------------------------------------------------------------------------------------------------------- This procedure uses the Homebrew package manager. Go [here](https://brew.sh/) to learn how install it. If you don't want to use Homebrew, Yarn provides [some alternatives](https://yarnpkg.com/en/docs/install#mac-stable) . If you have issues installing or using Yarn, read their [official documentation](https://yarnpkg.com/en/docs/install#mac-stable) . Running `brew install yarn` in the macOS terminal will install Yarn. To confirm it installed successfully, run `yarn --version` in the macOS terminal. If successful, the current version of Yarn should print out in your terminal, indicating that it installed successfully and is running on your system. [](https://docs.portainer.io/2.27/contribute/build/mac#part-3-installing-or-updating-node.js) Part 3: Installing or updating Node.JS ----------------------------------------------------------------------------------------------------------------------------------------- If you used Homebrew to install Yarn, Node.JS should have automatically installed alongside it. If not, you can install it by following the [Node.JS documentation](https://nodejs.org/en/download/) . If you have issues installing or updating Node.JS using Homebrew, read [Homebrew's troubleshooting guide](https://docs.brew.sh/Common-Issues) . To check if Node.JS is installed on your system, run `node --version` in your terminal. The current version of Node.JS should print out. If the version is version 6 or later, updating it to the latest version is optional (but we recommend it because it's good practice to stay up to date). If you are running a version of Node.JS that is older than version 6, you must upgrade in order to run the Portainer development environment. If Homebrew was installed at the same time as Yarn (using Homebrew), follow these steps to update Node.JS: [PreviousBuild instructions](https://docs.portainer.io/2.27/contribute/build) [NextSet up a Linux build environment](https://docs.portainer.io/2.27/contribute/build/linux) Was this helpful? --- # Set up a Linux build environment | 2.27 LTS | Portainer Documentation As an open source product, we encourage users to edit our code and submit patches to it. This article explains how to set up a local environment on Linux so you can build your own copy of Portainer and test your changes. We tested these instructions on Ubuntu 18.04.2 LTS. For instructions that relate to other systems, see the linked documentation below. [](https://docs.portainer.io/2.27/contribute/build/linux#dependencies) Dependencies ---------------------------------------------------------------------------------------- * [Docker CE](https://docs.docker.com/install/) is the Docker application that runs on your machine to enable the use of Docker features. The latest version is not a requirement for this development stack, however we recommend staying up to date with the latest improvements and security fixes. * ​[Yarn](https://yarnpkg.com/en/docs/install#mac-stable) is a package manager for installing new software packages on your system, and is used to run the Portainer development environment. * [Node.JS](https://nodejs.org/en/download/) is a JavaScript package used when building applications that leverage networking, such as Portainer. Version 18 or later is required. * [Golang](https://golang.org/dl/) is the open source language that we use to build the majority of Portainer software. Version 1.18 of Golang is required. * Wget is a package used to retrieve files using common internet protocols such as HTTP and FTP. [](https://docs.portainer.io/2.27/contribute/build/linux#part-1-installing-docker) Part 1: Installing Docker ----------------------------------------------------------------------------------------------------------------- The following instructions were run on Ubuntu, for up-to-date instructions on this and other Linux distributions read the [official Docker CE documentation](https://docs.docker.com/install/) . You must configure the Docker repository before you install Docker. ### [](https://docs.portainer.io/2.27/contribute/build/linux#step-1-configure-the-docker-repository) Step 1: Configure the Docker repository First, update your system's packages using this command: Copy sudo apt-get update Next, install the required packages to use repos over HTTPS: Copy sudo apt-get install \ apt-transport-https \ ca-certificates \ curl \ gnupg-agent \ software-properties-common Now install the official GPG key for Docker: Copy curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - Use this fingerprint to confirm that you have the correct key: `9DC8 5822 9FC7 DD38 854A E2D8 8D81 803C 0EBF CD88` Copy sudo apt-key fingerprint 0EBFCD88 The correct output should be: Copy pub rsa4096 2017-02-22 [SCEA] 9DC8 5822 9FC7 DD38 854A E2D8 8D81 803C 0EBF CD88 uid [ unknown] Docker Release (CE deb) <[email protected]> sub rsa4096 2017-02-22 [S] And finally, use the following command to set up the stable repository: Copy sudo add-apt-repository \ "deb [arch=amd64] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) \ stable" ### [](https://docs.portainer.io/2.27/contribute/build/linux#step-2-install-docker) Step 2: Install Docker We always recommend installing software using the most up-to-date instructions from the official vendor. This step is based on Docker's own [installation instructions for Docker on Linux](https://docs.docker.com/install/) . First, update your system's packages using this command: Copy sudo apt-get update Next, install Docker and its associated packages: Copy sudo apt-get install docker-ce docker-ce-cli containerd.io Finally, verify that Docker was correctly installed and is running on your system. This command should download a test image that you can run in a container, print an informational message for then exit out of. Copy sudo docker run hello-world [](https://docs.portainer.io/2.27/contribute/build/linux#part-2-installing-yarn) Part 2: Installing Yarn ------------------------------------------------------------------------------------------------------------- If you are running a different Linux distribution than Ubuntu, read Yarn's own [installation instructions for Yarn on Linux](https://yarnpkg.com/en/docs/install) . If you have issues installing or using Yarn, read their [official documentation](https://yarnpkg.com/en/docs/install#mac-stable) . Run this command in the terminal to configure the Yarn repository on your system: Copy curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list Update your system's packages and install Yarn using this command: Copy sudo apt-get update && sudo apt-get install yarn Finally, run this command in the terminal to confirm that the Yarn installation was a success: Copy yarn --version The current version of Yarn should print out in your terminal, indicating that that it installed successfully and is running on your system. [](https://docs.portainer.io/2.27/contribute/build/linux#part-3-installing-or-updating-node.js) Part 3: Installing or updating Node.JS ------------------------------------------------------------------------------------------------------------------------------------------- This procedure makes use of NVM to install Node.JS (Node.JS version 12 or later is required). NVM allows multiple different versions of Node.JS to be installed on a system and provides an easy way to switch between them. If you have issues installing or updating Node.JS, read NVM's [documentation](https://github.com/creationix/nvm) . First, install or update to the latest version of Node.JS by running this command in the terminal: Copy nvm install node Finally, check if Node is installed on your system: Copy node --version The latest version of Node.JS should now print out. [](https://docs.portainer.io/2.27/contribute/build/linux#part-4-installing-golang-using-a-linux-tar-file) Part 4: Installing Golang using a Linux tar file --------------------------------------------------------------------------------------------------------------------------------------------------------------- Go version 1.17 must be installed. If you're upgrading from an older version, you must [remove the existing version](https://golang.org/doc/install#uninstall) first before installing version 1.17. For the most up-to-date installation instructions, read [Go's own documentation](https://golang.org/doc/install#install) . If you have issues installing or using Go, read the _Getting help_ section in their [official documentation](https://golang.org/doc/install#help) . First, [download](https://golang.org/dl/) the appropriate version of Go for your system. Navigate to where it was downloaded then extract it to the `/usr/local` directory using this command: Copy sudo tar -C /usr/local -xzf go1.17.6.linux-amd64.tar.gz Next, add `/usr/local/go/bin` to the PATH environment variable inside your shell profile. Here's an example using bash: Copy echo "export PATH=$PATH:$HOME/go/bin:/usr/local/go/bin" >> ~/.bashrc You may need to log out and log back in for this to take effect. And finally, follow the _Test your installation_ section in [Golang's official documentation](https://golang.org/doc/code.html#Testing) to ensure that Go installed correctly. [](https://docs.portainer.io/2.27/contribute/build/linux#part-5-installing-wget) Part 5: Installing Wget ------------------------------------------------------------------------------------------------------------- If you have issues installing or using Wget, read their [documentation](https://www.gnu.org/software/wget/manual/) . To install Wget on Linux, simply run the `apt-get install wget` command in the terminal. [PreviousSet up a macOS build environment](https://docs.portainer.io/2.27/contribute/build/mac) [NextPrivacy Policy](https://docs.portainer.io/2.27/privacy) Was this helpful? --- # Docker roles and permissions | 2.27 LTS | Portainer Documentation This document describes the permission levels each [RBAC role](https://docs.portainer.io/2.27/admin/user/roles) has within the Portainer application for both Docker Standalone and Docker Swarm environments. Refer to the linked notes for further requirements on each operation. Role-Based Access Control is only available in Portainer Business Edition. [](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#legend) Legend ------------------------------------------------------------------------------------------- Abbreviation Role name EA Environment Administrator OP Operator HD Helpdesk ST Standard user RO Read-only user [](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#roles-and-permissions) Roles and permissions ------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#templates) Templates Operation EA OP HD ST RO Notes View app templates Deploy app templates View custom templates [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Create custom templates Deploy custom templates [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Edit custom templates [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Change custom template ownership [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Delete custom template [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) ### [](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#stacks) Stacks Access to these operations can be affected by the **Disable the use of Stacks for non-administrators** security setting ([Docker](https://docs.portainer.io/2.27/user/docker/host/setup#docker-security-settings) , [Swarm](https://docs.portainer.io/2.27/user/docker/swarm/setup#docker-security-settings) ). Operation EA OP HD ST RO Notes View stacks [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Create a stack [3](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Edit a stack [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) View stack details [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Change stack ownership [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Stop a stack [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Start a stack [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Duplicate a stack [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Migrate a stack [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Create template from a stack [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Update service in stack [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) , [2](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Remove service from stack [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) , [2](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Delete a stack [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) ### [](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#services) Services These operations are only relevant for Docker Swarm environments. Operation EA OP HD ST RO Notes View services [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Create service [3.5](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) View service details [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Edit service [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) , [3.5](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Update service [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Roll back service [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) View service logs [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Change service ownership [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Delete service [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) ### [](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#containers) Containers Operation EA OP HD ST RO Notes View containers [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Create container [3](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Build an image from a container [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) View container details [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Start container [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Stop container [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Kill container [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Restart container [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Pause container [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Resume container [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Edit container [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) , [3](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Duplicate container [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) , [3](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Recreate container [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) , [3](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Container console [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Container attach [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Join container to network [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Remove container from network [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) View container logs [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Change container ownership [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Delete container [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) ### [](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#images) Images Operation EA OP HD ST RO Notes View images Pull an image Push an image Build an image Import an image View image details Add tag to image Remove tag from image Export image Delete an image ### [](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#volumes) Volumes Operation EA OP HD ST RO Notes View volumes [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Create a volume View volume details [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Browse a volume [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) , [4](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Change volume ownership [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Delete a volume [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) ### [](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#networks) Networks Operation EA OP HD ST RO Notes View networks [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Create a network View network details [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Change network ownership [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Delete a network [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) ### [](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#events) Events These operations are only relevant for Docker Standalone environments. Operation EA OP HD ST RO Notes View events ### [](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#configs) Configs These operations are only relevant for Docker Swarm environments. Operation EA OP HD ST RO Notes View configs [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Create a config View config details [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Clone a config [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Change config ownership [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Delete a config [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) ### [](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#secrets) Secrets These operations are only relevant for Docker Swarm environments. Operation EA OP HD ST RO Notes View secrets [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Create a secret View secret details [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Change secret ownership [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Delete a secret [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) ### [](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#host) Host These operations are only relevant for Docker Standalone environments. Operation EA OP HD ST RO Notes View host details ### [](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#swarm) Swarm These operations are only relevant for Docker Swarm environments. Operation EA OP HD ST RO Notes View cluster details ### [](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#registries) Registries Operation EA OP HD ST RO Notes Read registry [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Browse registry [1](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Update repositories [5](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Delete repositories [5](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) [](https://docs.portainer.io/2.27/advanced/docker-roles-and-permissions#notes) Notes ----------------------------------------------------------------------------------------- 1. Standard / Read only users (and Operators in the case of ownership operations) have permission only if they are given access to the resource. This can be inherited, for example inheriting a service from a stack. 2. This operation is only relevant for Swarm environments. 3. This operation can be affected by the following security settings ([Docker](https://docs.portainer.io/2.27/user/docker/host/setup#docker-security-settings) , [Swarm](https://docs.portainer.io/2.27/user/docker/swarm/setup#docker-security-settings) ): 1. **Disable privileged mode for non-administrators** 2. **Disable the use of host PID 1 for non-administrators** 3. **Disable device mappings for non-administrators** 4. **Disable container capabilities for non-administrators** 5. **Disable bind mounts for non-administrators** 4. This operation can be affected by the **Enable volume management for non-administrators** setting ([Docker](https://docs.portainer.io/2.27/user/docker/host/setup#enable-volume-management-for-non-administrators) , [Swarm](https://docs.portainer.io/2.27/user/docker/swarm/setup#host-and-filesystem) ), and requires the use of the Portainer Agent. 5. This operation can only be performed under the allowed registry. [PreviousHelm chart configuration options](https://docs.portainer.io/2.27/advanced/helm-chart-configuration-options) [NextKubernetes roles and bindings](https://docs.portainer.io/2.27/advanced/kubernetes-roles-and-bindings) Was this helpful? --- # What's new in version 2.35 | 2.35 STS | Portainer Documentation Portainer version 2.35 includes a number of new fixes and updates. For a full list of changes, please refer to our [release notes](https://docs.portainer.io/sts/release-notes) . [](https://docs.portainer.io/sts/whats-new#short-term-support-sts) Short Term Support (STS) ------------------------------------------------------------------------------------------------ 2.35 is a Short Term Support, or "STS", release of Portainer. STS releases intended to be an introduction of new features and functionality in Portainer, and while we do perform significant testing prior to release are not recommended for production use. For production, we recommend staying with the Long Term Support (LTS) releases. The features that appear in STS releases will, once refined and stable, be implemented in the next LTS release. You can read more about our release principles in our [lifecycle policy](https://docs.portainer.io/sts/start/lifecycle) . [](https://docs.portainer.io/sts/whats-new#new-in-this-release) New in this release ---------------------------------------------------------------------------------------- ### [](https://docs.portainer.io/sts/whats-new#automatic-patch-updates) Automatic patch updates ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FpVQRQqVtoWyELrx2mP2t%2Fbutton_be.png&width=300&dpr=4&quality=100&sign=b5e853a3&sv=2) Portainer now supports [automatic patch updates](https://docs.portainer.io/sts/admin/settings/general#automatic-portainer-patch-updates) , keeping your instance up to date with the latest patch releases. You can schedule when patches are applied, use a custom registry for air-gapped or restricted environments, and track applied updates in the Patch history table. This feature is in beta and should be used with caution in production environments. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2F2686689526-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FoeG1zgfd7OQLVZtVK5LC%252Fuploads%252FerJ0v0qREYgwDk4L1gUF%252F2.35_auto_patch_updates.png%3Falt%3Dmedia%26token%3D83e8ef03-68bd-43bc-a893-911855dcf831&width=768&dpr=4&quality=100&sign=5c3c8130&sv=2) ### [](https://docs.portainer.io/sts/whats-new#git-integration-for-helm-chart-deployments) Git integration for Helm chart deployments ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FpVQRQqVtoWyELrx2mP2t%2Fbutton_be.png&width=300&dpr=4&quality=100&sign=b5e853a3&sv=2) Portainer now supports [deploying Helm charts directly from a Git source](https://docs.portainer.io/sts/user/kubernetes/applications/manifest/helm#git-repository) , allowing you to manage Helm releases through your Git repository. You can view Git details for deployed Helm releases and see when a release is out of sync with its Git source. Applications created from Git [can also be edited](https://docs.portainer.io/sts/user/kubernetes/applications/edit-helm) and upgraded by modifying the Git settings directly within the application view. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2F2686689526-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FoeG1zgfd7OQLVZtVK5LC%252Fuploads%252FAfT7bKLrwmQS2XLwyTrC%252F2.35-whats-new-helm.gif%3Falt%3Dmedia%26token%3D5f837124-ea43-49e3-b616-e242a3ebcf27&width=768&dpr=4&quality=100&sign=5ff031c5&sv=2) ### [](https://docs.portainer.io/sts/whats-new#always-clone-option-for-edge-stacks) Always clone option for Edge stacks ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FpVQRQqVtoWyELrx2mP2t%2Fbutton_be.png&width=300&dpr=4&quality=100&sign=b5e853a3&sv=2) You can now choose to [always clone your Git repository](https://docs.portainer.io/sts/user/edge/stacks/add#always-clone-git-repository) when deploying Edge stacks that use relative path volumes. Enabling this option will ensure that Portainer automatically pulls the latest content from your Git repository to the target environment during deployment. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2F2686689526-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FoeG1zgfd7OQLVZtVK5LC%252Fuploads%252Frt0hXcWv8Q8O9hlPZWWL%252F2.35-Always-clone-git-standalone.png%3Falt%3Dmedia%26token%3Db226a438-0fd2-4576-a421-5565a1b3b4fa&width=768&dpr=4&quality=100&sign=5477745a&sv=2) [PreviousWelcome](https://docs.portainer.io/sts) [NextRelease Notes](https://docs.portainer.io/sts/release-notes) Last updated 1 month ago Was this helpful? --- # Welcome | 2.35 STS | Portainer Documentation Welcome to Portainer's official documentation site. [](https://docs.portainer.io/sts#about-portainer) 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](https://docs.portainer.io/sts/admin/user/roles) , [registry management](https://docs.portainer.io/sts/admin/registries/browse) , and [dedicated support](https://docs.portainer.io/sts#getting-support) , Portainer BE is a powerful toolset that allows you to easily build and manage containers in Docker, Docker Swarm, Kubernetes, Podman and Azure ACI. 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](https://www.portainer.io/get-a-license) of Portainer Business Edition or [purchase a license](https://www.portainer.io/pricing) . 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](https://docs.portainer.io/sts#community-edition-five-three-node-free-and-home-and-student-users) , and paid Business customers through our [business support channels](https://docs.portainer.io/sts#business-edition-customers) . [](https://docs.portainer.io/sts#documentation) 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 raise a question in one of our [support channels](https://docs.portainer.io/sts#getting-support) . For more detailed step-by-step guides to Portainer, we're building out the [Portainer Academy](https://academy.portainer.io/) with more courses regularly. 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](https://www.youtube.com/channel/UC7diMJcrULjDseq5yhSUZgg) , we cover a lot of ground but there may be gaps. [](https://docs.portainer.io/sts#getting-support) Getting support ---------------------------------------------------------------------- ### [](https://docs.portainer.io/sts#community-edition-five-three-node-free-and-home-and-student-users) 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](https://github.com/orgs/portainer/discussions/categories/help) forum or the [community Slack channel](https://portainer.io/slack) . Other platforms exist (Reddit, Discord, Stack Overflow) but we are less active in those spaces. * **Log bugs** in [GitHub Issues](https://github.com/portainer/portainer/issues) so they can be properly managed. * **Flag vulnerabilities** by emailing [\[email protected\]](https://docs.portainer.io/cdn-cgi/l/email-protection#2754424452554e535e6757485553464e494255094e48) so we can deal with them immediately. * **Flag documentation issues** via our [GitHub documentation channel](https://github.com/portainer/portainer-docs/issues) (or start [contributing](https://docs.portainer.io/sts/contribute/contribute) and make our documentation better!). ### [](https://docs.portainer.io/sts#business-edition-customers) 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](https://docs.portainer.io/cdn-cgi/l/email-protection#432136302a2d263030303633332c313703332c3137222a2d26316d2a2c) or filling out the [Request Support form](https://www.portainer.io/portainer-business-support) . 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. [NextWhat's new in version 2.35](https://docs.portainer.io/sts/whats-new) Last updated 27 days ago Was this helpful? --- # Introduction | 2.35 STS | Portainer Documentation This section explains the Portainer architecture and how to install it. We recommend that you read the entire section to ensure your installation goes smoothly. Learn about the [architecture](https://docs.portainer.io/sts/start/architecture) first, get familiar with the [prerequisites to installation](https://docs.portainer.io/sts/start/requirements-and-prerequisites) , then finally, step through how to [install the product](https://docs.portainer.io/sts/start/install) in your environment. [Portainer architecture](https://docs.portainer.io/sts/start/architecture) [PreviousRelease Notes](https://docs.portainer.io/sts/release-notes) [NextPortainer architecture](https://docs.portainer.io/sts/start/architecture) Was this helpful? --- # Set up a new Portainer BE Server installation | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/sts/start/install-ce/server) . Select the environment for your new Portainer installation: [Docker Standalone](https://docs.portainer.io/sts/start/install/server/docker) [Docker Swarm](https://docs.portainer.io/sts/start/install/server/swarm) [Podman](https://docs.portainer.io/sts/start/install/server/podman) [Kubernetes](https://docs.portainer.io/sts/start/install/server/kubernetes) [PreviousInstall Portainer BE](https://docs.portainer.io/sts/start/install) [NextDocker Standalone](https://docs.portainer.io/sts/start/install/server/docker) Was this helpful? --- # Install Portainer BE | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/sts/start/install-ce) . Portainer Business Edition is straightforward to install. There are two options: installing new or adding an environment to an existing installation. For a detailed, step-by-step guide to setting up Portainer for production, have a look at our [Best Practice Install Guide](https://academy.portainer.io/install/) in the Portainer Academy. If you haven't already, please check that your environments meet [our requirements](https://docs.portainer.io/sts/start/requirements-and-prerequisites) before proceeding. [Set up a new Portainer BE Server installation](https://docs.portainer.io/sts/start/install/server) [Add an environment to an existing installation](https://docs.portainer.io/sts/start/agent) [PreviousRequirements and prerequisites](https://docs.portainer.io/sts/start/requirements-and-prerequisites) [NextSet up a new Portainer BE Server installation](https://docs.portainer.io/sts/start/install/server) Was this helpful? --- # Docker Standalone | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/sts/start/install-ce/server/docker) . Installation instructions can differ between platforms. Please choose your platform below: [Install Portainer BE with Docker on Linux](https://docs.portainer.io/sts/start/install/server/docker/linux) [Install Portainer BE with Docker on WSL / Docker Desktop](https://docs.portainer.io/sts/start/install/server/docker/wsl) [Install Portainer BE with Docker on Windows Container Service](https://docs.portainer.io/sts/start/install/server/docker/wcs) [PreviousSet up a new Portainer BE Server installation](https://docs.portainer.io/sts/start/install/server) [NextInstall Portainer BE with Docker on Linux](https://docs.portainer.io/sts/start/install/server/docker/linux) Was this helpful? --- # Install Portainer BE with Docker on Linux | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/sts/start/install-ce/server/docker/linux) . [](https://docs.portainer.io/sts/start/install/server/docker/linux#introduction) Introduction -------------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_, and the _Portainer Agent_. Both elements run as lightweight Docker containers on a Docker engine. This document will help you install the Portainer Server container on your Linux environment. To add a new Linux environment to an existing Portainer Server installation, please refer to the [Portainer Agent installation instructions](https://docs.portainer.io/sts/admin/environments/add/docker/agent) . To get started, you will need: * The latest version of Docker installed and working. We recommend following the [official installation instructions](https://docs.docker.com/engine/install/) for Docker - in particular, we advise _against_ installing Docker via snap on Ubuntu distributions as you may run into compatibility issues. * sudo access on the machine that will host your Portainer Server instance * By default, Portainer Server will expose the UI over port `9443` and expose a TCP tunnel server over port `8000`. The latter is optional and is only required if you plan to use the Edge compute features with Edge agents. * A license key for Portainer Business Edition. The installation instructions also make the following assumptions about your environment: * Your environment meets [our requirements](https://docs.portainer.io/sts/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. * You are accessing Docker via Unix sockets. Alternatively, you can also connect via TCP. * SELinux is disabled on the machine running Docker. If you require SELinux, you will need to pass the `--privileged` flag to Docker when deploying Portainer. * Docker is running as root. Portainer with rootless Docker has some limitations, and requires additional configuration. [](https://docs.portainer.io/sts/start/install/server/docker/linux#deployment) Deployment ---------------------------------------------------------------------------------------------- You can choose to deploy Portainer using `docker run` or via Docker Compose. docker run Docker Compose To install using `docker run`, first create the volume that Portainer Server will use to store its database: Copy docker volume create portainer_data Then, download and install the Portainer Server container: Copy docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ee:sts By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-docker-standalone) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. If you require HTTP port `9000` open for legacy reasons, add the following to your `docker run` command: `-p 9000:9000` Portainer Server has now been installed. You can check to see whether the Portainer Server container has started by running `docker ps`: Copy root@server:~# docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 7963585688a9 portainer/portainer-ee:sts "/portainer" 8 seconds ago Up 8 seconds 0.0.0.0:8000->8000/tcp, [::]:8000->8000/tcp, 0.0.0.0:9443->9443/tcp, [::]:9443->9443/tcp, 9000/tcp portainer To install using Docker Compose, download the compose file using the following `curl` command: Copy curl -L https://downloads.portainer.io/ee-sts/portainer-compose.yaml -o portainer-compose.yaml Alternatively, create a `portainer-compose.yaml` file with the following contents: Copy services: portainer: container_name: portainer image: portainer/portainer-ee:sts restart: always volumes: - /var/run/docker.sock:/var/run/docker.sock - portainer_data:/data ports: - 9443:9443 - 8000:8000 # Remove if you do not intend to use Edge Agents volumes: portainer_data: name: portainer_data networks: default: name: portainer_network Once you have created or downloaded the compose file, you can deploy it with the following command: Copy docker compose -f portainer-compose.yaml up -d Docker Compose will create the necessary resources and deploy Portainer. You can check to see whether the Portainer Server container has started by running `docker ps`: Copy root@server:~# docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 7963585688a9 portainer/portainer-ee:sts "/portainer" 8 seconds ago Up 8 seconds 0.0.0.0:8000->8000/tcp, [::]:8000->8000/tcp, 0.0.0.0:9443->9443/tcp, [::]:9443->9443/tcp, 9000/tcp portainer [](https://docs.portainer.io/sts/start/install/server/docker/linux#logging-in) Logging In ---------------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance by opening a web browser and going to: Copy https://localhost:9443 Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/sts/start/install/server/setup) [PreviousDocker Standalone](https://docs.portainer.io/sts/start/install/server/docker) [NextInstall Portainer BE with Docker on WSL / Docker Desktop](https://docs.portainer.io/sts/start/install/server/docker/wsl) Was this helpful? --- # Install Portainer BE with Docker on WSL / Docker Desktop | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/sts/start/install-ce/server/docker/wsl) . [](https://docs.portainer.io/sts/start/install/server/docker/wsl#introduction) Introduction ------------------------------------------------------------------------------------------------ Portainer consists of two elements, the _Portainer Server_, and the _Portainer Agent_. Both elements run as lightweight Docker containers on a Docker engine. This document will help you install the Portainer Server container on your Windows environment with WSL and Docker Desktop. To add a new WSL / Docker Desktop environment to an existing Portainer Server installation, please refer to the [Portainer Agent installation instructions](https://docs.portainer.io/sts/admin/environments/add/docker/agent) . To get started, you will need: * The latest version of Docker Desktop installed and working. * Administrator access on the machine that will host your Portainer Server instance. * Windows Subsystem for Linux (WSL) installed and a Linux distribution selected. For a new installation we recommend WSL2. * By default, Portainer Server will expose the UI over port `9443` and expose a TCP tunnel server over port `8000`. The latter is optional and is only required if you plan to use the Edge compute features with Edge agents. * A license key for Portainer Business Edition. The installation instructions also make the following assumptions about your environment: * Your environment meets [our requirements](https://docs.portainer.io/sts/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. * You are accessing Docker via Unix sockets. Alternatively, you can also connect via TCP. * SELinux is disabled within the Linux distribution used by WSL. If you require SELinux, you will need to pass the `--privileged` flag to Docker when deploying Portainer. * Docker is running as root. Portainer with rootless Docker has some limitations, and requires additional configuration. [](https://docs.portainer.io/sts/start/install/server/docker/wsl#deployment) Deployment -------------------------------------------------------------------------------------------- First, create the volume that Portainer Server will use to store its database: Copy docker volume create portainer_data Then, download and install the Portainer Server container: Copy docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ee:lts By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-docker-standalone) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. If you require HTTP port `9000` open for legacy reasons, add the following to your `docker run` command: `-p 9000:9000` Portainer Server has now been installed. You can check to see whether the Portainer Server container has started by running `docker ps`: Copy root@server:~# docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES f4ab79732007 portainer/portainer-ee:lts "/portainer" 2 weeks ago Up 29 hours 0.0.0.0:8000->8000/tcp, :::8000->8000/tcp, 0.0.0.0:9443->9000/tcp, :::9443->9443/tcp portainer [](https://docs.portainer.io/sts/start/install/server/docker/wsl#logging-in) Logging In -------------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance by opening a web browser and going to: Copy https://localhost:9443 Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/sts/start/install/server/setup) [PreviousInstall Portainer BE with Docker on Linux](https://docs.portainer.io/sts/start/install/server/docker/linux) [NextInstall Portainer BE with Docker on Windows Container Service](https://docs.portainer.io/sts/start/install/server/docker/wcs) Was this helpful? --- # Install Portainer BE with Docker Swarm on Linux | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/sts/start/install-ce/server/swarm/linux) . [](https://docs.portainer.io/sts/start/install/server/swarm/linux#introduction) Introduction ------------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_ and the _Portainer Agent_. Both elements run as lightweight Docker containers on a Docker engine. This document will help you deploy the Portainer Server and Agent containers on your Linux environment. To add a new Linux Swarm environment to an existing Portainer Server installation, please refer to the [Portainer Agent installation instructions](https://docs.portainer.io/sts/admin/environments/add/swarm/agent) . To get started, you will need: * The latest version of Docker installed and working. We recommend following the [official installation instructions](https://docs.docker.com/engine/install/) for Docker - in particular, we advise _against_ installing Docker via snap on Ubuntu distributions as you may run into compatibility issues. * Swarm mode [enabled](https://docs.docker.com/engine/swarm/swarm-mode/) and working, including the overlay network for the swarm service communication * `sudo` access on the manager node of your swarm cluster * By default, Portainer will expose the UI over port `9443` and expose a TCP tunnel server over port `8000`. The latter is optional and is only required if you plan to use the Edge compute features with Edge agents. * The manager and worker nodes must be able to communicate with each other over port `9001`. * A license key for Portainer Business Edition. The installation instructions also make the following assumptions about your environment: * Your environment meets [our requirements](https://docs.portainer.io/sts/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. * You are accessing Docker via Unix sockets. Connecting via TCP is not supported in Docker Swarm. * SELinux is disabled on the machine running Docker. * Docker is running as root. Portainer with rootless Docker has some limitations, and requires additional configuration. * You are running a single manager node in your swarm. If you have more than one, please [read this knowledge base article](https://portal.portainer.io/knowledge/how-can-i-ensure-portainers-configuration-is-retained) before proceeding. * If your nodes are using DNS records to communicate, that all records are resolvable across the cluster. [](https://docs.portainer.io/sts/start/install/server/swarm/linux#deployment) Deployment --------------------------------------------------------------------------------------------- Portainer can be directly deployed as a service in your Docker cluster. Note that this method will automatically deploy a single instance of the Portainer Server, and deploy the Portainer Agent as a global service on every node in your cluster. Only do this **once** for your environment, regardless of how many nodes are in the cluster. You **do not** need to add each node in your cluster as a separate environment in Portainer. Deploying the manifest to your swarm will include every node in the cluster automatically. Adding each node as a separate environment will also consume more of your licensed node count than you may expect. First, retrieve the stack YML manifest: Copy curl -L https://downloads.portainer.io/ee-sts/portainer-agent-stack.yml -o portainer-agent-stack.yml Then use the downloaded YML manifest to deploy your stack: Copy docker stack deploy -c portainer-agent-stack.yml portainer By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-docker-swarm) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. Portainer Server and the Agents have now been installed. You can check to see whether the Portainer Server and Agent containers have started by running `docker ps`: Copy root@manager01:~# docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 59ee466f6b15 portainer/agent:sts "./agent" About a minute ago Up About a minute portainer_agent.xbb8k6r7j1tk9gozjku7e43wr.5sa6b3e8cl6hyu0snlt387sgv 2db7dd4bfba0 portainer/portainer-ee:sts "/portainer -H tcp:/…" About a minute ago Up About a minute 8000/tcp, 9443/tcp portainer_portainer.1.gpuvu3pqmt1m19zxfo44v7izx [](https://docs.portainer.io/sts/start/install/server/swarm/linux#logging-in) Logging In --------------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance by opening a web browser and going to: Copy https://localhost:9443 Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/sts/start/install/server/setup) [PreviousDocker Swarm](https://docs.portainer.io/sts/start/install/server/swarm) [NextInstall Portainer BE with Docker Swarm on WSL / Docker Desktop](https://docs.portainer.io/sts/start/install/server/swarm/wsl) Was this helpful? --- # Install Portainer BE with Docker Swarm on WSL / Docker Desktop | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/sts/start/install-ce/server/swarm/wsl) . [](https://docs.portainer.io/sts/start/install/server/swarm/wsl#introduction) Introduction ----------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_, and the _Portainer Agent_. Both elements run as lightweight Docker containers on a Docker engine. This document will help you install the Portainer Server container on your Windows environment with WSL and Docker Desktop. To add a new WSL / Docker Desktop Swarm environment to an existing Portainer Server installation, please refer to the [Portainer Agent installation instructions](https://docs.portainer.io/sts/admin/environments/add/swarm/agent) . To get started, you will need: * The latest version of Docker Desktop installed and working. * Swarm mode [enabled](https://docs.docker.com/engine/swarm/swarm-mode/) and working, including the overlay network for the swarm service communication. * Administrator access on the manager node of your Swarm cluster. * Windows Subsystem for Linux (WSL) installed and a Linux distribution selected. For a new installation we recommend WSL2. * By default, Portainer will expose the UI over port `9443` and expose a TCP tunnel server over port `8000`. The latter is optional and is only required if you plan to use the Edge compute features with Edge agents. * The manager and worker nodes must be able to communicate with each other over port `9001`. * A license key for Portainer Business Edition. The installation instructions also make the following assumptions about your environment: * Your environment meets [our requirements](https://docs.portainer.io/sts/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. * You are accessing Docker via Unix sockets. Alternatively, you can also connect via TCP. * SELinux is disabled within the Linux distribution used by WSL. * Docker is running as root. Portainer with rootless Docker has some limitations, and requires additional configuration. * You are running a single manager node in your swarm. If you have more than one, please [read this article](https://docs.portainer.io/sts/faqs/installing/how-can-i-ensure-portainers-configuration-is-retained) before proceeding. * If your nodes are using DNS records to communicate, that all records are resolvable across the cluster. [](https://docs.portainer.io/sts/start/install/server/swarm/wsl#deployment) Deployment ------------------------------------------------------------------------------------------- Portainer can be directly deployed as a service in your Docker Swarm cluster. Note that this method will automatically deploy a single instance of the Portainer Server, and deploy the Portainer Agent as a global service on every node in your cluster. Only do this **once** for your environment, regardless of how many nodes are in the cluster. You **do not** need to add each node in your cluster as a separate environment in Portainer. Deploying the manifest to your swarm will include every node in the cluster automatically. Adding each node as a separate environment will also consume more of your licensed node count than you may expect. To begin the installation, first retrieve the stack YML manifest: Copy curl -L https://downloads.portainer.io/ee-lts/portainer-agent-stack.yml -o portainer-agent-stack.yml Then use the downloaded YML manifest to deploy your stack: Copy docker stack deploy -c portainer-agent-stack.yml portainer By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-docker-swarm) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. [](https://docs.portainer.io/sts/start/install/server/swarm/wsl#logging-in) Logging In ------------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance by opening a web browser and going to: Copy https://localhost:9443 Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/sts/start/install/server/setup) [PreviousInstall Portainer BE with Docker Swarm on Linux](https://docs.portainer.io/sts/start/install/server/swarm/linux) [NextInstall Portainer BE with Docker Swarm on Windows Container Service](https://docs.portainer.io/sts/start/install/server/swarm/wcs) Was this helpful? --- # Docker Swarm | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/sts/start/install-ce/server/swarm) . Installation instructions can differ between platforms. Please choose your platform below: [Install Portainer BE with Docker Swarm on Linux](https://docs.portainer.io/sts/start/install/server/swarm/linux) [Install Portainer BE with Docker Swarm on WSL / Docker Desktop](https://docs.portainer.io/sts/start/install/server/swarm/wsl) [Install Portainer BE with Docker Swarm on Windows Container Service](https://docs.portainer.io/sts/start/install/server/swarm/wcs) [PreviousInstall Portainer BE with Docker on Windows Container Service](https://docs.portainer.io/sts/start/install/server/docker/wcs) [NextInstall Portainer BE with Docker Swarm on Linux](https://docs.portainer.io/sts/start/install/server/swarm/linux) Was this helpful? --- # Install Portainer BE with Docker on Windows Container Service | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/sts/start/install-ce/server/docker/wcs) . [](https://docs.portainer.io/sts/start/install/server/docker/wcs#introduction) Introduction ------------------------------------------------------------------------------------------------ Portainer consists of two elements, the _Portainer Server_, and the _Portainer Agent_. Both elements run as lightweight Docker containers on a Docker engine. This document will help you install the Portainer Server container on your Windows server with Windows Containers. To add a new WCS environment to an existing Portainer Server installation, please refer to the [Portainer Agent installation instructions](https://docs.portainer.io/sts/admin/environments/add/docker/agent) . To get started, you will need: * Administrator access on the machine that will host your Portainer Server instance * By default, Portainer Server will expose the UI over port `9443` and expose a TCP tunnel server over port `8000`. The latter is optional and is only required if you plan to use the Edge compute features with Edge agents. * A license key for Portainer Business Edition. The installation instructions also make the following assumption about your environment: * Your environment meets [our requirements](https://docs.portainer.io/sts/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. [](https://docs.portainer.io/sts/start/install/server/docker/wcs#preparation) Preparation ---------------------------------------------------------------------------------------------- To run Portainer Server in a Windows Server/Desktop Environment you need to create exceptions in the firewall. These can easily be added through PowerShell by running the following commands: Copy netsh advfirewall firewall add rule name="cluster_management" dir=in action=allow protocol=TCP localport=2377 netsh advfirewall firewall add rule name="node_communication_tcp" dir=in action=allow protocol=TCP localport=7946 netsh advfirewall firewall add rule name="node_communication_udp" dir=in action=allow protocol=UDP localport=7946 netsh advfirewall firewall add rule name="overlay_network" dir=in action=allow protocol=UDP localport=4789 netsh advfirewall firewall add rule name="swarm_dns_tcp" dir=in action=allow protocol=TCP localport=53 netsh advfirewall firewall add rule name="swarm_dns_udp" dir=in action=allow protocol=UDP localport=53 You will also need to install the Windows Container Host Service and install Docker. Microsoft have [provided](https://learn.microsoft.com/en-us/virtualization/windowscontainers/quick-start/set-up-environment?tabs=dockerce#windows-server-1) a PowerShell script to perform the necessary actions. You can download the script and run it with the following commands: Copy Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/microsoft/Windows-Containers/Main/helpful_tools/Install-DockerCE/install-docker-ce.ps1" -o install-docker-ce.ps1 .\install-docker-ce.ps1 Once this is complete you will need to restart your Windows server. After the restart completes, you're ready to install Portainer itself. [](https://docs.portainer.io/sts/start/install/server/docker/wcs#deployment) Deployment -------------------------------------------------------------------------------------------- First, create the volume that Portainer Server will use to store its database. Using PowerShell: Copy docker volume create portainer_data Then, download and install the Portainer Server container: Copy docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart always -v \\.\pipe\docker_engine:\\.\pipe\docker_engine -v portainer_data:C:\data portainer/portainer-ee:lts By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. If you see an error message similar to: `"\\.\pipe\dockerDesktopEngine" includes invalid characters for a local volume name` then you may not have Windows containers properly enabled. If you are using Docker Desktop, right click the icon in your tray and select **Switch to Windows Containers**. If you require HTTP port `9000` open for legacy reasons, add the following to your `docker run` command: `-p 9000:9000` [](https://docs.portainer.io/sts/start/install/server/docker/wcs#logging-in) Logging In -------------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance by opening a web browser and going to: Copy https://localhost:9443 Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/sts/start/install/server/setup) [PreviousInstall Portainer BE with Docker on WSL / Docker Desktop](https://docs.portainer.io/sts/start/install/server/docker/wsl) [NextDocker Swarm](https://docs.portainer.io/sts/start/install/server/swarm) Was this helpful? --- # Podman | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/sts/start/install-ce/server/podman) . Installation instructions can differ between platforms. Please choose your platform below: [Install Portainer BE with Podman on Linux](https://docs.portainer.io/sts/start/install/server/podman/linux) [PreviousInstall Portainer BE with Docker Swarm on Windows Container Service](https://docs.portainer.io/sts/start/install/server/swarm/wcs) [NextInstall Portainer BE with Podman on Linux](https://docs.portainer.io/sts/start/install/server/podman/linux) Was this helpful? --- # Install Portainer BE with Docker Swarm on Windows Container Service | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/sts/start/install-ce/server/swarm/wcs) . [](https://docs.portainer.io/sts/start/install/server/swarm/wcs#introduction) Introduction ----------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_, and the _Portainer Agent_. Both elements run as lightweight Docker containers on a Docker engine. This document will help you install the Portainer Server container on your Windows server with Windows Containers. To add a new WCS environment to an existing Portainer Server installation, please refer to the [Portainer Agent installation instructions](https://docs.portainer.io/sts/admin/environments/add/swarm/agent) . To get started, you will need: * The latest version of Docker installed and working. * Swarm mode [enabled](https://docs.docker.com/engine/swarm/swarm-mode/) and working, including the overlay network for the swarm service communication. * Administrator access on the manager node of your Swarm cluster. * By default, Portainer will expose the UI over port `9443` and expose a TCP tunnel server over port `8000`. The latter is optional and is only required if you plan to use the Edge compute features with Edge agents. * The manager and worker nodes must be able to communicate with each other over port `9001`. * A license key for Portainer Business Edition. The installation instructions also make the following assumptions about your environment: * Your environment meets [our requirements](https://docs.portainer.io/sts/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. * You are running a single manager node in your swarm. If you have more than one, please [read this article](https://docs.portainer.io/sts/faqs/installing/how-can-i-ensure-portainers-configuration-is-retained) before proceeding. * If your nodes are using DNS records to communicate, that all records are resolvable across the cluster. [](https://docs.portainer.io/sts/start/install/server/swarm/wcs#preparation) Preparation --------------------------------------------------------------------------------------------- To run Portainer Server in a Windows Server/Desktop Environment you need to create exceptions in the firewall. These can easily be added through PowerShell by running the following commands: Copy netsh advfirewall firewall add rule name="cluster_management" dir=in action=allow protocol=TCP localport=2377 netsh advfirewall firewall add rule name="node_communication_tcp" dir=in action=allow protocol=TCP localport=7946 netsh advfirewall firewall add rule name="node_communication_udp" dir=in action=allow protocol=UDP localport=7946 netsh advfirewall firewall add rule name="overlay_network" dir=in action=allow protocol=UDP localport=4789 netsh advfirewall firewall add rule name="swarm_dns_tcp" dir=in action=allow protocol=TCP localport=53 netsh advfirewall firewall add rule name="swarm_dns_udp" dir=in action=allow protocol=UDP localport=53 You will also need to install the Windows Container Host Service and install Docker. Microsoft have [provided](https://learn.microsoft.com/en-us/virtualization/windowscontainers/quick-start/set-up-environment?tabs=dockerce#windows-server-1) a PowerShell script to perform the necessary actions. You can download the script and run it with the following commands: Copy Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/microsoft/Windows-Containers/Main/helpful_tools/Install-DockerCE/install-docker-ce.ps1" -o install-docker-ce.ps1 .\install-docker-ce.ps1 Once this is complete you will need to restart your Windows server. After the restart completes, you're ready to install Portainer itself. [](https://docs.portainer.io/sts/start/install/server/swarm/wcs#deployment) Deployment ------------------------------------------------------------------------------------------- Portainer can be directly deployed as a service in your Docker cluster. Note that this method will automatically deploy a single instance of the Portainer Server, and deploy the Portainer Agent as a global service on every node in your cluster. Only do this **once** for your environment, regardless of how many nodes are in the cluster. You **do not** need to add each node in your cluster as a separate environment in Portainer. Deploying the manifest to your swarm will include every node in the cluster automatically. Adding each node as a separate environment will also consume more of your licensed node count than you may expect. You can use our YML manifest to run Portainer in Windows using Windows Containers. In PowerShell, run: Copy curl https://downloads.portainer.io/ee-lts/portainer_windows_stack.yml -o portainer-windows-stack.yml Then use the downloaded YML manifest to deploy your stack: Copy docker stack deploy --compose-file=portainer-windows-stack.yml portainer By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-docker-swarm) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. [](https://docs.portainer.io/sts/start/install/server/swarm/wcs#logging-in) Logging In ------------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance by opening a web browser and going to: Copy https://localhost:9443 Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/sts/start/install/server/setup) [PreviousInstall Portainer BE with Docker Swarm on WSL / Docker Desktop](https://docs.portainer.io/sts/start/install/server/swarm/wsl) [NextPodman](https://docs.portainer.io/sts/start/install/server/podman) Was this helpful? --- # Kubernetes | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/sts/start/install-ce/server/kubernetes) . Installation instructions can differ between platforms. Please choose your platform below: [Install Portainer BE on your Kubernetes environment](https://docs.portainer.io/sts/start/install/server/kubernetes/baremetal) [Install Portainer BE with Kubernetes on WSL / Docker Desktop](https://docs.portainer.io/sts/start/install/server/kubernetes/wsl) [PreviousInstall Portainer BE with Podman on Linux](https://docs.portainer.io/sts/start/install/server/podman/linux) [NextInstall Portainer BE on your Kubernetes environment](https://docs.portainer.io/sts/start/install/server/kubernetes/baremetal) Was this helpful? --- # Install Portainer BE with Podman on Linux | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/sts/start/install-ce/server/podman/linux) . [](https://docs.portainer.io/sts/start/install/server/podman/linux#introduction) Introduction -------------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_, and the _Portainer Agent_. Both elements run as lightweight containers on a Podman engine. This document will help you install the Portainer Server container on your Linux environment. To add a new Linux environment to an existing Portainer Server installation, please refer to the [Portainer Agent installation instructions](https://docs.portainer.io/sts/admin/environments/add/podman/agent) . To get started, you will need: * CentOS 9 with the latest version of Podman 5.x installed and working on your Podman host. Other Podman versions and Linux distros may work but we currently only support the above. We recommend following the [official installation instructions](https://podman.io/docs/installation#installing-on-linux) for Podman. * sudo access on the machine that will host your Portainer Server instance * By default, Portainer Server will expose the UI over port `9443` and expose a TCP tunnel server over port `8000`. The latter is optional and is only required if you plan to use the Edge compute features with Edge agents. * A license key for Portainer Business Edition. The installation instructions also make the following assumptions about your environment: * Your environment meets [our requirements](https://docs.portainer.io/sts/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. * You are accessing Podman via Unix sockets. * Podman is running as root. Portainer with rootless Podman may work but is currently not officially supported. [](https://docs.portainer.io/sts/start/install/server/podman/linux#deployment) Deployment ---------------------------------------------------------------------------------------------- First, ensure the Podman socket is enabled: Copy systemctl enable --now podman.socket Next, create the volume that Portainer Server will use to store its database: Copy podman volume create portainer_data Then, download and install the Portainer Server container: Copy podman run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always --privileged -v /run/podman/podman.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ee:lts By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-docker-standalone) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. If you require HTTP port `9000` open for legacy reasons, add the following to your `podman run` command: `-p 9000:9000` Portainer Server has now been installed. You can check to see whether the Portainer Server container has started by running `podman ps`: Copy root@server:~# podman ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES de5b28eb2fa9 portainer/portainer-ee:lts "/portainer" 2 weeks ago Up 9 days 0.0.0.0:8000->8000/tcp, :::8000->8000/tcp, 0.0.0.0:9443->9443/tcp, :::9443->9443/tcp portainer [](https://docs.portainer.io/sts/start/install/server/podman/linux#logging-in) Logging In ---------------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance by opening a web browser and going to: Copy https://localhost:9443 Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/sts/start/install/server/setup) [PreviousPodman](https://docs.portainer.io/sts/start/install/server/podman) [NextKubernetes](https://docs.portainer.io/sts/start/install/server/kubernetes) Was this helpful? --- # Install Portainer CE with Docker on Linux | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Community Edition (CE). For Portainer Business Edition (BE) refer to the [BE install documentation](https://docs.portainer.io/sts/start/install/server/docker/linux) . [](https://docs.portainer.io/sts/start/install-ce/server/docker/linux#introduction) Introduction ----------------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_, and the _Portainer Agent_. Both elements run as lightweight Docker containers on a Docker engine. This document will help you install the Portainer Server container on your Linux environment. To add a new Linux environment to an existing Portainer Server installation, please refer to the [Portainer Agent installation instructions](https://docs.portainer.io/sts/admin/environments/add/docker/agent) . To get started, you will need: * The latest version of Docker installed and working. We recommend following the [official installation instructions](https://docs.docker.com/engine/install/) for Docker - in particular, we advise _against_ installing Docker via snap on Ubuntu distributions as you may run into compatibility issues. * sudo access on the machine that will host your Portainer Server instance * By default, Portainer Server will expose the UI over port `9443` and expose a TCP tunnel server over port `8000`. The latter is optional and is only required if you plan to use the Edge compute features with Edge agents. The installation instructions also make the following assumptions about your environment: * Your environment meets [our requirements](https://docs.portainer.io/sts/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. * You are accessing Docker via Unix sockets. Alternatively, you can also connect via TCP. * SELinux is disabled on the machine running Docker. If you require SELinux, you will need to pass the `--privileged` flag to Docker when deploying Portainer. * Docker is running as root. Portainer with rootless Docker has some limitations, and requires additional configuration. [](https://docs.portainer.io/sts/start/install-ce/server/docker/linux#deployment) Deployment ------------------------------------------------------------------------------------------------- You can choose to deploy Portainer using `docker run` or via Docker Compose. docker run Docker Compose To install using `docker run`, first create the volume that Portainer Server will use to store its database: Copy docker volume create portainer_data Then, download and install the Portainer Server container: Copy docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:sts By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-docker-standalone) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. If you require HTTP port `9000` open for legacy reasons, add the following to your `docker run` command: `-p 9000:9000` Portainer Server has now been installed. You can check to see whether the Portainer Server container has started by running `docker ps`: Copy root@server:~# docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 7963585688a9 portainer/portainer-ce:sts "/portainer" 8 seconds ago Up 8 seconds 0.0.0.0:8000->8000/tcp, [::]:8000->8000/tcp, 0.0.0.0:9443->9443/tcp, [::]:9443->9443/tcp, 9000/tcp portainer To install using Docker Compose, download the compose file using the following `curl` command: Copy curl -L https://downloads.portainer.io/ce-sts/portainer-compose.yaml -o portainer-compose.yaml Alternatively, create a `portainer-compose.yaml` file with the following contents: Copy services: portainer: container_name: portainer image: portainer/portainer-ce:sts restart: always volumes: - /var/run/docker.sock:/var/run/docker.sock - portainer_data:/data ports: - 9443:9443 - 8000:8000 # Remove if you do not intend to use Edge Agents volumes: portainer_data: name: portainer_data networks: default: name: portainer_network Once you have created or downloaded the compose file, you can deploy it with the following command: Copy docker compose -f portainer-compose.yaml up -d Docker Compose will create the necessary resources and deploy Portainer. You can check to see whether the Portainer Server container has started by running `docker ps`: Copy root@server:~# docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 7963585688a9 portainer/portainer-ce:sts "/portainer" 8 seconds ago Up 8 seconds 0.0.0.0:8000->8000/tcp, [::]:8000->8000/tcp, 0.0.0.0:9443->9443/tcp, [::]:9443->9443/tcp, 9000/tcp portainer [](https://docs.portainer.io/sts/start/install-ce/server/docker/linux#logging-in) Logging In ------------------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance by opening a web browser and going to: Copy https://localhost:9443 Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/sts/start/install-ce/server/setup) [PreviousDocker Standalone](https://docs.portainer.io/sts/start/install-ce/server/docker) [NextInstall Portainer CE with Docker on WSL / Docker Desktop](https://docs.portainer.io/sts/start/install-ce/server/docker/wsl) Was this helpful? --- # Install Portainer CE | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Community Edition (CE). For Portainer Business Edition (BE) refer to the [BE install documentation](https://docs.portainer.io/sts/start/install) . Portainer Community Edition is straightforward to install. There are two options: installing new or adding an environment to an existing installation. If you haven't already, please check that your environments meet [our requirements](https://docs.portainer.io/sts/start/requirements-and-prerequisites) before proceeding. [Set up a new Portainer CE Server installation](https://docs.portainer.io/sts/start/install-ce/server) [Add an environment to an existing installation](https://docs.portainer.io/sts/start/agent) [PreviousInitial setup](https://docs.portainer.io/sts/start/install/server/setup) [NextSet up a new Portainer CE Server installation](https://docs.portainer.io/sts/start/install-ce/server) Was this helpful? --- # Initial setup | 2.35 STS | Portainer Documentation Once the Portainer Server has been deployed, and you have navigated to the instance's URL, you are ready for the initial setup. [](https://docs.portainer.io/sts/start/install/server/setup#creating-the-first-user) Creating the first user ----------------------------------------------------------------------------------------------------------------- Your first user will be an administrator. The username defaults to `admin` but you can change it if you prefer. The password must be at least 12 characters long and meet the listed password requirements. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FV3aliie9dZxqejU1vhLc%2F2.32-initial-setup-username.png&width=768&dpr=4&quality=100&sign=b28abdae&sv=2) [](https://docs.portainer.io/sts/start/install/server/setup#enabling-or-disabling-the-collection-of-statistics) Enabling or disabling the collection of statistics ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- We use a tool called [Matomo](https://matomo.org/) to collect anonymous information about how Portainer is used. We recommend enabling this option so we can make improvements based on usage. For more about what we do with the information we collect, read our [privacy policy](https://www.portainer.io/privacy-policy) . During installation, you can enable or disable connection statistics using the checkbox. If you change your mind later, you can easily update this option under [Settings](https://docs.portainer.io/sts/admin/settings/general#allow-the-collection-of-anonymous-statistics) in the Portainer UI. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FmeqIrkMxUAxv4uVzWv44%2F2.15-install-server-setup-matomo.png&width=768&dpr=4&quality=100&sign=fbc6da50&sv=2) [](https://docs.portainer.io/sts/start/install/server/setup#add-your-license-key) Add your license key ----------------------------------------------------------------------------------------------------------- You will now be asked to provide your license key. You will have been provided this when signing up for Business Edition or the free trial. If you don't have a license key, you can either click the **Don't have a license?** link or [get in touch with our team](https://docs.portainer.io/cdn-cgi/l/email-protection#56252335353325251626392422373f383324783f39) . Paste the license key you were provided into the box and click **Submit**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FYZfOBVofTaWkBzMTuk5r%2F2.32-initial-setup-license.png&width=768&dpr=4&quality=100&sign=eb9241f0&sv=2) [](https://docs.portainer.io/sts/start/install/server/setup#connecting-portainer-to-your-environments) Connecting Portainer to your environments ----------------------------------------------------------------------------------------------------------------------------------------------------- Once the admin user has been created, the **Environment Wizard** will automatically launch. The wizard will help get you started with Portainer. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FfeFSHOLYNcOZGosaSVc2%2F2.32-initial-setup-welcome.png&width=768&dpr=4&quality=100&sign=4e2e0b07&sv=2) The installation process automatically detects your local environment and sets it up for you. If you want to add additional environments to manage with this Portainer instance, click **Add Environments**. Otherwise, click **Get Started** to start using Portainer! [PreviousInstall Portainer BE with Kubernetes on WSL / Docker Desktop](https://docs.portainer.io/sts/start/install/server/kubernetes/wsl) [NextInstall Portainer CE](https://docs.portainer.io/sts/start/install-ce) Was this helpful? --- # Docker Standalone | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Community Edition (CE). For Portainer Business Edition (BE) refer to the [BE install documentation](https://docs.portainer.io/sts/start/install/server/docker) . Installation instructions can differ between platforms. Please choose your platform below: [Install Portainer CE with Docker on Linux](https://docs.portainer.io/sts/start/install-ce/server/docker/linux) [Install Portainer CE with Docker on WSL / Docker Desktop](https://docs.portainer.io/sts/start/install-ce/server/docker/wsl) [Install Portainer CE with Docker on Windows Container Service](https://docs.portainer.io/sts/start/install-ce/server/docker/wcs) [PreviousSet up a new Portainer CE Server installation](https://docs.portainer.io/sts/start/install-ce/server) [NextInstall Portainer CE with Docker on Linux](https://docs.portainer.io/sts/start/install-ce/server/docker/linux) Was this helpful? --- # Install Portainer BE with Kubernetes on WSL / Docker Desktop | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/sts/start/install-ce/server/kubernetes/wsl) . [](https://docs.portainer.io/sts/start/install/server/kubernetes/wsl#introduction) Introduction ---------------------------------------------------------------------------------------------------- The following instructions will guide you in setting up _Portainer Server_ with Kubernetes running on Docker Desktop with WSL. This scenario is for testing purposes only. We are aware of an issue where namespace and application access privileges are not fully implemented when running Kubernetes via Docker Desktop. We are looking into the root cause and hope to have a resolution soon. [](https://docs.portainer.io/sts/start/install/server/kubernetes/wsl#preparation) Preparation -------------------------------------------------------------------------------------------------- Before you start, you must make sure that Kubernetes is enabled and running within your Docker Desktop installation. To enable Kubernetes in Docker Desktop, you need to open the dashboard of Docker Desktop. Right click the Docker icon in the system tray and click **Dashboard**: ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FCZmIenUkg1e3kry9S6oN%2Fkube-wsl-1.png&width=768&dpr=4&quality=100&sign=8234ef77&sv=2) Click **Settings**, then select **Kubernetes**, tick **Enable Kubernetes**, then click **Apply and Restart** (clicking **Install** in the dialog to install Kubernetes): ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FULanvTgsC3egXWID5jYf%2Fkube-wsl-2.gif&width=768&dpr=4&quality=100&sign=1fa3a150&sv=2) After a few minutes, you will see that Kubernetes is running in the bottom left status bar of Docker Desktop: ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FYW1PiekvhWqlihBwpB6O%2Fkube-wsl-4.png&width=768&dpr=4&quality=100&sign=41532ab8&sv=2) Docker is on the left, Kubernetes is on the right [](https://docs.portainer.io/sts/start/install/server/kubernetes/wsl#deployment) Deployment ------------------------------------------------------------------------------------------------ To deploy Portainer within a Kubernetes cluster you can use our provided Helm charts or YAML manifests. ### [](https://docs.portainer.io/sts/start/install/server/kubernetes/wsl#deploy-using-helm) Deploy using Helm Ensure you're using at least Helm v3.2, which includes support for the `--create-namespace` argument. First add the Portainer Helm repository by running the following commands: Copy helm repo add portainer https://portainer.github.io/k8s/ helm repo update Once the update completes, you're ready to begin the installation. Which method you choose will depend on how you wish to expose the Portainer service: Expose via NodePort Expose via Ingress Expose via Load Balancer Using the following command, Portainer will be available on port `30777` for HTTP and `30779` for HTTPS: Copy helm upgrade --install --create-namespace -n portainer portainer portainer/portainer \ --set enterpriseEdition.enabled=true \ --set enterpriseEdition.image.tag=lts By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) or [via the Portainer UI](https://app.gitbook.com/admin/settings#ssl-certificate) after installation is complete. In this example, Portainer will be deployed to your cluster and assigned a Cluster IP, with an nginx Ingress Controller at the defined hostname. For more on Ingress options, refer to the list of [Chart Configuration Options](https://docs.portainer.io/sts/advanced/helm-chart-configuration-options) . Copy helm upgrade --install --create-namespace -n portainer portainer portainer/portainer \ --set enterpriseEdition.enabled=true \ --set enterpriseEdition.image.tag=lts \ --set service.type=ClusterIP \ --set tls.force=true \ --set ingress.enabled=true \ --set ingress.ingressClassName= \ --set ingress.annotations."nginx\.ingress\.kubernetes\.io/backend-protocol"=HTTPS \ --set ingress.hosts[0].host= \ --set ingress.hosts[0].paths[0].path="/" Using the following command, Portainer will be available at an assigned Load Balancer IP on port `9000` for HTTP and `9443` for HTTPS: Copy helm upgrade --install --create-namespace -n portainer portainer portainer/portainer \ --set service.type=LoadBalancer \ --set enterpriseEdition.enabled=true \ --set enterpriseEdition.image.tag=lts By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) or [via the Portainer UI](https://app.gitbook.com/admin/settings#ssl-certificate) after installation is complete. To explicitly set the target node when deploying the Helm chart on the CLI, include `--set nodeSelector.kubernetes.io/hostname=` in your `helm install` command. ### [](https://docs.portainer.io/sts/start/install/server/kubernetes/wsl#deploy-using-yaml-manifests) Deploy using YAML manifests Our YAML manifests support exposing Portainer via either NodePort or Load Balancer. Expose via NodePort Expose via Load Balancer To expose via NodePort, you can use the following command (Portainer will be available on port `30777` for HTTP and `30779` for HTTPS): Copy kubectl apply -n portainer -f https://downloads.portainer.io/ee-lts/portainer.yaml By default, Portainer generates and uses a self-signed SSL certificate to secure port `30779`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. To expose via Load Balancer, use the following command to provision Portainer at an assigned Load Balancer IP on port `9000` for HTTP and `9443` for HTTPS: Copy kubectl apply -n portainer -f https://downloads.portainer.io/ee-lts/portainer-lb.yaml By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. To explicitly set the target node when deploying using YAML manifests, run the following one-liner to "patch" the deployment, forcing the pod to always be scheduled on the node it's currently running on: Copy kubectl patch deployments -n portainer portainer -p '{"spec": {"template": {"spec": {"nodeSelector": {"kubernetes.io/hostname": "'$(kubectl get pods -n portainer -o jsonpath='{ ..nodeName }')'"}}}}}' || (echo Failed to identify current node of portainer pod; exit 1) [](https://docs.portainer.io/sts/start/install/server/kubernetes/wsl#logging-in) Logging In ------------------------------------------------------------------------------------------------ Now that the installation is complete, you can log into your Portainer Server instance. Depending on how you chose to expose your Portainer installation, open a web browser and navigate to the following URL: NodePort Ingress Load Balancer Copy https://localhost:30779/ or http://localhost:30777/ Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. Copy https:/// Replace `` with the FQDN of your Portainer instance. Copy https://:9443/ or http://:9000/ Replace `` with the IP address or FQDN of the load balancer, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/sts/start/install/server/setup) [PreviousInstall Portainer BE on your Kubernetes environment](https://docs.portainer.io/sts/start/install/server/kubernetes/baremetal) [NextInitial setup](https://docs.portainer.io/sts/start/install/server/setup) Was this helpful? --- # Install Portainer CE with Docker on WSL / Docker Desktop | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Community Edition (CE). For Portainer Business Edition (BE) refer to the [BE install documentation](https://docs.portainer.io/sts/start/install/server/docker/wsl) . [](https://docs.portainer.io/sts/start/install-ce/server/docker/wsl#introduction) Introduction --------------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_, and the _Portainer Agent_. Both elements run as lightweight Docker containers on a Docker engine. This document will help you install the Portainer Server container on your Windows environment with WSL and Docker Desktop. To add a new WSL / Docker Desktop environment to an existing Portainer Server installation, please refer to the [Portainer Agent installation instructions](https://docs.portainer.io/sts/admin/environments/add/docker/agent) . To get started, you will need: * The latest version of Docker Desktop installed and working. * Administrator access on the machine that will host your Portainer Server instance. * Windows Subsystem for Linux (WSL) installed and a Linux distribution selected. For a new installation we recommend WSL2. * By default, Portainer Server will expose the UI over port `9443` and expose a TCP tunnel server over port `8000`. The latter is optional and is only required if you plan to use the Edge compute features with Edge agents. The installation instructions also make the following assumptions about your environment: * Your environment meets [our requirements](https://docs.portainer.io/sts/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. * You are accessing Docker via Unix sockets. Alternatively, you can also connect via TCP. * SELinux is disabled within the Linux distribution used by WSL. If you require SELinux, you will need to pass the `--privileged` flag to Docker when deploying Portainer. * Docker is running as root. Portainer with rootless Docker has some limitations, and requires additional configuration. [](https://docs.portainer.io/sts/start/install-ce/server/docker/wsl#deployment) Deployment ----------------------------------------------------------------------------------------------- First, create the volume that Portainer Server will use to store its database: Copy docker volume create portainer_data Then, download and install the Portainer Server container: Copy docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:lts By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-docker-standalone) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. If you require HTTP port `9000` open for legacy reasons, add the following to your `docker run` command: `-p 9000:9000` Portainer Server has now been installed. You can check to see whether the Portainer Server container has started by running `docker ps`: Copy root@server:~# docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES f4ab79732007 portainer/portainer-ce:lts "/portainer" 2 weeks ago Up 29 hours 0.0.0.0:8000->8000/tcp, :::8000->8000/tcp, 0.0.0.0:9443->9000/tcp, :::9443->9443/tcp portainer [](https://docs.portainer.io/sts/start/install-ce/server/docker/wsl#logging-in) Logging In ----------------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance by opening a web browser and going to: Copy https://localhost:9443 Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/sts/start/install-ce/server/setup) [PreviousInstall Portainer CE with Docker on Linux](https://docs.portainer.io/sts/start/install-ce/server/docker/linux) [NextInstall Portainer CE with Docker on Windows Container Service](https://docs.portainer.io/sts/start/install-ce/server/docker/wcs) Was this helpful? --- # Set up a new Portainer CE Server installation | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Community Edition (CE). For Portainer Business Edition (BE) refer to the [BE install documentation](https://docs.portainer.io/sts/start/install/server) . Select the environment for your new Portainer installation: [Docker Standalone](https://docs.portainer.io/sts/start/install-ce/server/docker) [Docker Swarm](https://docs.portainer.io/sts/start/install-ce/server/swarm) [Podman](https://docs.portainer.io/sts/start/install-ce/server/podman) [Kubernetes](https://docs.portainer.io/sts/start/install-ce/server/kubernetes) [PreviousInstall Portainer CE](https://docs.portainer.io/sts/start/install-ce) [NextDocker Standalone](https://docs.portainer.io/sts/start/install-ce/server/docker) Was this helpful? --- # Install Portainer BE on your Kubernetes environment | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Business Edition (BE). For Portainer Community Edition (CE) refer to the [CE install documentation](https://docs.portainer.io/sts/start/install-ce/server/kubernetes/baremetal) . [](https://docs.portainer.io/sts/start/install/server/kubernetes/baremetal#introduction) Introduction ---------------------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_ and the _Portainer Agent_. Both elements run as lightweight containers on Kubernetes. To get started, you will need: * A working and up to date Kubernetes cluster. * Access to run `helm` or `kubectl` commands on your cluster. * Cluster Admin rights on your Kubernetes cluster. This is so Portainer can create the necessary `ServiceAccount` and `ClusterRoleBinding` for it to access the Kubernetes cluster. * A `default` StorageClass configured (see below). * A license key for Portainer Business Edition. The installation instructions also make the following assumptions about your environment: * Your environment meets [our requirements](https://docs.portainer.io/sts/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. * Kubernetes RBAC is enabled and working (this is required for the access control functionality in Portainer). * You will be using the `portainer` namespace for Portainer. At present this is a requirement - other namespaces are currently unsupported. * Kubernetes' metrics server is installed and working (if you wish to use the metrics within Portainer). [](https://docs.portainer.io/sts/start/install/server/kubernetes/baremetal#data-persistence) Data Persistence ------------------------------------------------------------------------------------------------------------------ Portainer requires data persistence, and as a result needs at least one StorageClass available to use. Portainer will attempt to use the default StorageClass during deployment. If you do not have a StorageClass tagged as `default` the deployment will likely fail. We recommend using block storage for Kubernetes rather than network storage for the best performance and reliability, but do pay attention to the IOPS of your block storage devices when choosing the volume to use as some options are slower than others. You can check if you have a default StorageClass by running the following command on your cluster: Copy kubectl get sc and looking for a StorageClass with `(default)` after its name: Copy root@kubemaster01:~# kubectl get sc NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE ALLOWVOLUMEEXPANSION AGE managed-nfs-storage (default) k8s-sigs.io/nfs-subdir-external-provisioner Delete Immediate false 11d To set a StorageClass as default, you can use the following: Copy kubectl patch storageclass -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}' replacing `` with the name of your StorageClass. Alternatively, if you are installing using our Helm chart, you can pass the following parameter in your helm install command to specify the StorageClass to use for Portainer: Copy --set persistence.storageClass= In some Kubernetes clusters (for example microk8s), the default StorageClass simply creates hostPath volumes, which are not explicitly tied to a particular node. In a multi-node cluster, this can create an issue when the pod is terminated and rescheduled on a different node, "leaving" all the persistent data behind and starting the pod with an "empty" volume. While this behavior is inherently a limitation of using hostPath volumes, a suitable workaround is to use add a nodeSelector to the deployment, which effectively "pins" the Portainer pod to a particular node. You can do this by editing your own values.yaml file to set the nodeSelector value: `nodeSelector: kubernetes.io/hostname: \` or alternatively follow the instructions below for each deployment method. [](https://docs.portainer.io/sts/start/install/server/kubernetes/baremetal#deployment) Deployment ------------------------------------------------------------------------------------------------------ To deploy Portainer within a Kubernetes cluster you can use our provided Helm charts or YAML manifests. ### [](https://docs.portainer.io/sts/start/install/server/kubernetes/baremetal#deploy-using-helm) Deploy using Helm Ensure you're using at least Helm v3.2, which includes support for the `--create-namespace` argument. First add the Portainer Helm repository by running the following commands: Copy helm repo add portainer https://portainer.github.io/k8s/ helm repo update Once the update completes, you're ready to begin the installation. Which method you choose will depend on how you wish to expose the Portainer service: Expose via NodePort Expose via Ingress Expose via Load Balancer Using the following command, Portainer will be available on port `30779` for HTTPS: Copy helm upgrade --install --create-namespace -n portainer portainer portainer/portainer \ --set enterpriseEdition.enabled=true \ --set enterpriseEdition.image.tag=lts \ --set tls.force=true By default, Portainer generates and uses a self-signed SSL certificate to secure port `30779`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. If you need to access Portainer via HTTP on port `30777`, remove the `--set tls.force=true` option. In this example, Portainer will be deployed to your cluster and assigned a Cluster IP, with an nginx Ingress Controller at the defined hostname. For more on Ingress options, refer to the list of [Chart Configuration Options](https://docs.portainer.io/sts/advanced/helm-chart-configuration-options) . Copy helm upgrade --install --create-namespace -n portainer portainer portainer/portainer \ --set enterpriseEdition.enabled=true \ --set enterpriseEdition.image.tag=lts \ --set service.type=ClusterIP \ --set tls.force=true \ --set ingress.enabled=true \ --set ingress.ingressClassName= \ --set ingress.annotations."nginx\.ingress\.kubernetes\.io/backend-protocol"=HTTPS \ --set ingress.hosts[0].host= \ --set ingress.hosts[0].paths[0].path="/" If you need to access Portainer via HTTP, remove the `--set tls.force=true` option. Using the following command, Portainer will be available at an assigned Load Balancer IP on port `9443` for HTTPS: Copy helm upgrade --install --create-namespace -n portainer portainer portainer/portainer \ --set service.type=LoadBalancer \ --set enterpriseEdition.enabled=true \ --set enterpriseEdition.image.tag=lts \ --set tls.force=true By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. If you need to access Portainer via HTTP on port `9000`, remove the `--set tls.force=true` option. If you want to explicitly set the target node when deploying the Helm chart on the CLI, include `--set nodeSelector.kubernetes\.io/hostname=` in your `helm install` command. ### [](https://docs.portainer.io/sts/start/install/server/kubernetes/baremetal#deploy-using-yaml-manifests) Deploy using YAML manifests Our YAML manifests support exposing Portainer via either NodePort or Load Balancer. Expose via NodePort Expose via Load Balancer To expose via NodePort, you can use the following command (Portainer will be available on port `30777` for HTTP and `30779` for HTTPS): Copy kubectl apply -n portainer -f https://downloads.portainer.io/ee-lts/portainer.yaml By default, Portainer generates and uses a self-signed SSL certificate to secure port `30779`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. To expose via Load Balancer, use the following command to provision Portainer at an assigned Load Balancer IP on port `9000` for HTTP and `9443` for HTTPS: Copy kubectl apply -n portainer -f https://downloads.portainer.io/ee-lts/portainer-lb.yaml By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. If you want to explicitly set the target node when deploying using YAML manifests, run the following one-liner to "patch" the deployment, forcing the pod to always be scheduled on the node it's currently running on: Copy kubectl patch deployments -n portainer portainer -p '{"spec": {"template": {"spec": {"nodeSelector": {"kubernetes.io/hostname": "'$(kubectl get pods -n portainer -o jsonpath='{ ..nodeName }')'"}}}}}' || (echo Failed to identify current node of portainer pod; exit 1) [](https://docs.portainer.io/sts/start/install/server/kubernetes/baremetal#logging-in) Logging In ------------------------------------------------------------------------------------------------------ Now that the installation is complete, you can log into your Portainer Server instance. Depending on how you chose to expose your Portainer installation, open a web browser and navigate to the following URL: NodePort Ingress Load Balancer Copy https://localhost:30779/ or http://localhost:30777/ Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. Copy https:/// Replace `` with the FQDN of your Portainer instance. Copy https://:9443/ or http://:9000/ Replace `` with the IP address or FQDN of the load balancer, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/sts/start/install/server/setup) [PreviousKubernetes](https://docs.portainer.io/sts/start/install/server/kubernetes) [NextInstall Portainer BE with Kubernetes on WSL / Docker Desktop](https://docs.portainer.io/sts/start/install/server/kubernetes/wsl) Was this helpful? --- # Install Portainer CE with Docker on Windows Container Service | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Community Edition (CE). For Portainer Business Edition (BE) refer to the [BE install documentation](https://docs.portainer.io/sts/start/install/server/docker/wcs) . [](https://docs.portainer.io/sts/start/install-ce/server/docker/wcs#introduction) Introduction --------------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_, and the _Portainer Agent_. Both elements run as lightweight Docker containers on a Docker engine. This document will help you install the Portainer Server container on your Windows server with Windows Containers. To add a new WCS environment to an existing Portainer Server installation, please refer to the [Portainer Agent installation instructions](https://docs.portainer.io/sts/admin/environments/add/docker/agent) . To get started, you will need: * Administrator access on the machine that will host your Portainer Server instance * By default, Portainer Server will expose the UI over port `9443` and expose a TCP tunnel server over port `8000`. The latter is optional and is only required if you plan to use the Edge compute features with Edge agents. The installation instructions also make the following assumption about your environment: * Your environment meets [our requirements](https://docs.portainer.io/sts/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. [](https://docs.portainer.io/sts/start/install-ce/server/docker/wcs#preparation) Preparation ------------------------------------------------------------------------------------------------- To run Portainer Server in a Windows Server/Desktop Environment you need to create exceptions in the firewall. These can easily be added through PowerShell by running the following commands: Copy netsh advfirewall firewall add rule name="cluster_management" dir=in action=allow protocol=TCP localport=2377 netsh advfirewall firewall add rule name="node_communication_tcp" dir=in action=allow protocol=TCP localport=7946 netsh advfirewall firewall add rule name="node_communication_udp" dir=in action=allow protocol=UDP localport=7946 netsh advfirewall firewall add rule name="overlay_network" dir=in action=allow protocol=UDP localport=4789 netsh advfirewall firewall add rule name="swarm_dns_tcp" dir=in action=allow protocol=TCP localport=53 netsh advfirewall firewall add rule name="swarm_dns_udp" dir=in action=allow protocol=UDP localport=53 You will also need to install the Windows Container Host Service and install Docker. Microsoft have [provided](https://learn.microsoft.com/en-us/virtualization/windowscontainers/quick-start/set-up-environment?tabs=dockerce#windows-server-1) a PowerShell script to perform the necessary actions. You can download the script and run it with the following commands: Copy Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/microsoft/Windows-Containers/Main/helpful_tools/Install-DockerCE/install-docker-ce.ps1" -o install-docker-ce.ps1 .\install-docker-ce.ps1 Once this is complete you will need to restart your Windows server. After the restart completes, you're ready to install Portainer itself. [](https://docs.portainer.io/sts/start/install-ce/server/docker/wcs#deployment) Deployment ----------------------------------------------------------------------------------------------- First, create the volume that Portainer Server will use to store its database. Using PowerShell: Copy docker volume create portainer_data Then, download and install the Portainer Server container: Copy docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart always -v \\.\pipe\docker_engine:\\.\pipe\docker_engine -v portainer_data:C:\data portainer/portainer-ce:lts By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. If you see an error message similar to: `"\\.\pipe\dockerDesktopEngine" includes invalid characters for a local volume name` then you may not have Windows containers properly enabled. If you are using Docker Desktop, right click the icon in your tray and select **Switch to Windows Containers**. If you require HTTP port `9000` open for legacy reasons, add the following to your `docker run` command: `-p 9000:9000` [](https://docs.portainer.io/sts/start/install-ce/server/docker/wcs#logging-in) Logging In ----------------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance by opening a web browser and going to: Copy https://localhost:9443 Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/sts/start/install-ce/server/setup) [PreviousInstall Portainer CE with Docker on WSL / Docker Desktop](https://docs.portainer.io/sts/start/install-ce/server/docker/wsl) [NextDocker Swarm](https://docs.portainer.io/sts/start/install-ce/server/swarm) Was this helpful? --- # Install Portainer CE with Docker Swarm on Linux | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Community Edition (CE). For Portainer Business Edition (BE) refer to the [BE install documentation](https://docs.portainer.io/sts/start/install/server/swarm/linux) . [](https://docs.portainer.io/sts/start/install-ce/server/swarm/linux#introduction) Introduction ---------------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_ and the _Portainer Agent_. Both elements run as lightweight Docker containers on a Docker engine. This document will help you deploy the Portainer Server and Agent containers on your Linux environment. To add a new Linux Swarm environment to an existing Portainer Server installation, please refer to the [Portainer Agent installation instructions](https://docs.portainer.io/sts/admin/environments/add/swarm/agent) . To get started, you will need: * The latest version of Docker installed and working. We recommend following the [official installation instructions](https://docs.docker.com/engine/install/) for Docker - in particular, we advise _against_ installing Docker via snap on Ubuntu distributions as you may run into compatibility issues. * Swarm mode [enabled](https://docs.docker.com/engine/swarm/swarm-mode/) and working, including the overlay network for the swarm service communication * `sudo` access on the manager node of your swarm cluster * By default, Portainer will expose the UI over port `9443` and expose a TCP tunnel server over port `8000`. The latter is optional and is only required if you plan to use the Edge compute features with Edge agents. * The manager and worker nodes must be able to communicate with each other over port `9001`. The installation instructions also make the following assumptions about your environment: * Your environment meets [our requirements](https://docs.portainer.io/sts/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. * You are accessing Docker via Unix sockets. Connecting via TCP is not supported in Docker Swarm. * SELinux is disabled on the machine running Docker. * Docker is running as root. Portainer with rootless Docker has some limitations, and requires additional configuration. * You are running a single manager node in your swarm. If you have more than one, please [read this article](https://docs.portainer.io/sts/faqs/installing/how-can-i-ensure-portainers-configuration-is-retained) before proceeding. * If your nodes are using DNS records to communicate, that all records are resolvable across the cluster. [](https://docs.portainer.io/sts/start/install-ce/server/swarm/linux#deployment) Deployment ------------------------------------------------------------------------------------------------ Portainer can be directly deployed as a service in your Docker cluster. Note that this method will automatically deploy a single instance of the Portainer Server, and deploy the Portainer Agent as a global service on every node in your cluster. Only do this **once** for your environment, regardless of how many nodes are in the cluster. You **do not** need to add each node in your cluster as a separate environment in Portainer. Deploying the manifest to your swarm will include every node in the cluster automatically. Adding each node as a separate environment will also consume more of your licensed node count than you may expect. First, retrieve the stack YML manifest: Copy curl -L https://downloads.portainer.io/ce-lts/portainer-agent-stack.yml -o portainer-agent-stack.yml Then use the downloaded YML manifest to deploy your stack: Copy docker stack deploy -c portainer-agent-stack.yml portainer By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-docker-swarm) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. Portainer Server and the Agents have now been installed. You can check to see whether the Portainer Server and Agent containers have started by running `docker ps`: Copy root@manager01:~# docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 59ee466f6b15 portainer/agent:lts "./agent" About a minute ago Up About a minute portainer_agent.xbb8k6r7j1tk9gozjku7e43wr.5sa6b3e8cl6hyu0snlt387sgv 2db7dd4bfba0 portainer/portainer-ce:lts "/portainer -H tcp:/…" About a minute ago Up About a minute 8000/tcp, 9443/tcp portainer_portainer.1.gpuvu3pqmt1m19zxfo44v7izx [](https://docs.portainer.io/sts/start/install-ce/server/swarm/linux#logging-in) Logging In ------------------------------------------------------------------------------------------------ Now that the installation is complete, you can log into your Portainer Server instance by opening a web browser and going to: Copy https://localhost:9443 Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/sts/start/install-ce/server/setup) [PreviousDocker Swarm](https://docs.portainer.io/sts/start/install-ce/server/swarm) [NextInstall Portainer CE with Docker Swarm on WSL / Docker Desktop](https://docs.portainer.io/sts/start/install-ce/server/swarm/wsl) Was this helpful? --- # Docker Swarm | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Community Edition (CE). For Portainer Business Edition (BE) refer to the [BE install documentation](https://docs.portainer.io/sts/start/install/server/swarm) . Installation instructions can differ between platforms. Please choose your platform below: [Install Portainer CE with Docker Swarm on Linux](https://docs.portainer.io/sts/start/install-ce/server/swarm/linux) [Install Portainer CE with Docker Swarm on WSL / Docker Desktop](https://docs.portainer.io/sts/start/install-ce/server/swarm/wsl) [Install Portainer CE with Docker Swarm on Windows Container Service](https://docs.portainer.io/sts/start/install-ce/server/swarm/wcs) [PreviousInstall Portainer CE with Docker on Windows Container Service](https://docs.portainer.io/sts/start/install-ce/server/docker/wcs) [NextInstall Portainer CE with Docker Swarm on Linux](https://docs.portainer.io/sts/start/install-ce/server/swarm/linux) Was this helpful? --- # Install Portainer CE with Docker Swarm on Windows Container Service | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Community Edition (CE). For Portainer Business Edition (BE) refer to the [BE install documentation](https://docs.portainer.io/sts/start/install/server/swarm/wcs) . [](https://docs.portainer.io/sts/start/install-ce/server/swarm/wcs#introduction) Introduction -------------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_, and the _Portainer Agent_. Both elements run as lightweight Docker containers on a Docker engine. This document will help you install the Portainer Server container on your Windows server with Windows Containers. To add a new WCS environment to an existing Portainer Server installation, please refer to the [Portainer Agent installation instructions](https://docs.portainer.io/sts/admin/environments/add/swarm/agent) . To get started, you will need: * The latest version of Docker installed and working. * Swarm mode [enabled](https://docs.docker.com/engine/swarm/swarm-mode/) and working, including the overlay network for the swarm service communication. * Administrator access on the manager node of your Swarm cluster. * By default, Portainer will expose the UI over port `9443` and expose a TCP tunnel server over port `8000`. The latter is optional and is only required if you plan to use the Edge compute features with Edge agents. * The manager and worker nodes must be able to communicate with each other over port `9001`. The installation instructions also make the following assumptions about your environment: * Your environment meets [our requirements](https://docs.portainer.io/sts/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. * You are running a single manager node in your swarm. If you have more than one, please [read this article](https://docs.portainer.io/sts/faqs/installing/how-can-i-ensure-portainers-configuration-is-retained) before proceeding. * If your nodes are using DNS records to communicate, that all records are resolvable across the cluster. [](https://docs.portainer.io/sts/start/install-ce/server/swarm/wcs#preparation) Preparation ------------------------------------------------------------------------------------------------ To run Portainer Server in a Windows Server/Desktop Environment you need to create exceptions in the firewall. These can easily be added through PowerShell by running the following commands: Copy netsh advfirewall firewall add rule name="cluster_management" dir=in action=allow protocol=TCP localport=2377 netsh advfirewall firewall add rule name="node_communication_tcp" dir=in action=allow protocol=TCP localport=7946 netsh advfirewall firewall add rule name="node_communication_udp" dir=in action=allow protocol=UDP localport=7946 netsh advfirewall firewall add rule name="overlay_network" dir=in action=allow protocol=UDP localport=4789 netsh advfirewall firewall add rule name="swarm_dns_tcp" dir=in action=allow protocol=TCP localport=53 netsh advfirewall firewall add rule name="swarm_dns_udp" dir=in action=allow protocol=UDP localport=53 You will also need to install the Windows Container Host Service and install Docker. Microsoft have [provided](https://learn.microsoft.com/en-us/virtualization/windowscontainers/quick-start/set-up-environment?tabs=dockerce#windows-server-1) a PowerShell script to perform the necessary actions. You can download the script and run it with the following commands: Copy Invoke-WebRequest -UseBasicParsing "https://raw.githubusercontent.com/microsoft/Windows-Containers/Main/helpful_tools/Install-DockerCE/install-docker-ce.ps1" -o install-docker-ce.ps1 .\install-docker-ce.ps1 Once this is complete you will need to restart your Windows server. After the restart completes, you're ready to install Portainer itself. [](https://docs.portainer.io/sts/start/install-ce/server/swarm/wcs#deployment) Deployment ---------------------------------------------------------------------------------------------- Portainer can be directly deployed as a service in your Docker cluster. Note that this method will automatically deploy a single instance of the Portainer Server, and deploy the Portainer Agent as a global service on every node in your cluster. Only do this **once** for your environment, regardless of how many nodes are in the cluster. You **do not** need to add each node in your cluster as a separate environment in Portainer. Deploying the manifest to your swarm will include every node in the cluster automatically. Adding each node as a separate environment will also consume more of your licensed node count than you may expect. You can use our YML manifest to run Portainer in Windows using Windows Containers. In PowerShell, run: Copy curl https://downloads.portainer.io/ce-lts/portainer_windows_stack.yml -o portainer-windows-stack.yml Then use the downloaded YML manifest to deploy your stack: Copy docker stack deploy --compose-file=portainer-windows-stack.yml portainer By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-docker-swarm) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. [](https://docs.portainer.io/sts/start/install-ce/server/swarm/wcs#logging-in) Logging In ---------------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance by opening a web browser and going to: Copy https://localhost:9443 Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/sts/start/install-ce/server/setup) [PreviousInstall Portainer CE with Docker Swarm on WSL / Docker Desktop](https://docs.portainer.io/sts/start/install-ce/server/swarm/wsl) [NextPodman](https://docs.portainer.io/sts/start/install-ce/server/podman) Was this helpful? --- # Install Portainer CE with Docker Swarm on WSL / Docker Desktop | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Community Edition (CE). For Portainer Business Edition (BE) refer to the [BE install documentation](https://docs.portainer.io/sts/start/install/server/swarm/wsl) . [](https://docs.portainer.io/sts/start/install-ce/server/swarm/wsl#introduction) Introduction -------------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_, and the _Portainer Agent_. Both elements run as lightweight Docker containers on a Docker engine. This document will help you install the Portainer Server container on your Windows environment with WSL and Docker Desktop. To add a new WSL / Docker Desktop Swarm environment to an existing Portainer Server installation, please refer to the [Portainer Agent installation instructions](https://docs.portainer.io/sts/admin/environments/add/swarm/agent) . To get started, you will need: * The latest version of Docker Desktop installed and working. * Swarm mode [enabled](https://docs.docker.com/engine/swarm/swarm-mode/) and working, including the overlay network for the swarm service communication. * Administrator access on the manager node of your Swarm cluster. * Windows Subsystem for Linux (WSL) installed and a Linux distribution selected. For a new installation we recommend WSL2. * By default, Portainer will expose the UI over port `9443` and expose a TCP tunnel server over port `8000`. The latter is optional and is only required if you plan to use the Edge compute features with Edge agents. * The manager and worker nodes must be able to communicate with each other over port `9001`. The installation instructions also make the following assumptions about your environment: * Your environment meets [our requirements](https://docs.portainer.io/sts/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. * You are accessing Docker via Unix sockets. Alternatively, you can also connect via TCP. * SELinux is disabled within the Linux distribution used by WSL. * Docker is running as root. Portainer with rootless Docker has some limitations, and requires additional configuration. * You are running a single manager node in your swarm. If you have more than one, please [read this article](https://docs.portainer.io/sts/faqs/installing/how-can-i-ensure-portainers-configuration-is-retained) before proceeding. * If your nodes are using DNS records to communicate, that all records are resolvable across the cluster. [](https://docs.portainer.io/sts/start/install-ce/server/swarm/wsl#deployment) Deployment ---------------------------------------------------------------------------------------------- Portainer can be directly deployed as a service in your Docker Swarm cluster. Note that this method will automatically deploy a single instance of the Portainer Server, and deploy the Portainer Agent as a global service on every node in your cluster. Only do this **once** for your environment, regardless of how many nodes are in the cluster. You **do not** need to add each node in your cluster as a separate environment in Portainer. Deploying the manifest to your swarm will include every node in the cluster automatically. Adding each node as a separate environment will also consume more of your licensed node count than you may expect. To begin the installation, first retrieve the stack YML manifest: Copy curl -L https://downloads.portainer.io/ce-lts/portainer-agent-stack.yml -o portainer-agent-stack.yml Then use the downloaded YML manifest to deploy your stack: Copy docker stack deploy -c portainer-agent-stack.yml portainer By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-docker-swarm) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. [](https://docs.portainer.io/sts/start/install-ce/server/swarm/wsl#logging-in) Logging In ---------------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance by opening a web browser and going to: Copy https://localhost:9443 Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/sts/start/install-ce/server/setup) [PreviousInstall Portainer CE with Docker Swarm on Linux](https://docs.portainer.io/sts/start/install-ce/server/swarm/linux) [NextInstall Portainer CE with Docker Swarm on Windows Container Service](https://docs.portainer.io/sts/start/install-ce/server/swarm/wcs) Was this helpful? --- # Podman | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Community Edition (CE). For Portainer Business Edition (BE) refer to the [BE install documentation](https://docs.portainer.io/sts/start/install/server/podman) . Installation instructions can differ between platforms. Please choose your platform below: [Install Portainer CE with Podman on Linux](https://docs.portainer.io/sts/start/install-ce/server/podman/linux) [PreviousInstall Portainer CE with Docker Swarm on Windows Container Service](https://docs.portainer.io/sts/start/install-ce/server/swarm/wcs) [NextInstall Portainer CE with Podman on Linux](https://docs.portainer.io/sts/start/install-ce/server/podman/linux) Was this helpful? --- # Install Portainer CE with Podman on Linux | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Community Edition (CE). For Portainer Business Edition (BE) refer to the [BE install documentation](https://docs.portainer.io/sts/start/install/server/podman/linux) . [](https://docs.portainer.io/sts/start/install-ce/server/podman/linux#introduction) Introduction ----------------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_, and the _Portainer Agent_. Both elements run as lightweight containers on a Podman engine. This document will help you install the Portainer Server container on your Linux environment. To add a new Linux environment to an existing Portainer Server installation, please refer to the [Portainer Agent installation instructions](https://docs.portainer.io/sts/admin/environments/add/podman/agent) . To get started, you will need: * CentOS 9 with the latest version of Podman 5.x installed and working on your Podman host. Other Podman versions and Linux distros may work but we currently only support the above. We recommend following the [official installation instructions](https://podman.io/docs/installation#installing-on-linux) for Podman. * sudo access on the machine that will host your Portainer Server instance * By default, Portainer Server will expose the UI over port `9443` and expose a TCP tunnel server over port `8000`. The latter is optional and is only required if you plan to use the Edge compute features with Edge agents. The installation instructions also make the following assumptions about your environment: * Your environment meets [our requirements](https://docs.portainer.io/sts/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. * You are accessing Podman via Unix sockets. * Podman is running as root. Portainer with rootless Podman may work but is currently not officially supported. [](https://docs.portainer.io/sts/start/install-ce/server/podman/linux#deployment) Deployment ------------------------------------------------------------------------------------------------- First, ensure the Podman socket is enabled: Copy systemctl enable --now podman.socket Next, create the volume that Portainer Server will use to store its database: Copy podman volume create portainer_data Then, download and install the Portainer Server container: Copy podman run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always --privileged -v /run/podman/podman.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:lts By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-docker-standalone) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. If you require HTTP port `9000` open for legacy reasons, add the following to your `podman run` command: `-p 9000:9000` Portainer Server has now been installed. You can check to see whether the Portainer Server container has started by running `podman ps`: Copy root@server:~# podman ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES de5b28eb2fa9 portainer/portainer-ce:lts "/portainer" 2 weeks ago Up 9 days 0.0.0.0:8000->8000/tcp, :::8000->8000/tcp, 0.0.0.0:9443->9443/tcp, :::9443->9443/tcp portainer [](https://docs.portainer.io/sts/start/install-ce/server/podman/linux#logging-in) Logging In ------------------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance by opening a web browser and going to: Copy https://localhost:9443 Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/sts/start/install-ce/server/setup) [PreviousPodman](https://docs.portainer.io/sts/start/install-ce/server/podman) [NextKubernetes](https://docs.portainer.io/sts/start/install-ce/server/kubernetes) Was this helpful? --- # Initial setup | 2.35 STS | Portainer Documentation Once the Portainer Server has been deployed, and you have navigated to the instance's URL, you are ready for the initial setup. [](https://docs.portainer.io/sts/start/install-ce/server/setup#creating-the-first-user) Creating the first user -------------------------------------------------------------------------------------------------------------------- Your first user will be an administrator. The username defaults to `admin` but you can change it if you prefer. The password must be at least 12 characters long and meet the listed password requirements. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FV3aliie9dZxqejU1vhLc%2F2.32-initial-setup-username.png&width=768&dpr=4&quality=100&sign=b28abdae&sv=2) [](https://docs.portainer.io/sts/start/install-ce/server/setup#enabling-or-disabling-the-collection-of-statistics) Enabling or disabling the collection of statistics -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- We use a tool called [Matomo](https://matomo.org/) to collect anonymous information about how Portainer is used. We recommend enabling this option so we can make improvements based on usage. For more about what we do with the information we collect, read our [privacy policy](https://www.portainer.io/privacy-policy) . During installation, you can enable or disable connection statistics using the checkbox. If you change your mind later, you can easily update this option under [Settings](https://docs.portainer.io/sts/admin/settings/general#allow-the-collection-of-anonymous-statistics) in the Portainer UI. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FmeqIrkMxUAxv4uVzWv44%2F2.15-install-server-setup-matomo.png&width=768&dpr=4&quality=100&sign=fbc6da50&sv=2) [](https://docs.portainer.io/sts/start/install-ce/server/setup#connecting-portainer-to-your-environments) Connecting Portainer to your environments -------------------------------------------------------------------------------------------------------------------------------------------------------- Once the admin user has been created, the **Environment Wizard** will automatically launch. The wizard will help get you started with Portainer. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FKszis9V73l4baaFULTvS%2F2.32-initial-setup-welcome-ce.png&width=768&dpr=4&quality=100&sign=ab2fc1df&sv=2) The installation process automatically detects your local environment and sets it up for you. If you want to add additional environments to manage with this Portainer instance, click **Add Environments**. Otherwise, click **Get Started** to start using Portainer! [PreviousInstall Portainer CE with Kubernetes on WSL / Docker Desktop](https://docs.portainer.io/sts/start/install-ce/server/kubernetes/wsl) [NextAdd an environment to an existing installation](https://docs.portainer.io/sts/start/agent) Was this helpful? --- # Add an environment to an existing installation | 2.35 STS | Portainer Documentation If you want to add another environment to your existing Portainer installation, first select the type of environment you would like to add. You can choose to connect to existing environments: [](https://docs.portainer.io/sts/admin/environments/add/docker) ![Cover](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FYwGynRLHn54gC18CZ7Fu%2Fcard-docker.png&width=490&dpr=4&quality=100&sign=a7aed3c2&sv=2) **Docker Standalone** Connect to Docker Standalone via URL/IP, API or Socket [](https://docs.portainer.io/sts/admin/environments/add/swarm) ![Cover](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FYwGynRLHn54gC18CZ7Fu%2Fcard-docker.png&width=490&dpr=4&quality=100&sign=a7aed3c2&sv=2) **Docker Swarm** Connect to Docker Swarm via URL/IP, API or Socket [](https://docs.portainer.io/sts/admin/environments/add/kubernetes) ![Cover](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FJdFxBG34cPIlXLr9iNFB%2Fcard-kubernetes.png&width=490&dpr=4&quality=100&sign=3727e21f&sv=2) **Kubernetes** Connect to a Kubernetes environment via URL/IP or via kubeconfig import [](https://docs.portainer.io/sts/admin/environments/add/podman) ![Cover](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2Fiq0lK98ZSD00kt0Zqt1V%2Fpodman-logo-tile.png&width=490&dpr=4&quality=100&sign=b312dd8a&sv=2) **Podman** Connect to a Podman environment via URL/IP or Socket [](https://docs.portainer.io/sts/admin/environments/add/aci) ![Cover](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FcjpG9m9Ts8ipQ0LPW1qm%2Fcard-aci.png&width=490&dpr=4&quality=100&sign=1c05d78a&sv=2) **Azure ACI** Connect to an Azure ACI environment via API Or alternatively set up new environments: [](https://docs.portainer.io/sts/admin/environments/add/kaas) ![Cover](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2Fy1QcLOQ7VT6jVy9AMmdS%2Fcard-kaas-large.png&width=752&dpr=4&quality=100&sign=df0e9996&sv=2) **Provision KaaS Cluster** Provision a Kubernetes cluster via a cloud provider's Kubernetes as a Service [](https://docs.portainer.io/sts/admin/environments/add/kube-create) ![Cover](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F4yxsRb3DJuTlx9R273m6%2Fcard-kube-create-large.png&width=752&dpr=4&quality=100&sign=e6176e55&sv=2) **Create a Kubernetes cluster** Create a Kubernetes cluster on existing infrastructure [PreviousInitial setup](https://docs.portainer.io/sts/start/install-ce/server/setup) [NextUpdating Portainer](https://docs.portainer.io/sts/start/upgrade) Was this helpful? --- # Updating Portainer | 2.35 STS | Portainer Documentation Portainer releases contain new features and bug fixes so it's important to keep your installation up to date. We have [tested and validated](https://docs.portainer.io/sts/start/requirements-and-prerequisites#valid-configurations) all Portainer version upgrades from 2.0.0 up to the latest release. While it's possible that an untested unvalidated update path might work, we recommend that all update paths are tested and validated on a non-critical system before applying them to your production systems. We added a [backup and restore feature](https://docs.portainer.io/sts/admin/settings#backup-portainer) to Portainer BE 2.7 and strongly recommend that you take a backup of your Portainer instance before updating. Starting with CE 2.9 and BE 2.10 Portainer is HTTPS enabled by default and uses port `9443` to serve the UI. HTTP can still be enabled on port `9000` if required. [](https://docs.portainer.io/sts/start/upgrade#update-order) Update order ------------------------------------------------------------------------------ In general, we recommend updating your Portainer Server deployment _before_ you update the Portainer Agents. When we release new versions of Portainer we ensure that Portainer Server is able to talk to older versions of the Agent, and in most cases the reverse is true, but in some instances we make changes to the Agent that are not fully backward compatible with older versions of Portainer Server. [](https://docs.portainer.io/sts/start/upgrade#updating-portainer) Updating Portainer ------------------------------------------------------------------------------------------ ### [](https://docs.portainer.io/sts/start/upgrade#from-within-portainer) From within Portainer Updating from within Portainer to STS versions (or within STS versions) is currently not available. Only LTS versions will be offered through the in-app update. To switch to or update to STS versions, follow the [manual instructions](https://docs.portainer.io/sts/start/upgrade#manually-update-portainer) below. From 2.19, Business Edition users are able to update their Portainer installation directly from within Portainer. To do so, click the **Update now** link in the update notification in the bottom left of the Portainer UI. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FKdRu75vKpMY8LTfzMzX0%2F2.19-update-notification.png&width=768&dpr=4&quality=100&sign=89f8a1f0&sv=2) In the confirmation dialog, click **Start update** to proceed with the update. Remember to [back up your Portainer installation](https://docs.portainer.io/sts/admin/settings#backup-portainer) before updating! ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F92BHI34KM7XOjeGmKCS6%2F2.19-update-confirmation.png&width=768&dpr=4&quality=100&sign=c7638f75&sv=2) ### [](https://docs.portainer.io/sts/start/upgrade#manually-update-portainer) Manually update Portainer If you would prefer to manually update your Portainer installation, choose your platform then follow the instructions: [Updating on Docker Standalone](https://docs.portainer.io/sts/start/upgrade/docker) [Updating on Docker Swarm](https://docs.portainer.io/sts/start/upgrade/swarm) [Updating on Podman](https://docs.portainer.io/sts/start/upgrade/podman) [Updating on Kubernetes](https://docs.portainer.io/sts/start/upgrade/kubernetes) ### [](https://docs.portainer.io/sts/start/upgrade#update-the-portainer-agent) Update the Portainer Agent To update the standard (non-Edge) Portainer Agent, you can find instructions in the above platform-specific links ([Docker Standalone](https://docs.portainer.io/sts/start/upgrade/docker#agent-only-upgrade) , [Docker Swarm](https://docs.portainer.io/sts/start/upgrade/swarm) , [Podman](https://docs.portainer.io/sts/start/upgrade/podman) and [Kubernetes](https://docs.portainer.io/sts/start/upgrade/kubernetes) ). If you are using the Portainer Edge Agent, we have specific update instructions for you: [Updating the Edge Agent](https://docs.portainer.io/sts/start/upgrade/edge) ### [](https://docs.portainer.io/sts/start/upgrade#upgrading-to-business-edition) Upgrading to Business Edition If you are coming from Portainer CE or the 1.24.x branch, we have guides for you as well. [Switching to Portainer Business Edition](https://docs.portainer.io/sts/start/upgrade/tobe) [PreviousAdd an environment to an existing installation](https://docs.portainer.io/sts/start/agent) [NextUpdating on Docker Standalone](https://docs.portainer.io/sts/start/upgrade/docker) Was this helpful? --- # Kubernetes | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Community Edition (CE). For Portainer Business Edition (BE) refer to the [BE install documentation](https://docs.portainer.io/sts/start/install/server/kubernetes) . Installation instructions can differ between platforms. Please choose your platform below: [Install Portainer CE on your Kubernetes environment](https://docs.portainer.io/sts/start/install-ce/server/kubernetes/baremetal) [Install Portainer CE with Kubernetes on WSL / Docker Desktop](https://docs.portainer.io/sts/start/install-ce/server/kubernetes/wsl) [PreviousInstall Portainer CE with Podman on Linux](https://docs.portainer.io/sts/start/install-ce/server/podman/linux) [NextInstall Portainer CE on your Kubernetes environment](https://docs.portainer.io/sts/start/install-ce/server/kubernetes/baremetal) Was this helpful? --- # Updating on Nomad | 2.35 STS | Portainer Documentation In our ongoing efforts to refine and optimize Portainer, we have made the decision to discontinue support for HashiCorp Nomad as an environment type from Portainer version 2.20.0. This decision is based on limited user adoption and the considerable development resources required to maintain Nomad support. [PreviousUpdating on Kubernetes](https://docs.portainer.io/sts/start/upgrade/kubernetes) [NextUpdating the Edge Agent](https://docs.portainer.io/sts/start/upgrade/edge) Was this helpful? --- # Updating on Docker Standalone | 2.35 STS | Portainer Documentation Always match the agent version to the Portainer Server version. In other words, when you're installing or updating to Portainer 2.35.0 make sure all of the agents are also on version 2.35.0. If you are updating from the 1.x version of Portainer, you **must** first [update to 2.0.0](https://docs.portainer.io/sts/start/upgrade/from-1.x) **before** updating to the newest version or you will run into issues. Before beginning any update, we highly recommend [taking a backup](https://docs.portainer.io/sts/admin/settings/general#back-up-portainer) of your current Portainer configuration. [](https://docs.portainer.io/sts/start/upgrade/docker#updating-your-portainer-server) Updating your Portainer Server ------------------------------------------------------------------------------------------------------------------------- Starting from Portainer CE 2.9 and BE 2.10, HTTPS is enabled by default on port `9443.` These instructions will configure Portainer to use 9443 for HTTPS and do not expose 9000 for HTTP. If you need to retain HTTP access, you can add: `-p 9000:9000` to your command. You can also choose to [completely disable HTTP](https://github.com/portainer/portainer-docs/blob/2.21/admin/settings/general/README.md#force-https-only) after the update. Before you make Portainer HTTPS only, make sure you have all your Agents and Edge Agents already communicating with Portainer using HTTPS. This article assumes that you used our recommended deployment scripts. To update to the latest version of Portainer Server, use the following commands to stop then remove the old version. Your other applications/containers will not be removed. Copy docker stop portainer Copy docker rm portainer Now that you have stopped and removed the old version of Portainer, you must ensure that you have the most up to date version of the image locally. You can do this with a `docker pull` command: Business Edition Community Edition Copy docker pull portainer/portainer-ee:sts Copy docker pull portainer/portainer-ce:sts Finally, deploy the updated version of Portainer: Business Edition Community Edition Copy docker run -d -p 8000:8000 -p 9443:9443 --name=portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ee:sts Copy docker run -d -p 8000:8000 -p 9443:9443 --name=portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:sts These `docker run` commands include opening port `8000` which is used for Edge Agent communication as included in our [installation instructions](https://docs.portainer.io/sts/start/install/server/docker/linux) . If you do not need this port open, you can remove it from the command. To provide your own SSL certs you may use `--sslcert` and `--sslkey` flags as below to provide the certificate and key files. The certificate file needs to be the full chain and in PEM format. For example, for Business Edition: Copy docker run -d -p 8000:8000 -p 9443:9443 --name=portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ee:sts --sslcert /path/to/cert/portainer.crt --sslkey /path/to/cert/portainer.key The newest version of Portainer will now be deployed on your system, using the persistent data from the previous version, and will also upgrade the Portainer database to the new version. When the deployment is finished, go to `https://your-server-address:9443` or `http://your-server-address:9000` and log in. You should notice that the update notification has disappeared and the version number has been updated. [](https://docs.portainer.io/sts/start/upgrade/docker#agent-only-update) Agent-only update ----------------------------------------------------------------------------------------------- To update to the latest version of Portainer Agent, use the following commands to stop then remove the old version. Your other applications/containers will not be removed. Copy docker stop portainer_agent Copy docker rm portainer_agent Next, pull the updated version of the image: Copy docker pull portainer/agent:sts Finally, start the agent with the updated image: Copy docker run -d -p 9001:9001 --name portainer_agent --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v /var/lib/docker/volumes:/var/lib/docker/volumes portainer/agent:sts If you have set a custom `AGENT_SECRET` on your Portainer Server instance (by specifying an `AGENT_SECRET` environment variable when starting the Portainer Server container) you must remember to explicitly provide the same secret to your Agent in the same way (as an environment variable) when updating your Agent: `-e AGENT_SECRET=yoursecret` [PreviousUpdating Portainer](https://docs.portainer.io/sts/start/upgrade) [NextUpdating on Docker Swarm](https://docs.portainer.io/sts/start/upgrade/swarm) Last updated 1 month ago Was this helpful? --- # Updating the Edge Agent | 2.35 STS | Portainer Documentation To update the Portainer Edge Agent to the latest version, follow the below instructions for your Edge environment. Always match the agent version to the Portainer Server version. In other words, when you're installing or updating to Portainer 2.35.0 make sure all of the agents are also on version 2.35.0. Before beginning any update, we highly recommend [taking a backup](https://docs.portainer.io/sts/admin/settings/general#back-up-portainer) of your current Portainer configuration. [](https://docs.portainer.io/sts/start/upgrade/edge#docker-standalone) Docker Standalone --------------------------------------------------------------------------------------------- Portainer now also has the ability to update Edge Agents on Docker Standalone [directly from within the UI](https://docs.portainer.io/sts/admin/environments/update) . To upgrade the Portainer Edge Agent on a Docker Standalone platform, you will first need to note the **Edge identifier** and the **Edge key** for the Edge environment. To find these values, log into Portainer and click **Environments**, then click the name of the environment you are updating. At the top of the page in the **Edge information** section, you will see the two values you require in the next steps. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FAX7nWtfSe5s3u06GeQfr%2F2.15-upgrade-edge-edgeinfo.png&width=768&dpr=4&quality=100&sign=bcd73219&sv=2) Next, on the Edge environment, we need to stop and remove the Edge Agent container. Copy docker stop portainer_edge_agent docker rm portainer_edge_agent We also want to ensure we have the updated version of the container image locally: Copy docker pull portainer/agent:sts To deploy the updated Edge Agent, replace the `your-edge-identifier-here` and `your-edge-key-here` values in the following command with those you retrieved earlier, then run the command: Copy docker run -d -v /var/run/docker.sock:/var/run/docker.sock -v /var/lib/docker/volumes:/var/lib/docker/volumes -v /:/host -v portainer_agent_data:/data --restart always -e EDGE=1 -e EDGE_ID=your-edge-identifier-here -e EDGE_KEY=your-edge-key-here -e EDGE_INSECURE_POLL=1 --name portainer_edge_agent portainer/agent:sts [](https://docs.portainer.io/sts/start/upgrade/edge#docker-swarm) Docker Swarm ----------------------------------------------------------------------------------- To update the Portainer Edge Agent on a Docker Swarm environment, run the following commands. First, to ensure you have the updated container image locally, pull the image: Copy docker pull portainer/agent:sts Then, update the service to use the new image version: Copy docker service update --image portainer/agent:sts --force portainer_edge_agent [](https://docs.portainer.io/sts/start/upgrade/edge#kubernetes) Kubernetes ------------------------------------------------------------------------------- To update the Portainer Edge Agent on a Kubernetes environment, you will need to first download an updated YAML manifest, then apply that manifest to your existing environment. To download the manifest, you can use one of the following commands: Business Edition Community Edition Copy curl -L https://downloads.portainer.io/ee-sts/portainer-agent-edge-k8s.yaml -o portainer-agent-edge-k8s.yaml Copy curl -L https://downloads.portainer.io/ce-sts/portainer-agent-edge-k8s.yaml -o portainer-agent-edge-k8s.yaml To apply this manifest to your environment, run the following command: Copy kubectl apply -f portainer-agent-edge-k8s.yaml [PreviousUpdating on Nomad](https://docs.portainer.io/sts/start/upgrade/nomad) [NextUpdating from Portainer 1.x](https://docs.portainer.io/sts/start/upgrade/from-1.x) Last updated 1 month ago Was this helpful? --- # Updating from Portainer 1.x | 2.35 STS | Portainer Documentation If you are updating a Portainer install that is currently running an image from the 1.x series, there are additional steps you must first take before updating to the most recent version. This document covers the steps depending on your current version - start from the instructions for your current version and work your way down. * [Version 1.24.0 or older](https://docs.portainer.io/sts/start/upgrade/from-1.x#updating-from-versions-older-than-1.24.1) * [Version 1.24.1 or 1.24.2](https://docs.portainer.io/sts/start/upgrade/from-1.x#updating-from-1.24.1-and-1.24.2) We only provide instructions for Docker Standalone and Docker Swarm environments here, as Portainer 1.x did not support Kubernetes environments. [](https://docs.portainer.io/sts/start/upgrade/from-1.x#updating-from-versions-older-than-1.24.1) **Updating from versions older than 1.24.1** --------------------------------------------------------------------------------------------------------------------------------------------------- If you are running a version prior to 1.24.1, you must first update to `portainer/portainer:1.24.2`. Your other applications/containers will not be removed. ### [](https://docs.portainer.io/sts/start/upgrade/from-1.x#docker-standalone) Docker Standalone Use the following commands to stop then remove the old version, then run Portainer release 1.24.2. Copy docker stop portainer docker rm portainer docker run -d -p 8000:8000 -p 9000:9000 --name=portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer:1.24.2 ### [](https://docs.portainer.io/sts/start/upgrade/from-1.x#docker-swarm) Docker Swarm Run the following command to update the Portainer service to 1.24.2. This assumes your service is named `portainer_portainer` (you can confirm this by checking the output of `docker service ls`). Copy docker service update --image portainer/portainer:1.24.2 --force portainer_portainer Verify that you are running version 1.24.2 by logging into Portainer and reading the version number on the bottom-left of the UI. You should now proceed to [update to version 2.0.0](https://docs.portainer.io/sts/start/upgrade/from-1.x#updating-from-1.24.1-and-1.24.2) . [](https://docs.portainer.io/sts/start/upgrade/from-1.x#updating-from-1.24.1-and-1.24.2) Updating from 1.24.1 and 1.24.2 ----------------------------------------------------------------------------------------------------------------------------- If you are running version 1.24.1 or 1.24.2 and want to update to the latest Portainer release, you must first update to `portainer/portainer-ce:2.0.0`. Use the following commands to stop then remove the old version. Your other applications/containers will not be removed. ### [](https://docs.portainer.io/sts/start/upgrade/from-1.x#docker-standalone-1) Docker Standalone Copy docker stop portainer docker rm portainer Now that you have stopped and removed the old version of Portainer, you must ensure that you have the latest version of the 2.0.0 image locally. You can do this with a `docker pull` command: Copy docker pull portainer/portainer-ce:2.0.0 Finally, deploy the updated version of Portainer: Copy docker run -d -p 8000:8000 -p 9000:9000 --name=portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:2.0.0 ### [](https://docs.portainer.io/sts/start/upgrade/from-1.x#docker-swarm-1) Docker Swarm Run the following command to update the Portainer service to 2.0.0. This assumes your service is named `portainer_portainer` (you can confirm this by checking the output of `docker service ls`). Copy docker service update --image portainer/portainer-ce:2.0.0 --force portainer_portainer Portainer CE 2.0.0 will now be deployed on your system, using the persistent data from the previous version, and will also update the Portainer database to the new version. When the deployment is finished, go to `http://your-server-address:9000` and log in. Verify that you are running version 2.0.0 by logging into Portainer and reading the version number on the bottom-left of the UI. [](https://docs.portainer.io/sts/start/upgrade/from-1.x#updating-from-2.0.0) Updating from 2.0.0 ----------------------------------------------------------------------------------------------------- Once you have updated to 2.0.0 you can proceed with the [standard update instructions](https://docs.portainer.io/sts/start/upgrade) for your platform, or if you are moving to Business Edition you can follow the [upgrade instructions](https://docs.portainer.io/sts/start/upgrade/tobe) . [PreviousUpdating the Edge Agent](https://docs.portainer.io/sts/start/upgrade/edge) [NextSwitching to Portainer Business Edition](https://docs.portainer.io/sts/start/upgrade/tobe) Was this helpful? --- # Updating on Podman | 2.35 STS | Portainer Documentation Always match the agent version to the Portainer Server version. In other words, when you're installing or updating to Portainer 2.35.0 make sure all of the agents are also on version 2.35.0. Before beginning any update, we highly recommend [taking a backup](https://docs.portainer.io/sts/admin/settings/general#back-up-portainer) of your current Portainer configuration. [](https://docs.portainer.io/sts/start/upgrade/podman#updating-your-portainer-server) Updating your Portainer Server ------------------------------------------------------------------------------------------------------------------------- Starting from Portainer CE 2.9 and BE 2.10, HTTPS is enabled by default on port `9443.` These instructions will configure Portainer to use 9443 for HTTPS and do not expose 9000 for HTTP. If you need to retain HTTP access, you can add: `-p 9000:9000` to your command. You can also choose to [completely disable HTTP](https://github.com/portainer/portainer-docs/blob/2.21/admin/settings/general/README.md#force-https-only) after the update. Before you make Portainer HTTPS only, make sure you have all your Agents and Edge Agents already communicating with Portainer using HTTPS. This article assumes that you used our recommended deployment scripts. To update to the latest version of Portainer Server, use the following commands to stop then remove the old version. Your other applications/containers will not be removed. Copy podman stop portainer Copy podman rm portainer Now that you have stopped and removed the old version of Portainer, you must ensure that you have the most up to date version of the image locally. You can do this with a `podman pull` command: Business Edition Community Edition Copy podman pull portainer/portainer-ee:sts Copy podman pull portainer/portainer-ce:sts Finally, deploy the updated version of Portainer: Business Edition Community Edition Copy podman run -d -p 8000:8000 -p 9443:9443 --name=portainer --restart=always --privileged -v /run/podman/podman.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ee:sts Copy podman run -d -p 8000:8000 -p 9443:9443 --name=portainer --restart=always --privileged -v /run/podman/podman.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:sts These `podman run` commands include opening port `8000` which is used for Edge Agent communication as included in our [installation instructions](https://docs.portainer.io/sts/start/install/server/docker/linux) . If you do not need this port open, you can remove it from the command. To provide your own SSL certs you may use `--sslcert` and `--sslkey` flags as below to provide the certificate and key files. The certificate file needs to be the full chain and in PEM format. For example, for Business Edition: Copy podman run -d -p 8000:8000 -p 9443:9443 --name=portainer --restart=always --privileged -v /run/podman/podman.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ee:sts --sslcert /path/to/cert/portainer.crt --sslkey /path/to/cert/portainer.key The newest version of Portainer will now be deployed on your system, using the persistent data from the previous version, and will also upgrade the Portainer database to the new version. When the deployment is finished, go to `https://your-server-address:9443` or `http://your-server-address:9000` and log in. You should notice that the update notification has disappeared and the version number has been updated. [](https://docs.portainer.io/sts/start/upgrade/podman#agent-only-update) Agent-only update ----------------------------------------------------------------------------------------------- To update to the latest version of Portainer Agent, use the following commands to stop then remove the old version. Your other applications/containers will not be removed. Copy podman stop portainer_agent Copy podman rm portainer_agent Next, pull the updated version of the image: Copy podman pull portainer/agent:sts Finally, start the agent with the updated image: Copy podman run -d -p 9001:9001 --name portainer_agent --restart=always --privileged -v /run/podman/podman.sock:/var/run/docker.sock -v /var/lib/containers/storage/volumes:/var/lib/docker/volumes portainer/agent:sts If you have set a custom `AGENT_SECRET` on your Portainer Server instance (by specifying an `AGENT_SECRET` environment variable when starting the Portainer Server container) you must remember to explicitly provide the same secret to your Agent in the same way (as an environment variable) when updating your Agent: `-e AGENT_SECRET=yoursecret` [PreviousUpdating on Docker Swarm](https://docs.portainer.io/sts/start/upgrade/swarm) [NextUpdating on Kubernetes](https://docs.portainer.io/sts/start/upgrade/kubernetes) Last updated 1 month ago Was this helpful? --- # Switching to Portainer Business Edition | 2.35 STS | Portainer Documentation It’s easy and quick to upgrade from Portainer CE (both 1.x and 2.x branches) to Portainer Business Edition without losing your data. The following instructions apply whether you’re using a 5 node free license or you’ve purchased a license for Portainer Business Edition. From version 2.17, you can upgrade your Portainer CE installation to Portainer BE from within Portainer itself. [Upgrade to Business Edition from within Portainer Community Edition](https://docs.portainer.io/sts/start/upgrade/tobe/inapp) If you would like to upgrade manually, you can find instructions for your environment at the following links: [Docker Standalone](https://docs.portainer.io/sts/start/upgrade/tobe/docker) [Docker Swarm](https://docs.portainer.io/sts/start/upgrade/tobe/swarm) [Kubernetes](https://docs.portainer.io/sts/start/upgrade/tobe/kubernetes) For Agent-only deployments, you do not need to upgrade the Agent to Business Edition. [Upgrading Agent-only deployments](https://docs.portainer.io/sts/start/upgrade/tobe/agent) [PreviousUpdating from Portainer 1.x](https://docs.portainer.io/sts/start/upgrade/from-1.x) [NextUpgrade to Business Edition from within Portainer Community Edition](https://docs.portainer.io/sts/start/upgrade/tobe/inapp) Was this helpful? --- # Install Portainer CE with Kubernetes on WSL / Docker Desktop | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Community Edition (CE). For Portainer Business Edition (BE) refer to the [BE install documentation](https://docs.portainer.io/sts/start/install/server/kubernetes/wsl) . [](https://docs.portainer.io/sts/start/install-ce/server/kubernetes/wsl#introduction) Introduction ------------------------------------------------------------------------------------------------------- The following instructions will guide you in setting up _Portainer Server_ with Kubernetes running on Docker Desktop with WSL. This scenario is for testing purposes only. We are aware of an issue where namespace and application access privileges are not fully implemented when running Kubernetes via Docker Desktop. We are looking into the root cause and hope to have a resolution soon. [](https://docs.portainer.io/sts/start/install-ce/server/kubernetes/wsl#preparation) Preparation ----------------------------------------------------------------------------------------------------- Before you start, you must make sure that Kubernetes is enabled and running within your Docker Desktop installation. To enable Kubernetes in Docker Desktop, you need to open the dashboard of Docker Desktop. Right click the Docker icon in the system tray and click **Dashboard**: ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FCZmIenUkg1e3kry9S6oN%2Fkube-wsl-1.png&width=768&dpr=4&quality=100&sign=8234ef77&sv=2) Click **Settings**, then select **Kubernetes**, tick **Enable Kubernetes**, then click **Apply and Restart** (clicking **Install** in the dialog to install Kubernetes): ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FULanvTgsC3egXWID5jYf%2Fkube-wsl-2.gif&width=768&dpr=4&quality=100&sign=1fa3a150&sv=2) After a few minutes, you will see that Kubernetes is running in the bottom left status bar of Docker Desktop: ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FYW1PiekvhWqlihBwpB6O%2Fkube-wsl-4.png&width=768&dpr=4&quality=100&sign=41532ab8&sv=2) Docker is on the left, Kubernetes is on the right [](https://docs.portainer.io/sts/start/install-ce/server/kubernetes/wsl#deployment) Deployment --------------------------------------------------------------------------------------------------- To deploy Portainer within a Kubernetes cluster you can use our provided Helm charts or YAML manifests. ### [](https://docs.portainer.io/sts/start/install-ce/server/kubernetes/wsl#deploy-using-helm) Deploy using Helm Ensure you're using at least Helm v3.2, which includes support for the `--create-namespace` argument. First add the Portainer Helm repository by running the following commands: Copy helm repo add portainer https://portainer.github.io/k8s/ helm repo update Once the update completes, you're ready to begin the installation. Which method you choose will depend on how you wish to expose the Portainer service: Expose via NodePort Expose via Ingress Expose via Load Balancer Using the following command, Portainer will be available on port `30777` for HTTP and `30779` for HTTPS: Copy helm upgrade --install --create-namespace -n portainer portainer portainer/portainer \ --set image.tag=lts By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) or [via the Portainer UI](https://app.gitbook.com/admin/settings#ssl-certificate) after installation is complete. In this example, Portainer will be deployed to your cluster and assigned a Cluster IP, with an nginx Ingress Controller at the defined hostname. For more on Ingress options, refer to the list of [Chart Configuration Options](https://docs.portainer.io/sts/advanced/helm-chart-configuration-options) . Copy helm upgrade --install --create-namespace -n portainer portainer portainer/portainer \ --set service.type=ClusterIP \ --set tls.force=true \ --set image.tag=lts \ --set ingress.enabled=true \ --set ingress.ingressClassName= \ --set ingress.annotations."nginx\.ingress\.kubernetes\.io/backend-protocol"=HTTPS \ --set ingress.hosts[0].host= \ --set ingress.hosts[0].paths[0].path="/" Using the following command, Portainer will be available at an assigned Load Balancer IP on port `9000` for HTTP and `9443` for HTTPS: Copy helm upgrade --install --create-namespace -n portainer portainer portainer/portainer \ --set service.type=LoadBalancer \ --set image.tag=lts By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) or [via the Portainer UI](https://app.gitbook.com/admin/settings#ssl-certificate) after installation is complete. To explicitly set the target node when deploying the Helm chart on the CLI, include `--set nodeSelector.kubernetes.io/hostname=` in your `helm install` command. ### [](https://docs.portainer.io/sts/start/install-ce/server/kubernetes/wsl#deploy-using-yaml-manifests) Deploy using YAML manifests Our YAML manifests support exposing Portainer via either NodePort or Load Balancer. Expose via NodePort Expose via Load Balancer To expose via NodePort, you can use the following command (Portainer will be available on port `30777` for HTTP and `30779` for HTTPS): Copy kubectl apply -n portainer -f https://downloads.portainer.io/ce-lts/portainer.yaml By default, Portainer generates and uses a self-signed SSL certificate to secure port `30779`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. To expose via Load Balancer, use the following command to provision Portainer at an assigned Load Balancer IP on port `9000` for HTTP and `9443` for HTTPS: Copy kubectl apply -n portainer -f https://downloads.portainer.io/ce-lts/portainer-lb.yaml By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. To explicitly set the target node when deploying using YAML manifests, run the following one-liner to "patch" the deployment, forcing the pod to always be scheduled on the node it's currently running on: Copy kubectl patch deployments -n portainer portainer -p '{"spec": {"template": {"spec": {"nodeSelector": {"kubernetes.io/hostname": "'$(kubectl get pods -n portainer -o jsonpath='{ ..nodeName }')'"}}}}}' || (echo Failed to identify current node of portainer pod; exit 1) [](https://docs.portainer.io/sts/start/install-ce/server/kubernetes/wsl#logging-in) Logging In --------------------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance. Depending on how you chose to expose your Portainer installation, open a web browser and navigate to the following URL: NodePort Ingress Load Balancer Copy https://localhost:30779/ or http://localhost:30777/ Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. Copy https:/// Replace `` with the FQDN of your Portainer instance. Copy https://:9443/ or http://:9000/ Replace `` with the IP address or FQDN of the load balancer, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/sts/start/install-ce/server/setup) [PreviousInstall Portainer CE on your Kubernetes environment](https://docs.portainer.io/sts/start/install-ce/server/kubernetes/baremetal) [NextInitial setup](https://docs.portainer.io/sts/start/install-ce/server/setup) Was this helpful? --- # Install Portainer CE on your Kubernetes environment | 2.35 STS | Portainer Documentation These installation instructions are for Portainer Community Edition (CE). For Portainer Business Edition (BE) refer to the [BE install documentation](https://docs.portainer.io/sts/start/install/server/kubernetes/baremetal) . [](https://docs.portainer.io/sts/start/install-ce/server/kubernetes/baremetal#introduction) Introduction ------------------------------------------------------------------------------------------------------------- Portainer consists of two elements, the _Portainer Server_ and the _Portainer Agent_. Both elements run as lightweight containers on Kubernetes. To get started, you will need: * A working and up to date Kubernetes cluster. * Access to run `helm` or `kubectl` commands on your cluster. * Cluster Admin rights on your Kubernetes cluster. This is so Portainer can create the necessary `ServiceAccount` and `ClusterRoleBinding` for it to access the Kubernetes cluster. * A `default` StorageClass configured (see below). The installation instructions also make the following assumptions about your environment: * Your environment meets [our requirements](https://docs.portainer.io/sts/start/requirements-and-prerequisites) . While Portainer may work with other configurations, it may require configuration changes or have limited functionality. * Kubernetes RBAC is enabled and working (this is required for the access control functionality in Portainer). * You will be using the `portainer` namespace for Portainer. At present this is a requirement - other namespaces are currently unsupported. * Kubernetes' metrics server is installed and working (if you wish to use the metrics within Portainer). [](https://docs.portainer.io/sts/start/install-ce/server/kubernetes/baremetal#data-persistence) Data Persistence --------------------------------------------------------------------------------------------------------------------- Portainer requires data persistence, and as a result needs at least one StorageClass available to use. Portainer will attempt to use the default StorageClass during deployment. If you do not have a StorageClass tagged as `default` the deployment will likely fail. We recommend using block storage for Kubernetes rather than network storage for the best performance and reliability, but do pay attention to the IOPS of your block storage devices when choosing the volume to use as some options are slower than others. You can check if you have a default StorageClass by running the following command on your cluster: Copy kubectl get sc and looking for a StorageClass with `(default)` after its name: Copy root@kubemaster01:~# kubectl get sc NAME PROVISIONER RECLAIMPOLICY VOLUMEBINDINGMODE ALLOWVOLUMEEXPANSION AGE managed-nfs-storage (default) k8s-sigs.io/nfs-subdir-external-provisioner Delete Immediate false 11d To set a StorageClass as default, you can use the following: Copy kubectl patch storageclass -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}' replacing `` with the name of your StorageClass. Alternatively, if you are installing using our Helm chart, you can pass the following parameter in your helm install command to specify the StorageClass to use for Portainer: Copy --set persistence.storageClass= In some Kubernetes clusters (for example microk8s), the default StorageClass simply creates hostPath volumes, which are not explicitly tied to a particular node. In a multi-node cluster, this can create an issue when the pod is terminated and rescheduled on a different node, "leaving" all the persistent data behind and starting the pod with an "empty" volume. While this behavior is inherently a limitation of using hostPath volumes, a suitable workaround is to use add a nodeSelector to the deployment, which effectively "pins" the Portainer pod to a particular node. You can do this by editing your own values.yaml file to set the nodeSelector value: `nodeSelector: kubernetes.io/hostname: \` or alternatively follow the instructions below for each deployment method. [](https://docs.portainer.io/sts/start/install-ce/server/kubernetes/baremetal#deployment) Deployment --------------------------------------------------------------------------------------------------------- To deploy Portainer within a Kubernetes cluster you can use our provided Helm charts or YAML manifests. ### [](https://docs.portainer.io/sts/start/install-ce/server/kubernetes/baremetal#deploy-using-helm) Deploy using Helm Ensure you're using at least Helm v3.2, which includes support for the `--create-namespace` argument. First add the Portainer Helm repository by running the following commands: Copy helm repo add portainer https://portainer.github.io/k8s/ helm repo update Once the update completes, you're ready to begin the installation. Which method you choose will depend on how you wish to expose the Portainer service: Expose via NodePort Expose via Ingress Expose via Load Balancer Using the following command, Portainer will be available on port `30779` for HTTPS: Copy helm upgrade --install --create-namespace -n portainer portainer portainer/portainer \ --set tls.force=true \ --set image.tag=lts By default, Portainer generates and uses a self-signed SSL certificate to secure port `30779`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. If you need to access Portainer via HTTP on port `30777`, remove the `--set tls.force=true` option. In this example, Portainer will be deployed to your cluster and assigned a Cluster IP, with an nginx Ingress Controller at the defined hostname. For more on Ingress options, refer to the list of [Chart Configuration Options](https://docs.portainer.io/sts/advanced/helm-chart-configuration-options) . Copy helm upgrade --install --create-namespace -n portainer portainer portainer/portainer \ --set service.type=ClusterIP \ --set tls.force=true \ --set image.tag=lts \ --set ingress.enabled=true \ --set ingress.ingressClassName= \ --set ingress.annotations."nginx\.ingress\.kubernetes\.io/backend-protocol"=HTTPS \ --set ingress.hosts[0].host= \ --set ingress.hosts[0].paths[0].path="/" If you need to access Portainer via HTTP, remove the `--set tls.force=true` option. Using the following command, Portainer will be available at an assigned Load Balancer IP on port `9443` for HTTPS: Copy helm upgrade --install --create-namespace -n portainer portainer portainer/portainer \ --set service.type=LoadBalancer \ --set tls.force=true \ --set image.tag=lts By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. If you need to access Portainer via HTTP on port `9000`, remove the `--set tls.force=true` option. If you want to explicitly set the target node when deploying the Helm chart on the CLI, include `--set nodeSelector.kubernetes\.io/hostname=` in your `helm install` command. ### [](https://docs.portainer.io/sts/start/install-ce/server/kubernetes/baremetal#deploy-using-yaml-manifests) Deploy using YAML manifests Our YAML manifests support exposing Portainer via either NodePort or Load Balancer. Expose via NodePort Expose via Load Balancer To expose via NodePort, you can use the following command (Portainer will be available on port `30777` for HTTP and `30779` for HTTPS): Copy kubectl apply -n portainer -f https://downloads.portainer.io/ce-lts/portainer.yaml By default, Portainer generates and uses a self-signed SSL certificate to secure port `30779`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. To expose via Load Balancer, use the following command to provision Portainer at an assigned Load Balancer IP on port `9000` for HTTP and `9443` for HTTPS: Copy kubectl apply -n portainer -f https://downloads.portainer.io/ce-lts/portainer-lb.yaml By default, Portainer generates and uses a self-signed SSL certificate to secure port `9443`. Alternatively you can provide your own SSL certificate [during installation](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) or [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) after installation is complete. If you want to explicitly set the target node when deploying using YAML manifests, run the following one-liner to "patch" the deployment, forcing the pod to always be scheduled on the node it's currently running on: Copy kubectl patch deployments -n portainer portainer -p '{"spec": {"template": {"spec": {"nodeSelector": {"kubernetes.io/hostname": "'$(kubectl get pods -n portainer -o jsonpath='{ ..nodeName }')'"}}}}}' || (echo Failed to identify current node of portainer pod; exit 1) [](https://docs.portainer.io/sts/start/install-ce/server/kubernetes/baremetal#logging-in) Logging In --------------------------------------------------------------------------------------------------------- Now that the installation is complete, you can log into your Portainer Server instance. Depending on how you chose to expose your Portainer installation, open a web browser and navigate to the following URL: NodePort Ingress Load Balancer Copy https://localhost:30779/ or http://localhost:30777/ Replace `localhost` with the relevant IP address or FQDN if needed, and adjust the port if you changed it earlier. Copy https:/// Replace `` with the FQDN of your Portainer instance. Copy https://:9443/ or http://:9000/ Replace `` with the IP address or FQDN of the load balancer, and adjust the port if you changed it earlier. You will be presented with the initial setup page for Portainer Server. [Initial setup](https://docs.portainer.io/sts/start/install-ce/server/setup) [PreviousKubernetes](https://docs.portainer.io/sts/start/install-ce/server/kubernetes) [NextInstall Portainer CE with Kubernetes on WSL / Docker Desktop](https://docs.portainer.io/sts/start/install-ce/server/kubernetes/wsl) Was this helpful? --- # Updating on Docker Swarm | 2.35 STS | Portainer Documentation Always match the agent version to the Portainer Server version. In other words, when you're installing or updating to Portainer 2.35.0 make sure all of the agents are also on version 2.35.0. Starting from Portainer CE 2.9 and BE 2.10, HTTPS is enabled by default on port `9443.` These instructions will configure Portainer to use 9443 for HTTPS and 9000 for HTTP. You can choose to [completely disable HTTP](https://docs.portainer.io/sts/admin/settings#force-https-only) after the update. Before you make Portainer HTTPS only, make sure you have all your Agents and Edge Agents already communicating with Portainer using HTTPS. If you are updating from the 1.x version of Portainer, you **must** first [update to 2.0.0](https://docs.portainer.io/sts/start/upgrade/from-1.x) **before** updating to the newest version or you will run into issues. Before beginning any update, we highly recommend [taking a backup](https://docs.portainer.io/sts/admin/settings/general#back-up-portainer) of your current Portainer configuration. To update the Portainer Server and the agents on Docker Swarm, first run the following command on the manager node of your Docker Swarm cluster: Copy docker service ls Make note of the service names for Portainer. You will need them later. Copy ID NAME MODE REPLICAS IMAGE PORTS tb9gtxc647fw portainer-agent_agent global 3/3 portainer/agent:2.28.0 m3a3mtuy55ed portainer_portainer replicated 1/1 portainer/portainer-ee:2.28.0 *:8000->8000/tcp, *:9000->9000/tcp To update Portainer Server to the most recent version, run one of the sets of commands below depending on your edition of Portainer (replace the `portainer_portainer` service name if your setup differs): Business Edition Community Edition Copy docker pull portainer/portainer-ee:sts docker service update --image portainer/portainer-ee:sts --publish-add 9443:9443 --force portainer_portainer Copy docker pull portainer/portainer-ce:sts docker service update --image portainer/portainer-ce:sts --publish-add 9443:9443 --force portainer_portainer To update the Portainer Agent to the latest version, run the commands below (replace the `portainer_agent` service name if your setup differs): Copy docker pull portainer/agent:sts docker service update --image portainer/agent:sts --force portainer_agent This will deploy the newest version of Portainer and the agent across your swarm and upgrade the Portainer database to match. When this is finished, go to `https://your-server-address:9443` or `http://your-server-address:9000` and log in. You should notice that the update notification has disappeared and the version number has been updated. [PreviousUpdating on Docker Standalone](https://docs.portainer.io/sts/start/upgrade/docker) [NextUpdating on Podman](https://docs.portainer.io/sts/start/upgrade/podman) Last updated 1 month ago Was this helpful? --- # Updating on Kubernetes | 2.35 STS | Portainer Documentation Always match the agent version to the Portainer Server version. In other words, when you're installing or updating to Portainer 2.35.0 make sure all of the agents are also on version 2.35.0. Starting from Portainer CE 2.9 and BE 2.10, HTTPS is enabled by default on port `9443`. These instructions will configure Portainer to use both `9443` for HTTPS and `9000` for HTTP. You can choose to [completely disable HTTP](https://docs.portainer.io/sts/admin/settings#force-https-only) after the update. Before you make Portainer HTTPS only, make sure you have all your Agents and Edge Agents already communicating with Portainer using HTTPS. Before beginning any update, we highly recommend [taking a backup](https://docs.portainer.io/sts/admin/settings/general#back-up-portainer) of your current Portainer configuration. Select the Portainer update method which matches the original installation method used. [](https://docs.portainer.io/sts/start/upgrade/kubernetes#method-1-updating-using-helm) Method 1: Updating using Helm -------------------------------------------------------------------------------------------------------------------------- Add the Portainer Helm repository by running the following commands. Ignore any warnings about the repo already being there: Copy helm repo add portainer https://portainer.github.io/k8s/ helm repo update Next, run one of the following commands to update Portainer: Business Edition Community Edition Copy helm upgrade -n portainer portainer portainer/portainer \ --set enterpriseEdition.image.tag=sts --set enterpriseEdition.enabled=true Copy helm upgrade -n portainer portainer portainer/portainer \ --set image.tag=sts [](https://docs.portainer.io/sts/start/upgrade/kubernetes#method-2-updating-using-yaml-manifest) Method 2: Updating using YAML Manifest -------------------------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.portainer.io/sts/start/upgrade/kubernetes#option-1-via-the-portainer-ui) Option 1: Via the Portainer UI The easiest way to update is to use the Portainer UI along with our manifest files. Copy the contents of the manifest file that matches the method you used to deploy Portainer: NodePort Load Balancer Copy the contents of the relevant NodePort manifest file: **Business Edition:** Copy https://downloads.portainer.io/ee-sts/portainer.yaml **Community Edition:** Copy https://downloads.portainer.io/ce-sts/portainer.yaml For an agent-only deployment, use one of the following manifests instead: **Business Edition:** Copy https://downloads.portainer.io/ee-sts/portainer-agent-k8s-nodeport.yaml **Community Edition:** Copy https://downloads.portainer.io/ce-sts/portainer-agent-k8s-nodeport.yaml If you have set a custom `AGENT_SECRET` on your Portainer Server instance (by specifying an `AGENT_SECRET` environment variable when starting the Portainer Server container) you must remember to explicitly provide the same secret to your Agent in the same way (as an environment variable) in the YAML when updating your Agent: `environment: - AGENT_SECRET: yoursecret` Copy the contents of the relevant Load Balancer manifest file: **Business Edition:** Copy https://downloads.portainer.io/ee-lts/portainer-lb.yaml **Community Edition:** Copy https://downloads.portainer.io/ce-lts/portainer-lb.yaml For an agent-only deployment, use one of the following manifests instead: **Business Edition:** Copy https://downloads.portainer.io/ee-lts/portainer-agent-k8s-lb.yaml **Community Edition:** Copy https://downloads.portainer.io/ce-lts/portainer-agent-k8s-lb.yaml If you have set a custom `AGENT_SECRET` on your Portainer Server instance you must remember to explicitly provide this in the YAML when updating your agent: `environment:` `- AGENT_SECRET: yoursecret` Log into Portainer and connect to the Kubernetes environment where Portainer is installed. From the menu select **Applications** then select **Create from manifest**. Toggle **Use namespace(s) specified from manifest** to on, then enter `portainer` in the **Name** field. If you used a different name for your Portainer deployment, use that instead. From the **Build method** selection choose **Web Editor** and ensure **Kubernetes** is selected as the **Deploy type**. Paste the contents of the YAML file then click **Deploy**. Portainer will process the manifest and should return you to the login page once the update is complete. ### [](https://docs.portainer.io/sts/start/upgrade/kubernetes#option-2-via-the-command-line) Option 2: Via the command line If you prefer to use the command line to update, you can do so using `kubectl` commands: NodePort Load Balancer Log into the control node of your Kubernetes cluster and run one of the following commands: **Business Edition:** Copy kubectl apply -n portainer -f https://downloads.portainer.io/ee-sts/portainer.yaml **Community Edition:** Copy kubectl apply -n portainer -f https://downloads.portainer.io/ce-sts/portainer.yaml For an agent-only deployment, use one of the following commands instead: **Business Edition:** Copy kubectl apply -n portainer -f https://downloads.portainer.io/ee-sts/portainer-agent-k8s-nodeport.yaml **Community Edition:** Copy kubectl apply -n portainer -f https://downloads.portainer.io/ce-sts/portainer-agent-k8s-nodeport.yaml If you have set a custom `AGENT_SECRET` on your Portainer Server instance (by specifying an `AGENT_SECRET` environment variable when starting the Portainer Server container) you must remember to explicitly provide the same secret to your Agent in the same way (as an environment variable) in the YAML when updating your Agent: `environment: - AGENT_SECRET: yoursecret` Log into the control node of your Kubernetes cluster and run one of the following commands: **Business Edition:** Copy kubectl apply -n portainer -f https://downloads.portainer.io/ee-sts/portainer-lb.yaml **Community Edition:** Copy kubectl apply -n portainer -f https://downloads.portainer.io/ce-sts/portainer.yaml For an agent-only deployment, use one of the following commands instead: **Business Edition:** Copy kubectl apply -n portainer -f https://downloads.portainer.io/ee-sts/portainer-agent-k8s-lb.yaml **Community Edition:** Copy kubectl apply -n portainer -f https://downloads.portainer.io/ce-sts/portainer-agent-k8s-lb.yaml If you have set a custom `AGENT_SECRET` on your Portainer Server instance you must remember to explicitly provide this in the YAML when updating your agent: `environment:` `- AGENT_SECRET: yoursecret` When the deployment is finished you will be able to log into Portainer. You should notice the new version number at the bottom-left of the Portainer UI. [](https://docs.portainer.io/sts/start/upgrade/kubernetes#method-3-force-an-update) Method 3: Force an update ------------------------------------------------------------------------------------------------------------------ If Portainer does not update after running the above commands, you can force a download of the latest image by running the following command: Copy kubectl -n portainer rollout restart deployment.apps/portainer Or, for an agent-only deployment, use this command instead: Copy kubectl -n portainer rollout restart deployment.apps/portainer-agent [PreviousUpdating on Podman](https://docs.portainer.io/sts/start/upgrade/podman) [NextUpdating on Nomad](https://docs.portainer.io/sts/start/upgrade/nomad) Last updated 26 days ago Was this helpful? --- # Upgrade to Business Edition from within Portainer Community Edition | 2.35 STS | Portainer Documentation To upgrade from Portainer Community Edition to Portainer Business Edition from within Portainer, log in as an administrator and click the **Upgrade to Business Edition** message in the top left. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FoYocqfIdXplGhMoBFEz8%2F2.32-start-upgradetobe.gif&width=768&dpr=4&quality=100&sign=3611a94&sv=2) If you already have a license for Portainer Business Edition, paste it in the box and click **Start upgrade** to begin the upgrade process. If you do not currently have a license, click **Get a license** and fill out the form to receive a trial key. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FrhEnffq1ahCltFCQYfaB%2F2.17-upgrade-tobe-inapp-licenseform.png&width=768&dpr=4&quality=100&sign=3671a77c&sv=2) Your trial key will be sent to the email address you provided and you will be returned to the license entry form. Your license should be sent automatically within a few minutes. If you have not received it please check your spam folders, or [get in touch with our team](https://docs.portainer.io/cdn-cgi/l/email-protection#cdbeb8aeaea8bebe8dbda2bfb9aca4a3a8bfe3a4a2) if you have not received it in 24 hours. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2Fu02KQtbfbznLBXhx3uF5%2F2.17-upgrade-tobe-inapp-licensesent.png&width=768&dpr=4&quality=100&sign=b4abd40b&sv=2) When you receive your license, paste the key into the box and click **Start upgrade** to begin the upgrade process. [PreviousSwitching to Portainer Business Edition](https://docs.portainer.io/sts/start/upgrade/tobe) [NextDocker Standalone](https://docs.portainer.io/sts/start/upgrade/tobe/docker) Was this helpful? --- # Docker Standalone | 2.35 STS | Portainer Documentation This article assumes that you used our recommended deployment scripts. Before you begin, copy the license key from the email we sent you. The process for switching to Portainer Business Edition is straightforward but does depend on which version of Portainer you are currently running. Start from the instructions for your current version and work your way down. * [Version 1.24.0 or older](https://docs.portainer.io/sts/start/upgrade/tobe/docker#upgrading-from-versions-older-than-1.24.1) * [Version 1.24.1 or 1.24.2](https://docs.portainer.io/sts/start/upgrade/tobe/docker#upgrading-from-1.24.1-and-1.24.2) * [Version 2.0.0 or newer](https://docs.portainer.io/sts/start/upgrade/tobe/docker#upgrading-from-version-2.0.0-and-later) [](https://docs.portainer.io/sts/start/upgrade/tobe/docker#upgrading-from-versions-older-than-1.24.1) **Upgrading from versions older than 1.24.1** -------------------------------------------------------------------------------------------------------------------------------------------------------- If you are running a version prior to 1.24.1, you must first upgrade to `portainer/portainer:1.24.2`. Your other applications/containers will not be removed. Use the following commands to stop then remove the old version, then run Portainer release 1.24.2: Copy docker stop portainer docker rm portainer docker run -d -p 8000:8000 -p 9000:9000 --name=portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer:1.24.2 Verify that you are running version 1.24.2 by logging into Portainer and reading the version number on the bottom-left of the UI. You should now proceed to [upgrade to version 2.0.0](https://docs.portainer.io/sts/start/upgrade/tobe/docker#upgrading-from-1.24.1-and-1.24.2) . [](https://docs.portainer.io/sts/start/upgrade/tobe/docker#upgrading-from-1.24.1-and-1.24.2) Upgrading from 1.24.1 and 1.24.2 ---------------------------------------------------------------------------------------------------------------------------------- If you are running a version prior to 1.24.1 and want to upgrade to the latest Portainer release, you must first upgrade to `portainer/portainer-ce:2.0.0`, use the following commands to stop then remove the old version. Your other applications/containers will not be removed. Copy docker stop portainer Copy docker rm portainer Now that you have stopped and removed the old version of Portainer, you must ensure that you have the latest version of the image locally. You can do this with a `docker pull` command: Copy docker pull portainer/portainer-ce:2.0.0 Finally, deploy the updated version of Portainer: Copy docker run -d -p 8000:8000 -p 9000:9000 --name=portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:2.0.0 Portainer CE 2.0.0 will now be deployed on your system, using the persistent data from the previous version, and will also upgrade the Portainer database to the new version. When the deployment is finished, go to `http://your-server-address:9000` and log in. Verify that you are running version 2.0.0 by logging into Portainer and reading the version number on the bottom-left of the UI. You can now [upgrade to the latest version](https://docs.portainer.io/sts/start/upgrade/tobe/docker#upgrading-from-version-2.0.0-and-later) of Portainer Business Edition. [](https://docs.portainer.io/sts/start/upgrade/tobe/docker#upgrading-from-version-2.0.0-and-later) Upgrading from version 2.0.0 and later ---------------------------------------------------------------------------------------------------------------------------------------------- To upgrade to Portainer Business Edition for Docker Standalone, use the following commands to stop then remove the old version. Your other applications/containers will not be removed. Copy docker stop portainer docker rm portainer Now that you have stopped and removed the old version of Portainer, run this command to deploy the most up to date version of Portainer Business: Copy docker run -d -p 8000:8000 -p 9000:9000 -p 9443:9443 --name=portainer --restart=always --pull=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ee:sts Log out of Portainer (if currently logged in) then log back in. When you log in for the first time, you'll be asked to enter your license key. Paste this in from the email we sent you. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FTd7pqzuHHBl1Xa4YQSsd%2F2.20-initial-setup-license.png&width=768&dpr=4&quality=100&sign=d73bb5cc&sv=2) 'Business Edition' now appears in the bottom-left corner. [PreviousUpgrade to Business Edition from within Portainer Community Edition](https://docs.portainer.io/sts/start/upgrade/tobe/inapp) [NextDocker Swarm](https://docs.portainer.io/sts/start/upgrade/tobe/swarm) Last updated 1 month ago Was this helpful? --- # Docker Swarm | 2.35 STS | Portainer Documentation This article assumes that you used our recommended deployment scripts. Before you begin, copy the license key from the email we sent you. To upgrade to Portainer Business Edition for Docker Swarm, use the following commands to deploy the newest version of Portainer Business on your Swarm Cluster: Copy docker service update --image portainer/portainer-ee:sts --force portainer_portainer Log out of Portainer (if currently logged in) then log back in. When you log in for the first time, you'll be asked to enter your license key. Paste this in from the email we sent you. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FTd7pqzuHHBl1Xa4YQSsd%2F2.20-initial-setup-license.png&width=768&dpr=4&quality=100&sign=d73bb5cc&sv=2) 'Business Edition' now appears in the bottom-left corner. [PreviousDocker Standalone](https://docs.portainer.io/sts/start/upgrade/tobe/docker) [NextPodman](https://docs.portainer.io/sts/start/upgrade/tobe/podman) Last updated 1 month ago Was this helpful? --- # Kubernetes | 2.35 STS | Portainer Documentation Select the Portainer CE to Portainer Business upgrade method below which matches the original installation method used. [](https://docs.portainer.io/sts/start/upgrade/tobe/kubernetes#method-1-upgrade-via-helm) Method 1: Upgrade via Helm ------------------------------------------------------------------------------------------------------------------------- To update your Helm repository, run this command first: Copy helm repo update Run this command next to deploy the latest version of Portainer Business on your Kubernetes cluster with all of the settings used in your Helm deployment: Copy helm upgrade -n portainer portainer portainer/portainer --set enterpriseEdition.enabled=true [](https://docs.portainer.io/sts/start/upgrade/tobe/kubernetes#method-2-upgrade-via-yaml-manifests) Method 2: Upgrade via YAML Manifests --------------------------------------------------------------------------------------------------------------------------------------------- Choose the right YAML manifest based on your original deployment: NodePort Load Balancer Use the following `kubectl` command to update a NodePort deployment: Copy kubectl apply -n portainer -f https://downloads.portainer.io/ee-sts/portainer.yaml Use the following `kubectl` command to update a Load Balancer deployment: Copy kubectl apply -n portainer -f https://downloads.portainer.io/ee-sts/portainer-lb.yaml This will deploy the newest version of Portainer Business on your Kubernetes cluster. [](https://docs.portainer.io/sts/start/upgrade/tobe/kubernetes#logging-back-in) Logging back in ---------------------------------------------------------------------------------------------------- When the upgrade is complete, log out of Portainer (if currently logged in) then log back in. When you log in for the first time, you'll be asked to enter your license key. Paste this in from the email we sent you. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FTd7pqzuHHBl1Xa4YQSsd%2F2.20-initial-setup-license.png&width=768&dpr=4&quality=100&sign=d73bb5cc&sv=2) 'Business Edition' now appears in the bottom-left corner. [PreviousPodman](https://docs.portainer.io/sts/start/upgrade/tobe/podman) [NextUpgrading Agent-only deployments](https://docs.portainer.io/sts/start/upgrade/tobe/agent) Last updated 1 month ago Was this helpful? --- # Podman | 2.35 STS | Portainer Documentation This article assumes that you used our recommended deployment scripts. Before you begin, copy the license key from the email we sent you. To upgrade to Portainer Business Edition for Podman, use the following commands to stop then remove the old version. Your other applications/containers will not be removed. Copy podman stop portainer podman rm portainer Now that you have stopped and removed the old version of Portainer, run this command to deploy the most up to date version of Portainer Business: Copy podman run -d -p 8000:8000 -p 9000:9000 -p 9443:9443 --name=portainer --restart=always --pull=always --privileged -v /run/podman/podman.sock:/run/podman/podman.sock -v portainer_data:/data portainer/portainer-ee:sts Log out of Portainer (if currently logged in) then log back in. When you log in for the first time, you'll be asked to enter your license key. Paste this in from the email we sent you. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FTd7pqzuHHBl1Xa4YQSsd%2F2.20-initial-setup-license.png&width=768&dpr=4&quality=100&sign=d73bb5cc&sv=2) 'Business Edition' now appears in the bottom-left corner. [PreviousDocker Swarm](https://docs.portainer.io/sts/start/upgrade/tobe/swarm) [NextKubernetes](https://docs.portainer.io/sts/start/upgrade/tobe/kubernetes) Last updated 1 month ago Was this helpful? --- # Upgrading Agent-only deployments | 2.35 STS | Portainer Documentation Both Portainer Community Edition and Portainer Business Edition use the same Portainer Agent container image to run, so if you are upgrading from CE to BE and have Agent-only environments, you don't need to upgrade them as well - just ensure they are on the same version (for example, if the Portainer Server is version 2.35.0 then the Portainer Agent should be 2.35.0 as well). [PreviousKubernetes](https://docs.portainer.io/sts/start/upgrade/tobe/kubernetes) [NextHome](https://docs.portainer.io/sts/user/home) Last updated 1 month ago Was this helpful? --- # Home | 2.35 STS | Portainer Documentation The **Home** page is the first page you will see after logging into Portainer. This page provides an overview of your environments along with vital statistics about each. You can search and filter your list of environments using the options at the top of the list. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FlegNfWm028UtjNVV2uL7%2F2.32-user-home.png&width=768&dpr=4&quality=100&sign=400e46f0&sv=2) Your currently selected environment (if any) will be shown by the **Connected** status on the right. To choose an environment, either click on the tile for the environment or the **Live connect** or **Browse snapshot** button (for [Edge Devices in async mode](https://docs.portainer.io/sts/user/home/snapshot) ). You can click the pencil icon to edit the environment's connection configuration, and the cog button to go to the environment's settings page (if the environment is directly accessible). ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FT6ae1f6zs3RlihOTiK1b%2F2.32-user-home-buttons.png&width=768&dpr=4&quality=100&sign=65c6b671&sv=2) [](https://docs.portainer.io/sts/user/home#build-information) Build information ------------------------------------------------------------------------------------ You can view the build information for your Portainer installation by clicking on the Portainer version number in the bottom left of the UI. This may be helpful when troubleshooting issues with the Portainer support team. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FelTASUOqSgEdIGQH9ocF%2F2.32-user-home-buildinfo.png&width=768&dpr=4&quality=100&sign=fbd83d09&sv=2) In the box that appears you can see the server version, database version, build number and image tag, as well as the versions of the compilation tools, dependencies, and environment variables used to build Portainer. [](https://docs.portainer.io/sts/user/home#getting-help) Getting help -------------------------------------------------------------------------- From any page in the Portainer UI, you can click on the **question mark icon** in the top right next to your username to access the related section of this documentation. You can also click the **robot icon** to start a conversation with our [AI chatbot](https://portainer.io/ask-the-ai) . ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FAoJ4dRTxVKxeFaZ1TvVg%2F2.25.0-icons.png&width=768&dpr=4&quality=100&sign=9ab5e3a1&sv=2) [PreviousUpgrading Agent-only deployments](https://docs.portainer.io/sts/start/upgrade/tobe/agent) [NextSnapshot browsing](https://docs.portainer.io/sts/user/home/snapshot) Was this helpful? --- # Snapshot browsing | 2.35 STS | Portainer Documentation Snapshot browsing allows the ability to run remote commands on your Edge devices that are in Async mode. You can browse your device as well as run commands like start, stop, restart, and delete on your containers, stacks and volumes. To browse your Edge device, on the [home page](https://docs.portainer.io/sts/user/home) locate your Edge device and click the **Browse snapshot** button. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2Foff9xbOv9Ys15Ae8GSWo%2F2.33-home-edge-async-tile.png&width=768&dpr=4&quality=100&sign=e20fe48a&sv=2) You will be directed to the dashboard for the Edge device, with a **Browsing snapshot** drop down that details the last updated and next updated date, how often the snapshots are taken and the environment status. You can refer to the [deployment sync options](https://docs.portainer.io/sts/admin/settings/edge#deployment-sync-options) for more details. The information displayed in Portainer for your Edge device is up to date as of the time the latest snapshot (as indicated in the dropdown) was taken. Depending on the [age of the snapshot](https://docs.portainer.io/sts/admin/settings/edge#deployment-sync-options) and the environment, this may not be an up to date representation of the current state of the device, so bear this in mind when taking actions on the device. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FFgUoi2C24pPg3uyxNAKd%2F2.33-snapshot-browse-details.png&width=768&dpr=4&quality=100&sign=a9df2950&sv=2) From here, you can browse the device as you would a regular environment. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FZdzaLFR83XGpSQZgiB6r%2F2.33-snapshot-browse.gif&width=768&dpr=4&quality=100&sign=1acfb582&sv=2) [PreviousHome](https://docs.portainer.io/sts/user/home) [NextOpenAMT](https://docs.portainer.io/sts/user/home/openamt) Was this helpful? --- # OpenAMT | 2.35 STS | Portainer Documentation OpenAMT allows you to remotely manage your compatible Edge devices from Portainer, letting you start, stop, restart and access the device console directly from within the Portainer UI. [](https://docs.portainer.io/sts/user/home/openamt#preparation) Preparation -------------------------------------------------------------------------------- To associate an Edge device with OpenAMT you must first add a compatible device. To do this, first [deploy the Edge Agent](https://docs.portainer.io/sts/admin/environments/add) to your device based on the appropriate method for your environment type. Once the Edge Agent has been set up and deployed on the remote device, the device is ready to be associated with OpenAMT. [](https://docs.portainer.io/sts/user/home/openamt#associate-your-device) Associate your device ---------------------------------------------------------------------------------------------------- To associate an existing Edge Agent deployment with OpenAMT, from the Home page click the **Associate with OpenAMT** button. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2Fw6KulKxY6YCnWv9YGY0c%2F2.18-home-openamt-associate-button.png&width=768&dpr=4&quality=100&sign=69a17a1b&sv=2) Check the box next to the device(s) you want to associate, then click the **Associate Devices** button. The activation process will now begin. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FFlQbY43dhPC0Fs5xu2Nu%2F2.18-home-openamt-associate-dialog.png&width=768&dpr=4&quality=100&sign=1da6e47a&sv=2) Once activation completes you will be returned to the Home page. [](https://docs.portainer.io/sts/user/home/openamt#interact-with-your-device) Interact with your device ------------------------------------------------------------------------------------------------------------ Once an OpenAMT device has been associated with an Edge Device in Portainer, you are able to interact directly with that device. To do so, go to the Home page and use the options on the right hand side of the tile to interact as required. * **Power ON**: Will power on the device if it is currently switched off. * **Power OFF**: Will power off the device if it is currently switched on. * **Restart**: Will initiate a restart of the device. * **KVM**: Will open a remote KVM (keyboard, video, mouse) session with the device. [PreviousSnapshot browsing](https://docs.portainer.io/sts/user/home/snapshot) [NextDocker/Swarm/Podman](https://docs.portainer.io/sts/user/docker) Was this helpful? --- # Docker/Swarm/Podman | 2.35 STS | Portainer Documentation The following sections describe how to manage a Docker Standalone, Docker Swarm or Podman environment using menu options available in the Portainer Server. [Dashboard](https://docs.portainer.io/sts/user/docker/dashboard) [Templates](https://docs.portainer.io/sts/user/docker/templates) [Stacks](https://docs.portainer.io/sts/user/docker/stacks) [Services](https://docs.portainer.io/sts/user/docker/services) [Containers](https://docs.portainer.io/sts/user/docker/containers) [Images](https://docs.portainer.io/sts/user/docker/images) [Networks](https://docs.portainer.io/sts/user/docker/networks) [Volumes](https://docs.portainer.io/sts/user/docker/volumes) [Configs](https://docs.portainer.io/sts/user/docker/configs) [Secrets](https://docs.portainer.io/sts/user/docker/secrets) [Events](https://docs.portainer.io/sts/user/docker/events) [Host](https://docs.portainer.io/sts/user/docker/host) [Swarm](https://docs.portainer.io/sts/user/docker/swarm) [PreviousOpenAMT](https://docs.portainer.io/sts/user/home/openamt) [NextDashboard](https://docs.portainer.io/sts/user/docker/dashboard) Was this helpful? --- # Dashboard | 2.35 STS | Portainer Documentation The Docker/Swarm dashboard summarizes your Docker Standalone or Docker Swarm environment and shows the components that make up the environment. [](https://docs.portainer.io/sts/user/docker/dashboard#environment-info) Environment info ---------------------------------------------------------------------------------------------- This section is visible only to Docker Standalone and Podman environments. This section shows the environment name, its URL and port along with any [tags](https://docs.portainer.io/sts/admin/environments/tags#tagging-an-environment) . You can also see the number of CPU cores (and their available memory), the Docker/Podman version, and whether or not the Portainer Agent is installed. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FvStKYhOlf8EjE37HBWD2%2F2.15-docker-standalone-dashboard.png&width=768&dpr=4&quality=100&sign=9250f11&sv=2) [](https://docs.portainer.io/sts/user/docker/dashboard#cluster-information) Cluster information ---------------------------------------------------------------------------------------------------- This section is visible only to Docker Swarm environments. This section shows how many nodes are in the cluster and a link to the [cluster visualizer](https://docs.portainer.io/sts/user/docker/swarm/cluster-visualizer) . ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FhZNVbXsYiwMpBG2wD1h1%2F2.15-docker-dashboard-swarm.png&width=768&dpr=4&quality=100&sign=5271d44c&sv=2) [](https://docs.portainer.io/sts/user/docker/dashboard#summary-tiles) Summary tiles ---------------------------------------------------------------------------------------- The remaining dashboard is made up of tiles showing the number of [stacks](https://docs.portainer.io/sts/user/docker/stacks) , [services](https://docs.portainer.io/sts/user/docker/services) (for Docker Swarm), [containers](https://docs.portainer.io/sts/user/docker/containers) (including health and running-status metrics), [images](https://docs.portainer.io/sts/user/docker/images) (and how much disk space they consume), [volumes](https://docs.portainer.io/sts/user/docker/volumes) and [networks](https://docs.portainer.io/sts/user/docker/networks) , and GPUs (if enabled). ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FdUwWtgs5VPMI4uAQvZAS%2F2.15-docker-dashboard-tiles.png&width=768&dpr=4&quality=100&sign=e3928287&sv=2) [PreviousDocker/Swarm/Podman](https://docs.portainer.io/sts/user/docker) [NextTemplates](https://docs.portainer.io/sts/user/docker/templates) Was this helpful? --- # Application | 2.35 STS | Portainer Documentation An application template lets you deploy a container (or a stack of containers) to an environment with a set of predetermined configuration values while still allowing you to customize the configuration (for example, environment variables). This page lists the application templates available to deploy on your environment. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2Fon9fx8s9tESLuqA0CEnc%2F2.20-templates-application-list.png&width=768&dpr=4&quality=100&sign=69f60ba8&sv=2) Portainer supports templates of both individual containers and stacks of containers. [Deploy a stack](https://docs.portainer.io/sts/user/docker/templates/deploy-stack) [Deploy a container](https://docs.portainer.io/sts/user/docker/templates/deploy-container) By default, Portainer provides a pre-built set of app templates, but you are free to modify or [replace these with your own](https://docs.portainer.io/sts/advanced/app-templates/build) . You can also create your own custom templates either manually or from an existing stack. [PreviousTemplates](https://docs.portainer.io/sts/user/docker/templates) [NextCustom templates](https://docs.portainer.io/sts/user/docker/templates/custom) Was this helpful? --- # Templates | 2.35 STS | Portainer Documentation Templates let you deploy a container (or a stack of containers) to an environment with a set of predetermined configuration values while still allowing you to customize the configuration (for example, environment variables). [Application](https://docs.portainer.io/sts/user/docker/templates/application) [Custom templates](https://docs.portainer.io/sts/user/docker/templates/custom) [PreviousDashboard](https://docs.portainer.io/sts/user/docker/dashboard) [NextApplication](https://docs.portainer.io/sts/user/docker/templates/application) Was this helpful? --- # Custom templates | 2.35 STS | Portainer Documentation A custom template can be used to help streamline the deployment of a container or stack. You can also [create a template from an existing deployed stack](https://docs.portainer.io/sts/user/docker/stacks/template) . [](https://docs.portainer.io/sts/user/docker/templates/custom#viewing-the-list-of-custom-templates) Viewing the list of custom templates --------------------------------------------------------------------------------------------------------------------------------------------- To view a list of custom templates, from the menu expand **Templates** then select **Custom**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FSMMjWGq3CsReKlEruUOJ%2F2.20-templates-custom.gif&width=768&dpr=4&quality=100&sign=920a462c&sv=2) [](https://docs.portainer.io/sts/user/docker/templates/custom#creating-a-new-custom-template) Creating a new custom template --------------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.portainer.io/sts/user/docker/templates/custom#entering-the-basic-information) Entering the basic information Click **Add Custom Template** then complete the details, using the table below as a guide. Field/Option Overview Title Give the template a descriptive name. Description Enter a brief description of what your template includes. Note Note any extra information about the template (optional). Logo Enter the URL to a logo to be used for the template when it appears in the list (optional). Platform Select the compatible platform for the template. Options are **Linux** or **Windows**. Type Select the type of template. Options are **Standalone / Podman** or **Swarm**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FiIGJXPmowMO1IAnjCkLf%2F2.22.0-templates-custom-new.png&width=768&dpr=4&quality=100&sign=2ba7014e&sv=2) ### [](https://docs.portainer.io/sts/user/docker/templates/custom#selecting-the-build-method) Selecting the build method Next, choose the build method that suits your needs. You can use the web editor to manually enter your docker-compose file, upload a `docker-compose.yml` file from your local computer, or pull the compose file from a Git repository. #### [](https://docs.portainer.io/sts/user/docker/templates/custom#web-editor) Web editor Paste the contents of your docker-compose file into the box provided. Once all the details have been completed, click **Create custom template**. You can search within the web editor at any time by pressing `Ctrl-F` (or `Cmd-F` on Mac). ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FLtTCuerbh9dj3Zf9l1P4%2F2.20-templates-custom-add-webeditor.png&width=768&dpr=4&quality=100&sign=1fbf4f4b&sv=2) #### [](https://docs.portainer.io/sts/user/docker/templates/custom#upload) Upload Click **Select file** to browse for a docker-compose file to upload. Once all the details have been completed, click **Create custom template**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FQ0sqzIycisOFuC1h4FOl%2F2.20-templates-custom-add-upload.png&width=768&dpr=4&quality=100&sign=8171931&sv=2) #### [](https://docs.portainer.io/sts/user/docker/templates/custom#git-repository) Git repository Fill in the details for your Git repository. Field/Option Overview Authentication Enable this if your Git repository requires authentication. Git Credentials If the **Authentication** toggle is enabled and you have configured [individual](https://docs.portainer.io/sts/user/account-settings#git-credentials) or [shared](https://docs.portainer.io/sts/admin/settings/credentials/git) Git credentials, you can select them from this dropdown. Shared Git credentials can be identified with the **Shared** tag, and are only available to administrators at present. Leave this field unset to provide new credentials. Username When Authentication is enabled, enter your Git username. Personal Access Token When Authentication is enabled, enter your personal access token or password. Save credential When Authentication is enabled and you have provided new credentials, you can tick this box and enter a name to save those credentials for future use. Repository URL Enter the URL to your Git repository. Repository reference Select the repository reference to define the branch or tag to pull from. Compose path Enter the path within the repository to your docker-compose file. Skip TLS Verification Enable this option to skip verification of your Git repository's TLS certificate. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F22OwUl5aBgBMNwtCkLu6%2F2.20-templates-custom-add-git.png&width=768&dpr=4&quality=100&sign=af972a9e&sv=2) When all the details have been entered, click **Create custom template**. [](https://docs.portainer.io/sts/user/docker/templates/custom#variables-in-templates) Variables in templates ----------------------------------------------------------------------------------------------------------------- Custom templates support the use of variables to provide further customization of the deployed stack. A stack can define a variable that can then be adjusted by the user at deployment. This feature is only available in Portainer Business Edition. Variables are identified in stacks with `{{ }}`. For example, the following stack provides a `MYSQL_PASSWORD` variable: ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2Fik30OtFoGeHg4AH5rZte%2F2.15-docker-templates-custom-variables-set.png&width=768&dpr=4&quality=100&sign=d1987b61&sv=2) When a variable is defined, options appear to customize how the variable appears when deploying the stack. You can set the **label**, **description** and **default value**. When a template is deployed, any variables that have been configured are editable: ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F1QCZOFPGKtrYowiBNnJp%2F2.15-docker-templates-custom-variables-create.png&width=768&dpr=4&quality=100&sign=2fefad42&sv=2) [PreviousApplication](https://docs.portainer.io/sts/user/docker/templates/application) [NextDeploy a stack](https://docs.portainer.io/sts/user/docker/templates/deploy-stack) Was this helpful? --- # Deploy a stack | 2.35 STS | Portainer Documentation Portainer lets you deploy an entire stack from either a default template or a custom template. You can also [create a template from a stack](https://docs.portainer.io/sts/user/docker/stacks/template) . From the menu expand **Templates**, select **Application** or **Custom** (depending on the template) then select the template you want to deploy. In this example we'll create a WordPress stack. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FChM61Ccy9NPWv1M65ZyW%2F2.20-templates-deploy-stack.gif&width=768&dpr=4&quality=100&sign=617f0fb5&sv=2) Enter a name for the stack and set any required configuration values (these will differ from template to template). Toggle **Enable access control** on or off as required. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FK0TSJ1LhL9Xy7kFRCI6f%2F2.15-docker-deploy-stack-wordpress.png&width=768&dpr=4&quality=100&sign=4182bd99&sv=2) Click **Deploy the stack** then wait for the deployment to finish. If the deployment is successful, the new stack will appear in the list. Select it to view the [deployment details](https://docs.portainer.io/sts/user/docker/stacks/edit) . ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F1m4jNlwBBSVGuba9pq62%2F2.20-templates-deploy-stack-stacklist.png&width=768&dpr=4&quality=100&sign=eb3622f3&sv=2) [PreviousCustom templates](https://docs.portainer.io/sts/user/docker/templates/custom) [NextDeploy a container](https://docs.portainer.io/sts/user/docker/templates/deploy-container) Was this helpful? --- # Deploy a container | 2.35 STS | Portainer Documentation Portainer lets you deploy a standalone container from the default templates list. From the menu expand **Templates** then select **Application** or **Custom** (depending on the container). On the Application templates page you can choose to display only Container templates using the **Type** dropdown. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F1cQlURJsvEiraKNVesSK%2F2.20-templates-deploy-container.gif&width=768&dpr=4&quality=100&sign=b6f983da&sv=2) Then, select the container template you want to deploy. Define a name, a network, port mapping and volumes, and toggle **Enable access control** on if needed. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FJ0L9cqSobfn1sjjDszd8%2F2.15-docker_deploy_container_nginx.png&width=768&dpr=4&quality=100&sign=8f53f146&sv=2) You can also make changes to container settings such as port and volume mapping, host file entries, labels and the hostname by clicking **Show advanced options**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FZPcBpPm9k2DHCTVfVtea%2F2.15-docker_deploy_container_nginx_adv_opts.png&width=768&dpr=4&quality=100&sign=566662ec&sv=2) Once you have configured the container, click **Deploy the container**. [PreviousDeploy a stack](https://docs.portainer.io/sts/user/docker/templates/deploy-stack) [NextStacks](https://docs.portainer.io/sts/user/docker/stacks) Was this helpful? --- # Stacks | 2.35 STS | Portainer Documentation A stack is a collection of services, usually related to one application or usage. For example, a WordPress stack definition may include a web server container (such as nginx) and a database container (such as MySQL). ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F5wf3NP51g9yZYAzFESBa%2F2.20-stacks-list.png&width=768&dpr=4&quality=100&sign=c5f8da8a&sv=2) When the [new image indicator](https://docs.portainer.io/sts/user/docker/host/setup#other) feature is enabled, the **Images up to date** column indicates whether the local images in the stack are up to date, with a green tick indicating they are up to date and an orange cross indicating that there is a newer version of an image available at the remote registry. A grey hyphen indicates Portainer was unable to determine whether there is an update available for the images. You can click the **Reload image indicators** button to recheck the images for your stacks for updates, or to recheck a single stack's images you can click the image indicator icon for that stack. For more on how this works, have a look at [this article](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/how-does-the-image-update-notification-icon-work) . [Add a new stack](https://docs.portainer.io/sts/user/docker/stacks/add) [Inspect or edit a stack](https://docs.portainer.io/sts/user/docker/stacks/edit) [Create a template from a deployed stack](https://docs.portainer.io/sts/user/docker/stacks/template) [Webhooks](https://docs.portainer.io/sts/user/docker/stacks/webhooks) [Migrate or duplicate a stack](https://docs.portainer.io/sts/user/docker/stacks/migrate) [Remove a stack](https://docs.portainer.io/sts/user/docker/stacks/remove) [PreviousDeploy a container](https://docs.portainer.io/sts/user/docker/templates/deploy-container) [NextAdd a new stack](https://docs.portainer.io/sts/user/docker/stacks/add) Was this helpful? --- # Inspect or edit a stack | 2.35 STS | Portainer Documentation [](https://docs.portainer.io/sts/user/docker/stacks/edit#inspecting-a-stack) Inspecting a stack ---------------------------------------------------------------------------------------------------- From the menu select **Stacks** then select the stack you want to inspect. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FHjlYlU9SI6uYN7ZVJN9b%2F2.20-stacks-edit.gif&width=768&dpr=4&quality=100&sign=daf2e4c1&sv=2) From here you can stop, delete or [create a template from the stack](https://docs.portainer.io/sts/user/docker/stacks/template) , and if deployed from Git you can [detach the stack from the Git repository](https://docs.portainer.io/sts/user/docker/stacks/edit#detach-from-git) . ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FA3W3USQSqtCJoM27oDD5%2F2.20-stacks-edit-options.png&width=768&dpr=4&quality=100&sign=721c3f35&sv=2) If the stack was deployed from a Git repository, you can: * Configure [GitOps updates](https://docs.portainer.io/sts/user/docker/stacks/add#gitops-updates) or manually pull and redeploy the stack. * View and edit the stack's environment variables. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F65KEsXdHWrPYVxJuoU4f%2F2.20-stacks-edit-git.png&width=768&dpr=4&quality=100&sign=7486daeb&sv=2) If the stack was deployed using the [Web Editor](https://docs.portainer.io/sts/user/docker/stacks/add#option-1-web-editor) or [uploaded](https://docs.portainer.io/sts/user/docker/stacks/add#option-2-upload) , you will have the option to [edit your compose file manually](https://docs.portainer.io/sts/user/docker/stacks/edit#editing-a-stack) . Regardless of the deployment method used, you can also [migrate or duplicate](https://docs.portainer.io/sts/user/docker/stacks/migrate) the stack. ### [](https://docs.portainer.io/sts/user/docker/stacks/edit#docker-standalone-podman) Docker Standalone / Podman When using Docker Standalone or Podman, you can: * View the containers that make up the stack. * Check to see if they are running or stopped. * Get access to logs. * Inspect individual containers. * View container statistics. * Get access to the container's console. You can also see the image update indicator for each container in the stack. To recheck the image update status for all containers in the stack you can click the reload button next to the search box, or to recheck a single container's image, click the image update indicator icon for that container. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F1jnJoxuWVHJOkGicGZH5%2F2.20-stacks-edit-containers.png&width=768&dpr=4&quality=100&sign=34969a39&sv=2) ### [](https://docs.portainer.io/sts/user/docker/stacks/edit#docker-swarm) Docker Swarm When using Docker Swarm, you can: * View the services that make up the stack, and the individual tasks that make up each service. * Check to see if they are running or stopped. * See how many replicas are running on each host. * Get access to logs. * Inspect individual services. * View service statistics. * Get access to the service's console. You can also see the image update indicator for each service in the stack. To recheck the image update status for all services in the stack you can click the Reload image indicators button, or to recheck a single service's image, click the image update indicator icon for that service. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FbgQafRkbGAUlxppsw83c%2F2.20-stacks-edit-services.png&width=768&dpr=4&quality=100&sign=507a509d&sv=2) [](https://docs.portainer.io/sts/user/docker/stacks/edit#editing-a-stack) Editing a stack ---------------------------------------------------------------------------------------------- Editing a stack allows you to make changes to the configuration and redeploy those changes. To edit a stack, from the menu select **Stacks**, select the stack you want to edit, then select the **Editor** tab. The Editor tab is only available for stacks that were deployed using the [Web Editor](https://docs.portainer.io/sts/user/docker/stacks/add#option-1-web-editor) . For stacks deployed from a Git repository, the compose file must be edited in the repository itself. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FxmfPAE8Ra05dQJHe9J8p%2F2.19-stacks-edit-webeditor.png&width=768&dpr=4&quality=100&sign=7485ad2d&sv=2) Here, you can edit the Compose file for the stack to suit your needs. Using the **Version** dropdown you can also select a previous version of your stack file (if one exists) to switch back to if required. Selecting a different version from the dropdown will replace the contents of the editor with that of the selected version. You can search within the web editor at any time by pressing `Ctrl-F` (or `Cmd-F` on Mac). In this section you can expand the Environment variables section to view and make changes to the stack's environment variables. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FMTYab5MA8ESe5sjpow4d%2F2.20-stacks-edit-envvars.png&width=768&dpr=4&quality=100&sign=39998dc2&sv=2) You can also toggle the stack [webhook](https://docs.portainer.io/sts/user/docker/stacks/webhooks) and retrieve the webhook URL: ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FCiumRXJMY22sEYRJMeuj%2F2.20-stacks-edit-webhook.png&width=768&dpr=4&quality=100&sign=af0870bf&sv=2) You can choose to **Prune services** if you have made changes that remove some services from the stack. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FyuT2MUBPSAk5mJTD0kvN%2F2.20-stacks-edit-swarm-prune.png&width=768&dpr=4&quality=100&sign=c5ca5c47&sv=2) When you have finished making changes, click **Update the stack**. [](https://docs.portainer.io/sts/user/docker/stacks/edit#detach-from-git) Detach from Git ---------------------------------------------------------------------------------------------- If your stack was created from a Git repository, you have the option to detach the stack from the repository. This means you can [edit the stack directly within Portainer](https://docs.portainer.io/sts/user/docker/stacks/edit#editing-a-stack) , but it does mean that the stack can't be updated from Git anymore. This action also cannot be reversed. Detaching downloads the main compose file for the stack and stores it in Portainer. It does not download any additional compose files or `.env` files that may be contained within the repository. Click **Detach from Git** to detach. You will be asked to confirm the action - click **Detach** to do so. [PreviousAdd a new stack](https://docs.portainer.io/sts/user/docker/stacks/add) [NextCreate a template from a deployed stack](https://docs.portainer.io/sts/user/docker/stacks/template) Was this helpful? --- # Add a new stack | 2.35 STS | Portainer Documentation There are four ways to deploy a new stack from Portainer: Option Overview [Web editor](https://docs.portainer.io/sts/user/docker/stacks/add#option-1-web-editor) Use our web editor to define the services for the stack using a docker-compose format. [Upload](https://docs.portainer.io/sts/user/docker/stacks/add#option-2-upload) If you have a `stack.yml` file, you can upload it from your computer and use it to deploy the stack. [Git repository](https://docs.portainer.io/sts/user/docker/stacks/add#option-3-git-repository) You can use a docker-compose format file hosted in a Git repository. Custom template If you have created a [custom stack template](https://docs.portainer.io/sts/user/docker/templates/custom) , you can deploy using this option. [](https://docs.portainer.io/sts/user/docker/stacks/add#option-1-web-editor) Option 1: Web editor ------------------------------------------------------------------------------------------------------ From the menu select **Stacks**, click **Add stack**, give the stack a descriptive name then select **Web editor**. Use the web editor to define the services. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FG30Yg6IHOlZ06HbbbMgP%2F2.15-docker_add_stack_web_editor.gif&width=768&dpr=4&quality=100&sign=872308a0&sv=2) You can search within the web editor at any time by pressing `Ctrl-F` (or `Cmd-F` on Mac). As part of the stack creation you can enable a stack webhook, allowing you to remotely trigger redeployments of the stack from your repository, for example. You can read more on this in our documentation on [stack webhooks](https://docs.portainer.io/sts/user/docker/stacks/webhooks) . ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FKbChJiHNbKdjs3ZgLlqm%2F2.15-docker_stack_web_editor_webhook.png&width=768&dpr=4&quality=100&sign=cb992992&sv=2) As an optional step, you can also use the web editor to define environment variables. You can use these to define values in your compose file that would vary between deployments (for example, hostnames, database names, etc). Environment variables can be set individually within Portainer or you can use **Load variables from .env file** to upload a file containing your environment variables. Environment variables you define (either individually or via a .env file) will be available to use in your compose file using an `environment` definition: Copy environment: MY_ENVIRONMENT_VARIABLE: ${MY_ENVIRONMENT_VARIABLE} Alternatively, on Docker Standalone and Podman environments you can add `stack.env` as an `env_file` definition to add all the environment variables that you have defined individually as well as those included in an uploaded .env file: Copy env_file: - stack.env **Note:** Using `env_file` to define a file does not work in Docker Swarm due to the lack of `env_file` support in `docker stack deploy` (used on Swarm environments to deploy your stack). On Docker Swarm, you will need to define each environment variable manually. Note the compose file is not changed when environment variables are used - this allows variables to be updated within Portainer without editing the compose file itself. You will still see the `${MY_ENVIRONMENT_VARIABLE}` style entry in the compose file. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F2veUlzsJHb3s0x0h0IHw%2F2.15-docker_stack_wed_editor_env_var.png&width=768&dpr=4&quality=100&sign=4d9dead0&sv=2) You can also select the registries to use when deploying the stack. This is useful when your stack deploys multiple images from different registries that require authentication. By default, all configured registries are used. However, when you have multiple registries from the same provider (like multiple ghcr.io registries), Docker's authentication system may use the wrong credentials during deployment. Explicitly selecting the specific registry ensures the correct credentials are used. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F3au8RNy9UwkaYVla6gUl%2F2.33-stacks-add-registries.png&width=768&dpr=4&quality=100&sign=30052f03&sv=2) When you're ready, click **Deploy the stack**. [](https://docs.portainer.io/sts/user/docker/stacks/add#option-2-upload) Option 2: Upload ---------------------------------------------------------------------------------------------- In Portainer you can create stacks from Compose YML files. To do this, from the menu select **Stacks**, click **Add stack**, then give the stack a descriptive name. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2Fw2Q9ms2AKHPXwHlzBNkR%2F2.15-docker_add_stack_upload.gif&width=768&dpr=4&quality=100&sign=774c2c00&sv=2) Select **Upload** then select the Compose file from your computer. As part of the stack creation you can enable a stack webhook, allowing you to remotely trigger redeployments of the stack from your repository, for example. You can read more on this in our documentation on [stack webhooks](https://docs.portainer.io/sts/user/docker/stacks/webhooks) . ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FKbChJiHNbKdjs3ZgLlqm%2F2.15-docker_stack_web_editor_webhook.png&width=768&dpr=4&quality=100&sign=cb992992&sv=2) As an optional step, enter any environment variables. You can use these to define values in your compose file that would vary between deployments (for example, hostnames, database names, etc). Environment variables can be set individually within Portainer or you can use **Load variables from .env file** to upload a file containing your environment variables. Environment variables you define (either individually or via a .env file) will be available to use in your compose file using an `environment` definition: Copy environment: MY_ENVIRONMENT_VARIABLE: ${MY_ENVIRONMENT_VARIABLE} Alternatively, you can add `stack.env` as an `env_file` definition to add all the environment variables that you have defined individually as well as those included in an uploaded .env file: Copy env_file: - stack.env Note the compose file is not changed when environment variables are used - this allows variables to be updated within Portainer without editing the compose file itself which would take it out of sync with your local copy. You will still see the `${MY_ENVIRONMENT_VARIABLE}` style entry in the compose file. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FLbelc3NqJYHD1OyWRcnY%2F2.15-docker_add_stack_upload_env_var.png&width=768&dpr=4&quality=100&sign=dfdb1eff&sv=2) When you're ready click **Deploy the stack**. [](https://docs.portainer.io/sts/user/docker/stacks/add#option-3-git-repository) Option 3: Git repository -------------------------------------------------------------------------------------------------------------- If your Compose file is hosted in a Git repository, you can deploy from there. From the menu select **Stacks**, click **Add stack**, then give the stack a descriptive name. When a stack is deployed from Git, Portainer will clone the entire Git repository as part of the deployment process. Ensure you have enough free space to accommodate this. Portainer's Git deployment functionality does not currently support the use of Git submodules. If your repository includes submodules, they will not be pulled as part of the deployment. We [hope to add support](https://github.com/orgs/portainer/discussions/9767) for submodules in a future release. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FZibZ1EbReclAyvFvXg7b%2F2.15-docker_add_stack_git.gif&width=768&dpr=4&quality=100&sign=d0b19b9&sv=2) Select **Git Repository** then enter information about your Git repo. Any Git-compatible repository should work here. Substitute the details as required. Field/Option Overview Authentication Toggle this on if your Git repository requires authentication. Git Credentials If the **Authentication** toggle is enabled and you have configured [individual](https://docs.portainer.io/sts/user/account-settings#git-credentials) or [shared](https://docs.portainer.io/sts/admin/settings/credentials/git) Git credentials, you can select them from this dropdown. Shared Git credentials can be identified with the **Shared** tag, and are only available to administrators at present. Leave this field unset to provide new credentials. Authorization type Select either **Basic** or **Token** authorization depending on what your Git repository requires. For example, GitHub, GitLab, and Bitbucket Cloud expect Basic Auth, even when using an API or access token. Username Enter your Git username. Personal Access Token Enter your personal access token or password. Save credential Check this option to save the credentials entered above for future use under the name provided in the **credential name** field. If you have 2FA configured in GitHub, your passcode is your password. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2F2686689526-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FoeG1zgfd7OQLVZtVK5LC%252Fuploads%252FiaFkRQYL1YHaIj5W2p3c%252F2.35-stacks-add-git-auth.png%3Falt%3Dmedia%26token%3D3cbad166-7846-4339-a74e-d1d256dd4b0a&width=768&dpr=4&quality=100&sign=6132300&sv=2) Field/Option Overview Repository URL Enter the repository URL. If you have enabled Authentication above the credentials will be used to access the repository. The below options will be populated by what is found in the repository. Skip TLS verification Toggle this on to skip the verification of TLS certificates used by your repository. This is useful if your repo uses a self-signed certificate. Repository reference Select the reference to use when deploying the stack (for example, the branch). Compose path Enter the path to the Compose file from the root of the repository. Additional paths Click **Add file** to add additional YAML files to be parsed by the build. This is the equivalent of passing multiple `-f` options to `docker compose`, and abides by the same [merging rules](https://docs.docker.com/compose/how-tos/multiple-compose-files/merge/#merging-rules) . GitOps updates Toggle this on to enable GitOps updates (see below). ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FNdmP7i5XuheK3WnHISe8%2F2.24.0-docker-stacks-add-git.png&width=768&dpr=4&quality=100&sign=622601ae&sv=2) ### [](https://docs.portainer.io/sts/user/docker/stacks/add#gitops-updates) GitOps updates Portainer supports automatically updating your stacks deployed from Git repositories. To enable this, toggle on **GitOps updates** and configure your settings. For more detail on how GitOps updates function under the hood, have a look at [this article](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/how-do-automatic-updates-for-stacks-applications-work) . Field/Option Overview Mechanism Select the method to use when checking for updates: **Polling:** Periodically poll the Git repository from Portainer to check for updates to the repository. **Webhook:** Generate a webhook URL to add to your Git repository to trigger the update on demand (for example via GitHub actions). Fetch interval If **Polling** is selected, how often Portainer will check the Git repository for updates. Webhook When **Webhook** is selected, displays the webhook URL to use in your integration. Click **Copy link** to copy the webhook URL to the clipboard. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FFfV8vJUPPG6h7mlt0pXI%2F2.19-stacks-add-git-polling.png&width=768&dpr=4&quality=100&sign=49d56242&sv=2) Automatic updates when using polling ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FKJqiLbMFBrkjxrwKcg9a%2F2.19-stacks-add-git-webhook.png&width=768&dpr=4&quality=100&sign=2d61870c&sv=2) Automatic updates when using webhooks Field/Option Overview Re-pull image Enable this setting to always pull the most recent version of container images when updating the stack. This is equivalent to the `--pull=always` flag for `docker run`. This option was previously labeled as **Pull latest image**. Force redeployment Enable this setting to force the redeployment of your stack at the specified interval (or when the webhook is triggered), overwriting any changes that have been made in the local environment, even if there has been no update to the stack in Git. This is useful if you want to ensure that your Git repository is the source of truth for your stacks and are happy with the local stack being replaced. If this option is left disabled, automatic updates will only trigger if Portainer detects a change in the remote Git repository. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F8MRxCJSidXMEKAtCeIRn%2F2.19-stacks-add-git-repull-force.png&width=768&dpr=4&quality=100&sign=f8a53d17&sv=2) ### [](https://docs.portainer.io/sts/user/docker/stacks/add#relative-path-volumes) Relative path volumes When you toggle **Enable relative path volumes** to on, you are able to specify relative path references in your compose files. Portainer will create the required directory structure and populate the directories with the relevant files from your Git repository. This feature is only available in Portainer Business Edition. On Docker Standalone and Podman environments, specify the path at which you want your files to be created on your host filesystem in the **Local filesystem path** field. Ensure this directory exists on your local filesystem and is writable. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FbiNNIPV81OLFTR2FKjg4%2F2.17-stacks-add-relativepath.png&width=768&dpr=4&quality=100&sign=9516caf8&sv=2) On Docker Swarm environments, specify the path at which you want your files to be created in the Network filesystem path field. Ensure that this path is available on all of your Docker Swarm nodes and is writable. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FqJQLBukGWdnM0bS3pJqG%2F2.17-stacks-add-relativepath-swarm.png&width=768&dpr=4&quality=100&sign=70f17c5a&sv=2) For more detail on how this feature works, have a look at [this article](https://docs.portainer.io/sts/advanced/relative-paths) . ### [](https://docs.portainer.io/sts/user/docker/stacks/add#environment-variables) Environment variables As an optional step, you can also set environment variables. You can use these to define values in your compose file that would vary between deployments (for example, hostnames, database names, etc). Environment variables can be set individually within Portainer or you can use **Load variables from .env file** to upload a file containing your environment variables. Environment variables you define (either individually or via a .env file) will be available to use in your compose file using an `environment` definition: Copy environment: MY_ENVIRONMENT_VARIABLE: ${MY_ENVIRONMENT_VARIABLE} Alternatively, you can add `stack.env` as an `env_file` definition to add all the environment variables that you have defined individually as well as those included in an uploaded .env file: Copy env_file: - stack.env Note the compose file is not changed when environment variables are used - this allows variables to be updated within Portainer without editing the compose file itself which would take it out of sync with the Git repository. You will still see the `${MY_ENVIRONMENT_VARIABLE}` style entry in the compose file. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F2veUlzsJHb3s0x0h0IHw%2F2.15-docker_stack_wed_editor_env_var.png&width=768&dpr=4&quality=100&sign=4d9dead0&sv=2) Enter environment variables if required then click **Deploy the stack**. [PreviousStacks](https://docs.portainer.io/sts/user/docker/stacks) [NextInspect or edit a stack](https://docs.portainer.io/sts/user/docker/stacks/edit) Last updated 1 month ago Was this helpful? --- # Create a template from a deployed stack | 2.35 STS | Portainer Documentation In Portainer you can create an [app template](https://docs.portainer.io/sts/user/docker/templates) from deployed stacks. This is useful if you need to deploy the same stack several times. From the menu select **Stacks**, select the already-deployed stack, then click **Create template from stack**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FAvpQzxKIayvqgSnmnSlB%2F2.20-stacks-template.gif&width=768&dpr=4&quality=100&sign=c06ca6c7&sv=2) Define some properties for the new template, using the table below as a guide. Field/Option Overview Title Give the template a descriptive name. Description Enter a brief description of what your template includes. Note Note any extra information about the template (optional). Logo Enter the URL to a logo to be used for the template when it appears in the list (optional). Platform Select the compatible platform for the template. Options are **Linux** or **Windows**. Type Select the type of template. Options are **Standalone / Podman** or **Swarm**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FiIGJXPmowMO1IAnjCkLf%2F2.22.0-templates-custom-new.png&width=768&dpr=4&quality=100&sign=2ba7014e&sv=2) The **Web editor** will be pre-populated with the Compose file for your stack. Make any changes you need here. You can search within the web editor at any time by pressing `Ctrl-F` (or `Cmd-F` on Mac). ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F8T4EPOSCyM6GJUGh2ZgB%2F2.20-stacks-template-webeditor.png&width=768&dpr=4&quality=100&sign=23cf314b&sv=2) When you're ready, click **Create custom template**. [PreviousInspect or edit a stack](https://docs.portainer.io/sts/user/docker/stacks/edit) [NextWebhooks](https://docs.portainer.io/sts/user/docker/stacks/webhooks) Was this helpful? --- # Migrate or duplicate a stack | 2.35 STS | Portainer Documentation [](https://docs.portainer.io/sts/user/docker/stacks/migrate#migrating-a-stack) Migrating a stack ----------------------------------------------------------------------------------------------------- From the menu select **Stacks** then select the stack you want to migrate. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FHjlYlU9SI6uYN7ZVJN9b%2F2.20-stacks-edit.gif&width=768&dpr=4&quality=100&sign=daf2e4c1&sv=2) In the **Stack duplication / migration** section, select the destination environment for the stack, and optionally define a new name for the stack. Click **Migrate**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2Fo4OdF378JvSv4T9lThpz%2F2.20-stacks-migrate-migrate.png&width=768&dpr=4&quality=100&sign=fa34094e&sv=2) When the confirmation message appears, click **Migrate**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FWMaIYbnYvShLWDWJIiLt%2F2.15-stack-migrate-confirm.png&width=768&dpr=4&quality=100&sign=1c658c19&sv=2) [](https://docs.portainer.io/sts/user/docker/stacks/migrate#duplicating-a-stack) Duplicating a stack --------------------------------------------------------------------------------------------------------- From the menu select **Stacks** then select the stack you want to duplicate. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FHjlYlU9SI6uYN7ZVJN9b%2F2.20-stacks-edit.gif&width=768&dpr=4&quality=100&sign=daf2e4c1&sv=2) In the **Stack duplication / migration** section, give the new stack a descriptive name then select the environment that the stack is currently on. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F8toFMa2GIxrol2Lnp5mA%2F2.20-stacks-migrate-duplicate.png&width=768&dpr=4&quality=100&sign=f479016d&sv=2) When you're ready, click **Duplicate**. [PreviousWebhooks](https://docs.portainer.io/sts/user/docker/stacks/webhooks) [NextRemove a stack](https://docs.portainer.io/sts/user/docker/stacks/remove) Was this helpful? --- # Webhooks | 2.35 STS | Portainer Documentation A webhook is a POST request sent to a URL that you define in Docker Hub or another registry. Use webhooks to trigger an action in response to an event such as a repository push. This functionality is only available in [Portainer Business Edition](https://www.portainer.io/business-upsell?from=stack-webhook) . Webhooks are only available on non-Edge environments (environments running Portainer Server or Portainer Agent, not the Portainer Edge Agent). This is because the tunnel to the Portainer Edge Agent is only opened on-demand, and therefore would mean there is no way to expose a webhook permanently. [](https://docs.portainer.io/sts/user/docker/stacks/webhooks#enabling-a-stack-webhook) Enabling a stack webhook -------------------------------------------------------------------------------------------------------------------- From the menu select **Stacks** then select the container that you want to configure the webhook for. Then select the **Edit** tab. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F1iS57gJH9RRrepl0nV6D%2F2.20-stacks-webhooks.gif&width=768&dpr=4&quality=100&sign=631ca72e&sv=2) Scroll down to the **Webhooks** section and toggle the **Create a stack webhook** option on. When the URL appears, click **Copy link**. This URL will be used to configure the webhook in your chosen registry. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FgE5IK57Kq4JIIMRbiSa6%2F2.15-docker_stack_create_webhook.png&width=768&dpr=4&quality=100&sign=c3f547c2&sv=2) This example shows how to trigger the webhook using `redeploy`: Copy
Redeploy stack containers with latest image of same tag
This example shows how to trigger the webhook to update the stack to use a different image tag: Copy
Update stack container images with different tag
[](https://docs.portainer.io/sts/user/docker/stacks/webhooks#preventing-a-pull) Preventing a pull ------------------------------------------------------------------------------------------------------ In some cases you may want to override the pulling of images when using the webhook to do a redeploy. In that scenario, you can specify `pullimage=false` as a parameter on your webhook to disable pulling of images. This option is only available in Portainer Business Edition. Copy
Update stack without pulling images
[](https://docs.portainer.io/sts/user/docker/stacks/webhooks#using-environment-variables-with-webhooks) Using environment variables with webhooks ------------------------------------------------------------------------------------------------------------------------------------------------------ When triggering a webhook, environment variables can be passed through the endpoint and referenced within stacks' compose files. To specify an environment variable on a webhook, add it as a variable to the URL. For example, to pass a `SERVICE_TAG` variable with the value `development`: Copy https://portainer:9443/api/stacks/webhooks/1d251d96-fb34-4172-a0a1-d0655467b897?SERVICE_TAG=development To reference the `SERVICE_TAG` variable in your compose file with a fallback to the value `stable`: Copy services: my-service: image: repository/image:${SERVICE_TAG:-stable} [](https://docs.portainer.io/sts/user/docker/stacks/webhooks#configuring-the-webhook-in-docker-hub) Configuring the webhook in Docker Hub ---------------------------------------------------------------------------------------------------------------------------------------------- To finish the configuration, refer to [Docker's own documentation](https://docs.docker.com/docker-hub/webhooks/) . [PreviousCreate a template from a deployed stack](https://docs.portainer.io/sts/user/docker/stacks/template) [NextMigrate or duplicate a stack](https://docs.portainer.io/sts/user/docker/stacks/migrate) Was this helpful? --- # Remove a stack | 2.35 STS | Portainer Documentation From the menu select **Stacks**, tick the checkbox next to the stack you want to remove, then click **Remove**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F6K6JN9TrY53GnDc1RV3f%2F2.20-stacks-remove.gif&width=768&dpr=4&quality=100&sign=add00e95&sv=2) When the confirmation message appears, click **Remove**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FUwAf9tvKEaWqBKSYgVub%2F2.15-stack-remove-confirm.png&width=768&dpr=4&quality=100&sign=ca4ae2b3&sv=2) [PreviousMigrate or duplicate a stack](https://docs.portainer.io/sts/user/docker/stacks/migrate) [NextServices](https://docs.portainer.io/sts/user/docker/services) Was this helpful? --- # Services | 2.35 STS | Portainer Documentation The **Services** menu is only available to Docker Swarm endpoints. A service consists of an image definition and container configuration as well as instructions on how those containers will be deployed across a Swarm cluster. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FnmA6xLrXlLDX3nxeFjuS%2F2.20-services-list.png&width=768&dpr=4&quality=100&sign=e1b06fae&sv=2) When the [new image indicator](https://docs.portainer.io/sts/user/docker/swarm/setup#other) feature is enabled, the **Images up to date** column indicates whether the local images in the service are up to date, with a green tick indicating they are up to date and an orange cross indicating that there is a newer version of an image available at the remote registry. A grey hyphen indicates Portainer was unable to determine whether there is an update available for the images. You can click the **Reload image indicators** button to recheck the images for all your services for updates, or to recheck a single service's images you can click the image indicator icon for that service. For more on how this works, have a look at [this article](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/how-does-the-image-update-notification-icon-work) . [Add a new service](https://docs.portainer.io/sts/user/docker/services/add) [Configure service options](https://docs.portainer.io/sts/user/docker/services/configure) Once a service has been created you can scale it to meet your needs, as well as view individual task status and logs. [Scale a service](https://docs.portainer.io/sts/user/docker/services/scale) [View the status of a service task](https://docs.portainer.io/sts/user/docker/services/tasks) [View service logs](https://docs.portainer.io/sts/user/docker/services/logs) If you need to undo some changes to a service, you can roll it back. [Roll back a service](https://docs.portainer.io/sts/user/docker/services/rollback) You can also configure webhooks for your services. [Webhooks](https://docs.portainer.io/sts/user/docker/services/webhooks) [PreviousRemove a stack](https://docs.portainer.io/sts/user/docker/stacks/remove) [NextAdd a new service](https://docs.portainer.io/sts/user/docker/services/add) Was this helpful? --- # Add a new service | 2.35 STS | Portainer Documentation From the menu click **Services** then click **Add service**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FRRm8PbjLhmHEJmHcf2wn%2F2.15-docker_services_add_service.gif&width=768&dpr=4&quality=100&sign=cf792211&sv=2) Complete the fields, using the table below as a guide. Field/Option Overview Name Give the service a descriptive name. Registry Select the registry that contains the image you wish to use for the service. Image Enter the name of the image. If you're using Docker Hub you can also search for images from here. Scheduling mode Select either to replicate the service on the same host or deploy it globally with one container on each host. Replicas Set the number of replicas (only if the scheduling mode is set to **Replicated**). Port mapping Define the ports to expose on the new service. Create a service webhook Toggle on to create a [webhook](https://docs.portainer.io/sts/user/docker/services/webhooks) for the service. You can send a POST request to this endpoint to automate pulling the most up-to-date image and re-deploy your service. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F6UA2TodoHQGRET7815lX%2F2.15-docker_service_create_service.png&width=768&dpr=4&quality=100&sign=2416ee7a&sv=2) You can also configure any advanced options for the service in the bottom section. When you're finished click **Create the service**. [PreviousServices](https://docs.portainer.io/sts/user/docker/services) [NextConfigure service options](https://docs.portainer.io/sts/user/docker/services/configure) Was this helpful? --- # Configure service options | 2.35 STS | Portainer Documentation From the menu select **Services** then select the service you want to configure. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FZLlGgEHZyrmw72vgCYPb%2F2.15-docker_services_configure.gif&width=768&dpr=4&quality=100&sign=9eb6e1e6&sv=2) [](https://docs.portainer.io/sts/user/docker/services/configure#service-details) Service details ----------------------------------------------------------------------------------------------------- In this section you can: * View a summary of the details about the service. * Configure the number of replicas. * Toggle the [service webhook](https://docs.portainer.io/sts/user/docker/services/webhooks) on or off. * View the [service logs](https://docs.portainer.io/sts/user/docker/services/logs) . * Update, [roll back](https://docs.portainer.io/sts/user/docker/services/rollback) or delete the service. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FJ0sxErnNUourBnYJW2iK%2F2.15-docker_services_service_details.png&width=768&dpr=4&quality=100&sign=316c939e&sv=2) [](https://docs.portainer.io/sts/user/docker/services/configure#container-specification-configuration-options) Container specification configuration options ----------------------------------------------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.portainer.io/sts/user/docker/services/configure#change-container-image) Change container image Here you can replace the container image with a different image. Select the registry, enter the image name, then click **Apply changes**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F4VQZ5VyLAGJTu2o6TMXa%2F2.15-docker_services_change_container_image.png&width=768&dpr=4&quality=100&sign=de7cb55e&sv=2) ### [](https://docs.portainer.io/sts/user/docker/services/configure#environment-variables) Environment variables It's best to set environment variables when you [create a container](https://docs.portainer.io/sts/user/docker/containers/add) and before deployment. You can still set or edit these variables after deployment if you wish. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FTMQUasrCFFgTat5LFWT0%2F2.15-docker_services_service_env_var.png&width=768&dpr=4&quality=100&sign=b4af26fe&sv=2) ### [](https://docs.portainer.io/sts/user/docker/services/configure#container-labels) Container labels Labels give you a way to record information about a container, such as the way it's configured. Labels can also be used by Portainer to [hide containers from the interface](https://docs.portainer.io/sts/admin/settings#hidden-containers) . ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F49Sp8kshE0SbLHZY2Ugw%2F2.15-docker_services_service_container_labels.png&width=768&dpr=4&quality=100&sign=63028114&sv=2) ### [](https://docs.portainer.io/sts/user/docker/services/configure#mounts) Mounts You have the option to either mount or bind volumes in Portainer, and you can also make them read only. To add a mount, first select either **Volume** or **Bind** from the **Type** dropdown. #### [](https://docs.portainer.io/sts/user/docker/services/configure#for-volume-mounts) For volume mounts: Select the volume from the **Source** dropdown, enter the container path in the **Target** field tick **Read only** if required then click **Apply changes**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FnsJgWdRYF6HtFsNWVaHu%2F2.15-docker_services_service_mounts_volume.png&width=768&dpr=4&quality=100&sign=1ab2dc0&sv=2) #### [](https://docs.portainer.io/sts/user/docker/services/configure#for-bind-mounts) For bind mounts: Enter the source path in the **Source** field, enter the container path in the **Target** field, tick **Read only** if required then click **Apply changes**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2Fz40Fq1XXo8KMzTfHqsiZ%2F2.15-docker_services_service_mounts_bind.png&width=768&dpr=4&quality=100&sign=2bf1bccd&sv=2) [](https://docs.portainer.io/sts/user/docker/services/configure#networks-and-ports-configuration-options) Networks & ports configuration options ----------------------------------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.portainer.io/sts/user/docker/services/configure#networks) Networks You can define one or more networks for a service either before or after deployment. Simply select the network from the dropdown then click **Apply changes**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FQ3ScGfgqVVoOkhl6AdeY%2F2.15-docker_services_service_networks.png&width=768&dpr=4&quality=100&sign=3923afb5&sv=2) ### [](https://docs.portainer.io/sts/user/docker/services/configure#published-ports) Published ports Use this setting to publish ports so they can access a container from outside of the host. You can either add new ports or update existing ports. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F72JHJNU7jbLkK9y1tSOV%2F2.15-docker_services_service_published_ports.png&width=768&dpr=4&quality=100&sign=a5348b5c&sv=2) ### [](https://docs.portainer.io/sts/user/docker/services/configure#hosts-file-entries) Hosts file entries Lets you manually specify a hostname or URL and associate the URL to an internal or external IP address. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FYDoqotnKOsvZacaq7dUv%2F2.15-docker_services_service_host_entries.png&width=768&dpr=4&quality=100&sign=69739959&sv=2) [](https://docs.portainer.io/sts/user/docker/services/configure#service-specification-settings) Service specification settings ----------------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.portainer.io/sts/user/docker/services/configure#resource-limits-and-reservations) Resource limits and reservations Sets limits on resource utilization, such as memory, CPU reservation and CPU limit. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FjO9Vwvrom3yXDrSkHvMT%2F2.15-docker_services_service_resource_limits.png&width=768&dpr=4&quality=100&sign=8687c430&sv=2) ### [](https://docs.portainer.io/sts/user/docker/services/configure#placement-constraints) Placement constraints Use placement constraints to control which nodes a service can be assigned to. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F0dBk1TrFy9FlrIIMeFay%2F2.15-docker_services_service_placement_constraint.png&width=768&dpr=4&quality=100&sign=8e05d1fc&sv=2) ### [](https://docs.portainer.io/sts/user/docker/services/configure#placement-preferences) Placement preferences While placement constraints limit the nodes a service can run on, placement preferences attempt to place tasks on appropriate nodes in an algorithmic way (by default they are spread evenly). ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FVxTGASKUWoY9skrwf3uo%2F2.15-docker_services_service_placement_pref.png&width=768&dpr=4&quality=100&sign=1bf7c1b9&sv=2) ### [](https://docs.portainer.io/sts/user/docker/services/configure#restart-policy) Restart policy Docker's restart policies ensure that linked containers are restarted in the correct order, and control the conditions under which they are restarted: * **Any**: Restart the container under any conditions (restarted host or Docker daemon). * **On Failure**: Restart the container if it exits due to an error which manifests as a non-zero exit code. * **None**: Do not automatically restart the container. You can also adjust the restart delay, maximum attempts and restart window. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FUWy8trAFoV1l7zoWDzyY%2F2.15-docker_services_service_restart_policy.png&width=768&dpr=4&quality=100&sign=f8981506&sv=2) ### [](https://docs.portainer.io/sts/user/docker/services/configure#update-configuration) Update configuration Updates a service according to the parameters you specify. The parameters specified here are the same as `docker service create` (see [Docker's own documentation](https://docs.docker.com/engine/reference/commandline/service_create/) for more information). Normally, updating a service will only cause the service’s tasks to be replaced with new ones if a change to the service requires recreating the tasks for it to take effect. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FljwBqz6DA5s8v9kgCggU%2F2.15-docker_services_service_update_config.png&width=768&dpr=4&quality=100&sign=77eec7a9&sv=2) ### [](https://docs.portainer.io/sts/user/docker/services/configure#logging-driver) Logging driver Docker includes logging mechanisms called _logging drivers_ that get information from the containers and services you're running. Each Docker daemon has a default logging driver which each container will use, unless you configure them to use a different logging driver. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FpMEfCh950WWDfShKp8Sd%2F2.15-docker_services_service_logging_driver.png&width=768&dpr=4&quality=100&sign=751795bf&sv=2) ### [](https://docs.portainer.io/sts/user/docker/services/configure#service-labels) Service labels Lets you add metadata to containers using Docker labels either via an array or a dictionary. We recommend that you use reverse-DNS notation to stop labels from conflicting with those used by other software. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FWweUkak4r6113MO1jmCG%2F2.15-docker_services_service_labels.png&width=768&dpr=4&quality=100&sign=cdf62d56&sv=2) ### [](https://docs.portainer.io/sts/user/docker/services/configure#configs) Configs Docker 17.06 introduced Swarm service configs. These allow you to store non-sensitive information such as configuration files outside a service’s image or running containers. This keeps images as generic as possible and removes the need to bind-mount configuration files into containers or use environment variables. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2Fi4OqDYImBV9v0vyNX6QZ%2F2.15-docker_services_service_configs.png&width=768&dpr=4&quality=100&sign=671e4535&sv=2) ### [](https://docs.portainer.io/sts/user/docker/services/configure#secrets) Secrets In the context of Docker Swarm services, a secret is a blob of data such as a password, SSH private key, SSL certificate, or another piece of data that should not be transmitted over a network or stored unencrypted in a Dockerfile or in your application’s source code. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FxEjEiBeVZrYnact53afV%2F2.15-docker_services_service_secrets.png&width=768&dpr=4&quality=100&sign=c18758b6&sv=2) [PreviousAdd a new service](https://docs.portainer.io/sts/user/docker/services/add) [NextScale a service](https://docs.portainer.io/sts/user/docker/services/scale) Was this helpful? --- # Scale a service | 2.35 STS | Portainer Documentation From the menu select **Services** then select **scale** next to the service you want to scale (in the **Scheduling Mode** column). ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FlbFBJqxQh8lgbhdEp7Oi%2F2.15-docker_services_scale.gif&width=768&dpr=4&quality=100&sign=a45af3a7&sv=2) Select the number of replicas you want to create for the service then click the tick icon to apply. If scaling is successful, a success message will appear at the top-right of the screen. Refresh the page until the running replicas appear. Depending on container size, there might be a slight delay before the replicas appear on screen. [PreviousConfigure service options](https://docs.portainer.io/sts/user/docker/services/configure) [NextView the status of a service task](https://docs.portainer.io/sts/user/docker/services/tasks) Was this helpful? --- # Troubleshooting | 2.35 STS | Portainer Documentation [Access and authentication](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication) [Agents and environment management](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management) [Stacks, deployments and updates](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates) [UI and features](https://docs.portainer.io/sts/faqs/troubleshooting/ui-and-features) [Logs, errors and debugging](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging) [Certificates and security](https://docs.portainer.io/sts/faqs/troubleshooting/certificates-and-security) [Registry and image management](https://docs.portainer.io/sts/faqs/troubleshooting/registry-and-image-management) [PreviousHow do I renew my 5 nodes free license?](https://docs.portainer.io/sts/faqs/licensing/how-do-i-renew-my-5-nodes-free-license) [NextAccess and authentication](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication) Was this helpful? --- # Access and authentication | 2.35 STS | Portainer Documentation [How can I switch back to internal authentication?](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication/how-can-i-switch-back-to-internal-authentication) [I enabled "Force HTTPS only" and now I'm locked out of Portainer. How do I get back in?](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication/i-enabled-force-https-only-and-now-im-locked-out-of-portainer.-how-do-i-get-back-in) [How do I reset my Portainer password?](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication/how-do-i-reset-my-portainer-password) [Client sent an HTTP request to an HTTPS server](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication/client-sent-an-http-request-to-an-https-server) [Unable to Authenticate After Portainer Update](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication/unable-to-authenticate-after-portainer-update) [Unable to Login via LDAP in Portainer](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication/unable-to-login-via-ldap-in-portainer) [PreviousTroubleshooting](https://docs.portainer.io/sts/faqs/troubleshooting) [NextHow can I switch back to internal authentication?](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication/how-can-i-switch-back-to-internal-authentication) Was this helpful? --- # How do I renew my 5 nodes free license? | 2.35 STS | Portainer Documentation It's important to note: * At the expiry date of your current license, our 5 Nodes Free license will be available **for non-commercial use only**. If you are currently using the 5 Nodes Free license for commercial purposes, please switch to a 3 Nodes Free license by visiting [this link](https://www.portainer.io/switch-to-a-3-nodes-free-license-key-for-5-nodes-free-users?hsLang=en) . * At expiry, non-commercial 5 Nodes Free license holders (home users, hobbyists, and students) who need more than 3 nodes can apply for a new 5 Nodes Free license under the updated [5 nodes free renewal license agreement](https://www.portainer.io/5nf-license-agreement-renewal?hsLang=en) . * Current 5 Nodes Free home or business users who need 3 nodes or less will be able to [switch to our 3 Nodes Free program](https://www.portainer.io/switch-to-a-3-nodes-free-license-key-for-5-nodes-free-users?hsLang=en) when their current 5 Node Free license expires. * For business users who need more than 3 nodes at the expiry date of their current 5 Nodes Free license, we offer a range of [pricing](https://www.portainer.io/pricing?hsLang=en) to suit different needs and we'd be happy to work with you to find something suitable. * Please note that we will delay the send of your new key until 14 days before your current license expiry date**.** You'll need to provide: * The email that you used to signup Here's the link to the form to [Request a renewal of a 5 nodes free license](https://www.portainer.io/5nf-renewal-license-key-for-home-users?hsLang=en) . Any problems please email: [\[email protected\]](https://docs.portainer.io/cdn-cgi/l/email-protection#c6b5b3a5a5a3b5b586b6a9b4b2a7afa8a3b4e8afa9) [PreviousHow do I renew my 3 nodes free license?](https://docs.portainer.io/sts/faqs/licensing/how-do-i-renew-my-3-nodes-free-license) [NextTroubleshooting](https://docs.portainer.io/sts/faqs/troubleshooting) Was this helpful? --- # How can I switch back to internal authentication? | 2.35 STS | Portainer Documentation If you are able to log into Portainer as an administrator you can change your authentication method under Settings, [Authentication](https://docs.portainer.io/sts/admin/settings/authentication) and selecting Internal. If you are unable to log into Portainer (for example if you have been locked out due to a external authentication / SSO misconfiguration) you can force using internal authentication by going to: Copy https://localhost:9443/#!/internal-auth Replace https://localhost:9443 with the URL and port of your Portainer server. You can then log in as the initial administrator user you first set up when installing Portainer. If you don't have the password for the initial administrator user, you can use our [password reset helper.](https://docs.portainer.io/sts/advanced/reset-admin) [PreviousAccess and authentication](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication) [NextI enabled "Force HTTPS only" and now I'm locked out of Portainer. How do I get back in?](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication/i-enabled-force-https-only-and-now-im-locked-out-of-portainer.-how-do-i-get-back-in) Was this helpful? --- # How do I reset my Portainer password? | 2.35 STS | Portainer Documentation If you know your current password and can log into Portainer, you can set a new password via the Portainer UI. If you have forgotten your password or are unable to log in, either ask another Portainer admin to reset the password for you, or use our [password reset helper](https://docs.portainer.io/sts/advanced/reset-admin) to reset the default admin account password (from when Portainer was initialized). [PreviousI enabled "Force HTTPS only" and now I'm locked out of Portainer. How do I get back in?](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication/i-enabled-force-https-only-and-now-im-locked-out-of-portainer.-how-do-i-get-back-in) [NextClient sent an HTTP request to an HTTPS server](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication/client-sent-an-http-request-to-an-https-server) Was this helpful? --- # Why has my Environment IP not updated after I changed it? | 2.35 STS | Portainer Documentation If you have updated your Portainer Agent environment's IP address, you may not see the update apply correctly in your Portainer Server instance. To resolve this, restart your Portainer Server container. Assuming you have followed our [install instructions](https://docs.portainer.io/sts/start/install/server) , you can do this from the command line: On Docker Standalone: Copy docker restart portainer On Docker Swarm: Copy docker service update --force portainer_portainer On Kubernetes: Copy kubectl -n portainer rollout restart deployment.apps/portainer [PreviousWhy can't my agents communicate with Portainer on Swarm?](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/why-cant-my-agents-communicate-with-portainer-on-swarm) [NextWhy is my Portainer Edge Agent using a large amount of memory?](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/why-is-my-portainer-edge-agent-using-a-large-amount-of-memory) Was this helpful? --- # Unable to Authenticate After Portainer Update | 2.35 STS | Portainer Documentation **Issue** After updating Portainer, login attempts result in a 403 Forbidden error. The UI loads correctly, but authentication fails. **Symptoms** * Logging in returns “Unable to login” with no server-side logs. * Browser console shows: Copy POST https:///portainer/api/auth 403 (Forbidden) **Cause** Portainer releases include security patches, including fixes for known CVEs. These changes invalidate existing authentication sessions server-side. However, the client (browser) may still store outdated tokens in cache or local storage, leading to failed authentication requests. **Resolution** Clear your browser cache and try logging in again. **Alternative Workaround** Open the Portainer login page in an incognito/private browsing window and attempt to log in from there. **Technical Context** Authentication tokens persisted in local storage or cookies can conflict with the updated server-side session handling introduced in this version. Since no auth request is successfully processed by the server, there are no related logs. [PreviousClient sent an HTTP request to an HTTPS server](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication/client-sent-an-http-request-to-an-https-server) [NextUnable to Login via LDAP in Portainer](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication/unable-to-login-via-ldap-in-portainer) Was this helpful? --- # Client sent an HTTP request to an HTTPS server | 2.35 STS | Portainer Documentation #### [](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication/client-sent-an-http-request-to-an-https-server#issue-description) Issue Description When accessing Portainer via the web you may receive the following error message: Copy Client sent an HTTP request to an HTTPS server. #### [](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication/client-sent-an-http-request-to-an-https-server#cause) Cause This error occurs when you attempt to access Portainer's HTTPS URL (port 9443) using the HTTP protocol: Copy http://my.portainer.url:9443/ This is because port 9443 only accepts the HTTPS protocol and does not accept HTTP requests. #### [](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication/client-sent-an-http-request-to-an-https-server#resolution) Resolution Use the HTTPS protocol in the address when accessing port 9443. Copy https://my.portainer.url:9443/ Alternatively if you have HTTP access enabled you can access via HTTP on port 9000: Copy http://my.portainer.url:9000/ [PreviousHow do I reset my Portainer password?](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication/how-do-i-reset-my-portainer-password) [NextUnable to Authenticate After Portainer Update](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication/unable-to-authenticate-after-portainer-update) Was this helpful? --- # I enabled "Force HTTPS only" and now I'm locked out of Portainer. How do I get back in? | 2.35 STS | Portainer Documentation Enabling the **Force HTTPS only** option (either via the toggle in [Settings](https://docs.portainer.io/sts/admin/settings) or via the --http-disabled command line option) disables logging into Portainer via HTTP. If your HTTPS setup is misconfigured (for example a malformed or missing certificate chain) this can result in you being locked out of Portainer. To resolve this, you can re-enable HTTP access by using the --http-enabled command line option in your docker run command, for example: **Business Edition:** Copy docker run -d -p 8000:8000 -p 9000:9000 -p 9443:9443 --name portainer \   --restart=always \   -v /var/run/docker.sock:/var/run/docker.sock \   -v portainer_data:/data \   portainer/portainer-ee:latest \   --http-enabled **Community Edition:** Copy docker run -d -p 8000:8000 -p 9000:9000 -p 9443:9443 --name portainer \   --restart=always \   -v /var/run/docker.sock:/var/run/docker.sock \   -v portainer_data:/data \ portainer/portainer-ce:latest \   --http-enabled Make sure to remove the --http-disabled option from your command if you are using it, as this will override the --http-enabled flag. When started with the --http-enabled flag, you will be able to access Portainer over HTTP once more. **Alternative: Edit the database directly** If you are using database encryption you will be unable to use this method. If you are unable to adjust the run command to include the command line option, you can edit the Portainer database to re-enable HTTP access. The Portainer database is a BoltDB database named portainer.db and can be found in the portainer\_data volume. To edit the database: 1. Stop the Portainer container to ensure there are no locks on the database. 2. Open the portainer.db file in a BoltDB editor (for example [boltbrowser](https://github.com/br0xen/boltbrowser) ). 3. Expand the ssl path and set the httpEnabled option to true. 4. Save and exit the editor and restart the Portainer container with the updated database. You should now be able to log in to Portainer using HTTP. [PreviousHow can I switch back to internal authentication?](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication/how-can-i-switch-back-to-internal-authentication) [NextHow do I reset my Portainer password?](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication/how-do-i-reset-my-portainer-password) Was this helpful? --- # Agents and environment management | 2.35 STS | Portainer Documentation [How can I move existing Edge Agent deployments to a new Portainer Server instance?](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/how-can-i-move-existing-edge-agent-deployments-to-a-new-portainer-server-instance) [Why can't my agents communicate with Portainer on Swarm?](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/why-cant-my-agents-communicate-with-portainer-on-swarm) [Why has my Environment IP not updated after I changed it?](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/why-has-my-environment-ip-not-updated-after-i-changed-it) [Why is my Portainer Edge Agent using a large amount of memory?](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/why-is-my-portainer-edge-agent-using-a-large-amount-of-memory) [Troubleshooting Edge Agent Connection Issues](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/troubleshooting-edge-agent-connection-issues) [How do I change the way I connect to an environment without losing my existing stacks?](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/how-do-i-change-the-way-i-connect-to-an-environment-without-losing-my-existing-stacks) [PreviousUnable to Login via LDAP in Portainer](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication/unable-to-login-via-ldap-in-portainer) [NextHow can I move existing Edge Agent deployments to a new Portainer Server instance?](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/how-can-i-move-existing-edge-agent-deployments-to-a-new-portainer-server-instance) Was this helpful? --- # Why is my Portainer Edge Agent using a large amount of memory? | 2.35 STS | Portainer Documentation #### [](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/why-is-my-portainer-edge-agent-using-a-large-amount-of-memory#problem) **Problem** Some users have experienced excessive memory usage from the Portainer Edge Agent running on their devices. After restarting the container, memory usage typically drops back but gradually climbs again over time. #### [](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/why-is-my-portainer-edge-agent-using-a-large-amount-of-memory#cause) **Cause** This issue is caused by a memory leak affecting **Edge Agent versions from 2.21.3 up until the fix introduced in version 2.26**. These versions are known to exhibit abnormal memory growth during runtime. #### [](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/why-is-my-portainer-edge-agent-using-a-large-amount-of-memory#resolution) **Resolution** The memory leak was **resolved in version 2.26**. Updating the Edge Agent to **2.26 or higher** will resolve the issue. [PreviousWhy has my Environment IP not updated after I changed it?](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/why-has-my-environment-ip-not-updated-after-i-changed-it) [NextTroubleshooting Edge Agent Connection Issues](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/troubleshooting-edge-agent-connection-issues) Was this helpful? --- # Troubleshooting Edge Agent Connection Issues | 2.35 STS | Portainer Documentation #### [](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/troubleshooting-edge-agent-connection-issues#before-you-begin-network-troubleshooting) **Before you begin network troubleshooting:** Check your **Portainer Edge Compute Settings** by navigating to **Settings** > **Edge Compute** > **Edge Compute Settings**. - Confirm that the **Portainer API Server URL** and the **Portainer Tunnel Address** are correct. - Ensure that ports **9443** and **8000** are open in your firewall. - Refer to the official Portainer documentation for detailed agent setup [requirements](https://docs.portainer.io/sts/advanced/edge-agent) * * * **What should I do if my Edge agent is unable to associate with the Portainer server?** If your Edge agent fails to connect to the Portainer server, the first step is to verify if the issue is isolated to one agent or affects multiple agents. If only one agent is experiencing connectivity issues, it suggests that the problem may be specific to that environment or configuration. * * * **How can I verify if my Edge agent is properly connected to the Portainer server?** You can test the connection between the Edge agent host and the Portainer server by using \`telnet\` to check port 9443: Copy telnet 9443 If this test succeeds, it confirms that the network traffic is not being blocked, meaning the issue may lie elsewhere. * * * **How can I further troubleshoot connection problems between the Edge agent and the Portainer server?** Run a `curl` command from the Edge agent to the Portainer server to verify connectivity and check for TLS handshake errors. Use the following command: Copy curl -v https://:9443 If you receive an error such as "Connection reset by peer," it indicates that the connection attempt is being blocked, likely due to a network or firewall issue. * * * **What does the "Connection reset by peer" error mean, and how can I fix it?** The "Connection reset by peer" error usually occurs when the connection between the Edge agent and the Portainer server is prematurely closed. This may happen due to a firewall, incorrect SSL/TLS configuration, or other network issues. Make sure that the firewall allows traffic on the correct ports (9443 and 8000), and verify that your TLS certificates are properly configured. * * * **How do I confirm that the Portainer server's configuration is not causing the issue?** If other Edge agents are able to connect without issues, this suggests that the Portainer server configuration is correct. The problem is likely isolated to the network or configuration of the specific agent that is failing to connect. * * * **What should I do if my Edge agent still can't connect after verifying the network settings?** If network settings and firewall rules appear correct but the issue persists, it may be necessary to consult with your network team or vendor. In some cases, subtle network misconfigurations, such as incorrect VLAN settings or firewall rules, can cause the Edge agent to fail to connect to the Portainer server. Once the underlying network issues are resolved, the agent should reconnect and show a healthy heartbeat. [PreviousWhy is my Portainer Edge Agent using a large amount of memory?](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/why-is-my-portainer-edge-agent-using-a-large-amount-of-memory) [NextHow do I change the way I connect to an environment without losing my existing stacks?](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/how-do-i-change-the-way-i-connect-to-an-environment-without-losing-my-existing-stacks) Was this helpful? --- # How can I move existing Edge Agent deployments to a new Portainer Server instance? | 2.35 STS | Portainer Documentation In order to change the Portainer server URL for an Edge Agent, a redeployment of the Edge Agent is necessary. A redeployment involves removing the existing Edge Agent from Portainer, stopping and removing the portainer\_edge\_agent container on the edge device, recreating the Edge Agent in Portainer, and redeploying it on the edge device. When deploying an Edge Agent, the Portainer server URL is encrypted into the Edge key. This tells the Edge Agent where to look for the Portainer server. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FDug0VxLtrPWXI6UUNtxN%2Fimage.png&width=768&dpr=4&quality=100&sign=cc1ea3d1&sv=2) The most typical scenarios that require a change to the Portainer server URL are: * Edge Agent was originally configured with an IP address (e.g., https://172.16.1.1:9443) and the Portainer instance is being moved to new location with a different IP address. * Edge Agent was originally configured with an IP address (e.g., https://172.16.1.1:9443) and will now be using a DNS name (e.g., https://portainer.mydomain.tld:9443) * Edge Agent was originally configured with a DNS name (e.g., https://portainer.mydomain.tld:9443) and now that name needs to change. * Edge Agent was originally configured with a DNS name (e.g., https://portainer.mydomain.tld:9443) and now will be accessed via its IP address. [PreviousAgents and environment management](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management) [NextWhy can't my agents communicate with Portainer on Swarm?](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/why-cant-my-agents-communicate-with-portainer-on-swarm) Was this helpful? --- # Why can't my agents communicate with Portainer on Swarm? | 2.35 STS | Portainer Documentation If you are running on a VMware environment, have a look at this article as well. You have set up a multi-node Swarm cluster and have deployed the Portainer Agent across the cluster successfully, but the Agent is failing to communicate with the Portainer Server. You may see log messages similar to the following: `[err: Cannot connect to the Docker daemon at tcp://tasks.portainer_agent:9001. Is the docker daemon running?]` `[err: Error response from daemon: The agent was unable to contact any other agent located on a manager node]` We have most commonly seen this on hosting providers such as Hetzner where the network used to communicate between Swarm nodes uses a MTU that is not 1500. Hetzner's private networking, for example, uses a MTU of 1450. Docker Swarm's default network MTU is 1500, and if the underlying network has a lower MTU than this the Swarm nodes may fail to communicate with each other. This would affect all Swarm services, not just Portainer. The solution to this is to adjust Docker Swarm's MTU to match that of the underlying network. First, you'll want to determine what the MTU of your network is. On Linux, you can find this with the following command: Copy ip a This will list the networks available on your server. Locate the network that your nodes communicate over and note the value after mtu. For example: Copy 5: ens10: mtu 1450 qdisc pfifo_fast state UP group default qlen 1000 In the above, the MTU is set to 1450. To use this new MTU, you will first need to remove and recreate the ingress network with the new value. You can use the following commands to achieve this: Copy docker network rm ingress docker network create -d overlay --ingress --opt com.docker.network.driver.mtu=1450 ingress Then, when you are creating new networks you will need to set the MTU to match. For example, in a compose file: Copy networks: default: driver: overlay driver_opts: com.docker.network.driver.mtu: 1450 [PreviousHow can I move existing Edge Agent deployments to a new Portainer Server instance?](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/how-can-i-move-existing-edge-agent-deployments-to-a-new-portainer-server-instance) [NextWhy has my Environment IP not updated after I changed it?](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/why-has-my-environment-ip-not-updated-after-i-changed-it) Was this helpful? --- # Unable to Login via LDAP in Portainer | 2.35 STS | Portainer Documentation **Issue:** Users encounter the following error in the Portainer logs when attempting to login via an LDAP user: Copy level=info msg="http error: Only initial admin is allowed to login without oauth (err=LDAP Result Code 49 \"Invalid Credentials\": 80090308: LdapErr: DSID-0C090511, comment: AcceptSecurityContext error, data 533, v4f7c\x00) (code=403)" **Cause:** This error occurs when the LDAP credentials configured in Portainer are no longer valid. It typically happens when the LDAP service account password has been changed or the account is no longer authorized. **Resolution:** To resolve this issue, follow these steps: 1 **Log in with a Local Portainer Admin Account** Use a local Portainer admin account to access the Portainer web interface. 2 **Update LDAP Credentials** • Navigate to **Settings** > **Authentication** in the Portainer interface. • Update the **LDAP password** with the correct credentials for the LDAP account. 3 **Verify Connectivity** • Perform a **Connectivity Check** to confirm the LDAP configuration is valid. • Ensure the test passes before saving changes. 4 **Save Changes** Save the updated settings and ensure that the connection is stable. [PreviousUnable to Authenticate After Portainer Update](https://docs.portainer.io/sts/faqs/troubleshooting/access-and-authentication/unable-to-authenticate-after-portainer-update) [NextAgents and environment management](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management) Was this helpful? --- # How do I change the way I connect to an environment without losing my existing stacks? | 2.35 STS | Portainer Documentation Note that these steps apply to Docker environments only. In the case of changing the way you connect to an environment (for example by moving from connecting to the Docker socket directly to using a socket proxy) you can move your stacks by: 1 ### [](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/how-do-i-change-the-way-i-connect-to-an-environment-without-losing-my-existing-stacks#removing-the-current-environment-connection-in-portainer) Removing the current environment connection in Portainer Under **Administration**, navigate to **Environment-related**, then to **Environments**. Select the environment you would like to remove and click **Remove.** The stacks in this environment will become orphaned, and therefore available to be re-associated once you re-add the environment in the next step. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FxVdMdAICrm1q5727xepN%2Fimage.png&width=768&dpr=4&quality=100&sign=32efbc4a&sv=2) 2 ### [](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/how-do-i-change-the-way-i-connect-to-an-environment-without-losing-my-existing-stacks#adding-a-new-environment-using-the-new-connection-method) Adding a new environment using the new connection method [Add the environment again](https://docs.portainer.io/sts/admin/environments/add) using the new connection method. 3 ### [](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/how-do-i-change-the-way-i-connect-to-an-environment-without-losing-my-existing-stacks#re-associating-the-orphaned-stacks-with-the-new-environment) Re-associating the orphaned stacks with the new environment Within the environment that you want to associate your orphaned stacks with, click **Stacks** in the left hand menu. At the Stacks list, click on the three dots in the top right corner and select **Show all orphaned stacks**. Your stack list will then update to include any orphaned stacks. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FFxKqJLW1u99usoApFaf5%2Fimage.png&width=768&dpr=4&quality=100&sign=94750a66&sv=2) Click into the stack that you want to recover, and select **Associate.** ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FlHeBpi3tcxk2o9OUJC8E%2Fimage.png&width=768&dpr=4&quality=100&sign=b3b5c558&sv=2) Your stack will now appear in your stack list with total control. Repeat this process for each stack you want to re-associate. [PreviousTroubleshooting Edge Agent Connection Issues](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/troubleshooting-edge-agent-connection-issues) [NextStacks, deployments and updates](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates) Was this helpful? --- # Stacks, deployments and updates | 2.35 STS | Portainer Documentation [How do automatic updates for stacks/applications work?](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/how-do-automatic-updates-for-stacks-applications-work) [How does the image update notification icon work?](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/how-does-the-image-update-notification-icon-work) [Can I build an image while deploying a stack/application from Git?](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/can-i-build-an-image-while-deploying-a-stack-application-from-git) [Why don't custom standalone app templates show when using Docker Swarm?](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/why-dont-custom-standalone-app-templates-show-when-using-docker-swarm) [How do I configure Portainer's GitOps features to authenticate to a Bitbucket repository?](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/how-do-i-configure-portainers-gitops-features-to-authenticate-to-a-bitbucket-repository) [Why are stack deployment times slow?](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/why-are-stack-deployment-times-slow) [Environment Variable Management in Docker: .env vs. stack.env](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/environment-variable-management-in-docker-.env-vs.-stack.env) [How do I recover orphaned stacks from a previously deleted environment?](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/how-do-i-recover-orphaned-stacks-from-a-previously-deleted-environment) [PreviousHow do I change the way I connect to an environment without losing my existing stacks?](https://docs.portainer.io/sts/faqs/troubleshooting/agents-and-environment-management/how-do-i-change-the-way-i-connect-to-an-environment-without-losing-my-existing-stacks) [NextHow do automatic updates for stacks/applications work?](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/how-do-automatic-updates-for-stacks-applications-work) Was this helpful? --- # How does the image update notification icon work? | 2.35 STS | Portainer Documentation In 2.14 we introduced a visual indicator next to containers, stacks and services so that users can quickly see whether images are up to date or whether a new version was available. This functionality works as follows: * Portainer looks at the first local digest of the image and compares it to the remote digest of the image. If the digests differ, then we assume a new version is available. This check is done on page refresh (with a bit of caching to not hamper performance). * The new version is based on the image _and_ tag, not just the image. * If a local copy of the image and tag already exists but hasn't been deployed, the circle will display as grey and the image name will change to the hash. This is partially due to how Docker itself works (you'd see the same "hash as the image name" behavior when doing docker ps), but we're discussing ways that we might be able to make this more user-friendly in the future. [PreviousHow do automatic updates for stacks/applications work?](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/how-do-automatic-updates-for-stacks-applications-work) [NextCan I build an image while deploying a stack/application from Git?](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/can-i-build-an-image-while-deploying-a-stack-application-from-git) Was this helpful? --- # How do automatic updates for stacks/applications work? | 2.35 STS | Portainer Documentation When you configure automatic updates for a [stack](https://docs.portainer.io/sts/user/docker/stacks) or [application](https://docs.portainer.io/sts/user/kubernetes/applications/manifest) deployed from a Git repository, you can choose for Portainer to either poll the Git repository for updates on a defined interval, or use a webhook to trigger a check on-demand (generally as part of an automated process). Regardless of the method you choose, the following events occur when a check is performed: * Portainer connects to the remote Git repository and retrieves the hash of the latest commit. * If the latest commit hash matches the hash that Portainer has in its database for the stack/application, Portainer assumes that the stack/application is up to date, and no further action is taken. Portainer stores the commit hash of the latest deploy of a stack/application in its database. This is first populated on initial deployment and updated on each deployment. If the latest commit hash does **not** match the hash in the database, Portainer pulls the repository contents at the latest commit. Portainer then processes the file defined as the **Compose path** for the stack/application as well as any **additional paths** defined. For **Docker Standalone**, this involves running: Copy docker-compose up -f my-compose-file -f additional-compose-file -up d in the working directory of the cloned repository (the directory containing the file defined as **Compose path**). For **Docker Swarm**, this involves running: Copy docker stack deploy --compose-file my-compose-file --compose-file compose-additional-file using the file defined in the Compose path and any additional compose paths defined. For **Kubernetes**, this involves running: Copy kubectl apply -f my-compose-file -f additional-compose-file using the file defined in the Compose path and any additional compose paths defined. For all platforms, we do **not** force a redeployment if the image has not updated (the default behavior of each of the tools). Therefore, if Docker or Kubernetes determines the image hasn't changed for a container it will **not** redeploy that container. The commit hash in the Portainer database is updated to match the newly deployed commit hash. Portainer doesn't otherwise reference any other files in the repository, unless those files are referenced by the compose files. This [can have consequences](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/can-i-build-an-image-while-deploying-a-stack-application-from-git) if you are trying to build an image within your compose file. The exception to this is the .env file, which if it exists (and environment variables have not been previously defined) is processed as well. The above commit hash checks are not performed if a stack or application is manually updated (for example using the **Pull and redeploy** button). In this case, the stack or application would be force-redeployed. [PreviousStacks, deployments and updates](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates) [NextHow does the image update notification icon work?](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/how-does-the-image-update-notification-icon-work) Was this helpful? --- # Can I build an image while deploying a stack/application from Git? | 2.35 STS | Portainer Documentation Our Git repository support is in its first version currently, so it is not fully-featured. One of the elements that are currently not fully implemented is building images via docker-compose, particularly around building from files that are included in the repository. We hope to expand the capability of this in the future. If the image is [built separately](https://docs.portainer.io/sts/user/docker/images/build) and referenced from docker-compose, it should install without an issue. [PreviousHow does the image update notification icon work?](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/how-does-the-image-update-notification-icon-work) [NextWhy don't custom standalone app templates show when using Docker Swarm?](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/why-dont-custom-standalone-app-templates-show-when-using-docker-swarm) Was this helpful? --- # Why don't custom standalone app templates show when using Docker Swarm? | 2.35 STS | Portainer Documentation One of Portainer's key principles is to enforce best practice across all functions — including Swarm. When you use Swarm, always use Swarm services, not containers. [PreviousCan I build an image while deploying a stack/application from Git?](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/can-i-build-an-image-while-deploying-a-stack-application-from-git) [NextHow do I configure Portainer's GitOps features to authenticate to a Bitbucket repository?](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/how-do-i-configure-portainers-gitops-features-to-authenticate-to-a-bitbucket-repository) Was this helpful? --- # How do I configure Portainer's GitOps features to authenticate to a Bitbucket repository? | 2.35 STS | Portainer Documentation The following instructions acknowledge that Bitbucket has announced the [deprecation of app passwords in Bitbucket Cloud](https://www.atlassian.com/blog/bitbucket/bitbucket-cloud-transitions-to-api-tokens-enhancing-security-with-app-password-deprecation) . When deploying a stack from a private Bitbucket repository, the authentication method will differ depending on how your bitbucket is hosted. * **Bitbucket cloud:** Use an [**API token**](https://support.atlassian.com/bitbucket-cloud/docs/api-tokens/) or [**access token**](https://support.atlassian.com/bitbucket-cloud/docs/access-tokens/) with **basic authentication**. * **Bitbucket Data Center:** Use a [**Personal Access Token**](https://confluence.atlassian.com/bitbucketserver/http-access-tokens-939515499.html) with **bearer token authentication.** [PreviousWhy don't custom standalone app templates show when using Docker Swarm?](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/why-dont-custom-standalone-app-templates-show-when-using-docker-swarm) [NextWhy are stack deployment times slow?](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/why-are-stack-deployment-times-slow) Was this helpful? --- # Why are stack deployment times slow? | 2.35 STS | Portainer Documentation Slow stack deployments within Portainer, particularly when these delays are not present during command line deployments, are often due to the Portainer environment's authentication process with configured registries. There are two main factors contributing to this: 1. **Registry Configuration Checks**: When registries are configured in your Portainer environment, it attempts to verify access to these registries before proceeding with the stack deployment. Having numerous registries to check can lengthen this verification process, thereby delaying the deployment. 2. **Authentication Timeouts**: If your Portainer environment encounters issues authenticating with a registry, it will wait for a timeout period before bypassing that registry. This waiting period can significantly contribute to the overall delay in stack deployments. 1. Ensure that the registry credentials are correct and up-to-date for each registry. 2. Check the networking between the Portainer environment and each registry. Ensure that all necessary firewall ports are open for this connection. [PreviousHow do I configure Portainer's GitOps features to authenticate to a Bitbucket repository?](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/how-do-i-configure-portainers-gitops-features-to-authenticate-to-a-bitbucket-repository) [NextEnvironment Variable Management in Docker: .env vs. stack.env](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/environment-variable-management-in-docker-.env-vs.-stack.env) Was this helpful? --- # Environment Variable Management in Docker: .env vs. stack.env | 2.35 STS | Portainer Documentation ### [](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/environment-variable-management-in-docker-.env-vs.-stack.env#overview) **Overview** When deploying containerized applications, managing environment variables is crucial for configuration flexibility. Docker provides two common approaches: * `**.env**` **File**: Used with Docker Compose for standalone deployments. * `**stack.env**` **File**: Used with Docker Swarm for orchestrated, multi-host deployments. Understanding the differences between these files will help you choose the right method for your deployment environment. * * * ### [](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/environment-variable-management-in-docker-.env-vs.-stack.env#docker-compose-and-the-.env-file) **Docker Compose and the** `**.env**` **File** #### [](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/environment-variable-management-in-docker-.env-vs.-stack.env#key-features) Key Features * **Variable Substitution:** The `.env` file supports variable substitution, allowing you to define placeholders in your `docker-compose.yml`file. **Example:** Copy image: nginx:${VERSION} Here, `${VERSION}` is replaced with the value defined in the `.env` file. * **Dynamic Configuration:** You can easily update port numbers, image versions, and other configuration settings by modifying the `.env` file without changing the main Compose file. #### [](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/environment-variable-management-in-docker-.env-vs.-stack.env#use-cases) Use Cases * **Local Development:** Simplifies the configuration process by decoupling variable values from the compose file. * **Standalone Deployments:** Docker Compose automatically detects and loads the `.env` file when running commands like `docker-compose up`. * * * ### [](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/environment-variable-management-in-docker-.env-vs.-stack.env#docker-swarm-and-the-stack.env-file) **Docker Swarm and the** `**stack.env**` **File** #### [](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/environment-variable-management-in-docker-.env-vs.-stack.env#key-features-1) Key Features * **Limited to Environment Variables:** The `stack.env` file is only used to set environment variables under the `environment` field in your stack configuration. It does **not** support variable substitution for other settings such as port numbers or image versions. * **No Variable Substitution:** Unlike the `.env` file, the `stack.env` file cannot dynamically replace placeholders in the configuration file. **Implication:** Values like image versions and port numbers must be hard-coded, set as defaults, or managed by an external process. #### [](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/environment-variable-management-in-docker-.env-vs.-stack.env#use-cases-1) Use Cases * **Production Deployments:** Ideal for multi-host environments managed by Docker Swarm, where consistency across nodes is critical. * **Limited Dynamic Updates:** For configurations that require updating after the initial deployment, you need alternative methods such as the Portainer UI or webhooks. * * * ### [](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/environment-variable-management-in-docker-.env-vs.-stack.env#updating-environment-variables-in-docker-swarm) **Updating Environment Variables in Docker Swarm** Since `stack.env` does not support variable substitution, you can use webhooks or the Portainer UI for dynamic updates: #### [](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/environment-variable-management-in-docker-.env-vs.-stack.env#using-webhooks) Using Webhooks 1. **Initial Deployment:** Set a default value in your `docker-compose.yml` or via the Portainer UI for the first deployment. 2. **Updating Values:** Use a webhook call to update the environment variable later. **Example Webhook URL:** Copy https://localhost:9471/api/stacks/webhooks/1fefe43c-9373-46bf-8cfa-3bf687a294c0?FRESHRSS_TAG=latest This URL updates the `FRESHRSS_TAG` variable to `latest`. Integrate this process into your CI/CD pipelines for seamless updates. * * * ### [](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/environment-variable-management-in-docker-.env-vs.-stack.env#additional-resources) **Additional Resources** * [**Portainer Webhook Documentation**](https://docs.portainer.io/sts/user/docker/stacks/webhooks) : For more detailed instructions on using webhooks with Docker Swarm, refer to the official documentation. * * * ### [](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/environment-variable-management-in-docker-.env-vs.-stack.env#summary) **Summary** * `**.env**` **in Docker Compose:** Supports variable substitution, ideal for dynamic configurations in local or standalone environments. * `**stack.env**` **in Docker Swarm:** Limited to setting environment variables without substitution; use defaults or external tools (like Portainer webhooks) for updates. * **Dynamic Updates:** In Docker Swarm, update configuration values through the Portainer UI or webhooks when direct substitution is not available. By choosing the appropriate method based on your deployment environment, you can effectively manage configuration changes and maintain consistency across your Docker applications. [PreviousWhy are stack deployment times slow?](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/why-are-stack-deployment-times-slow) [NextHow do I recover orphaned stacks from a previously deleted environment?](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/how-do-i-recover-orphaned-stacks-from-a-previously-deleted-environment) Was this helpful? --- # How do I recover orphaned stacks from a previously deleted environment? | 2.35 STS | Portainer Documentation Stacks from an environment that has been deleted will be labelled as orphaned stacks. When a new environment has been created within the same node, the orphaned stacks can be re-associated by following the below steps.​ 1. Within the environment that you want to associate your orphaned stacks with, click **Stacks** in the left hand menu. At the Stacks list, click on the three dots in the top right corner and select **Show all orphaned stacks**. Your stack list will then update to include any orphaned stacks. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F8Qd5h75V7GDpf3C0WQY1%2Fimage.png&width=768&dpr=4&quality=100&sign=8bb63cd1&sv=2) 1. Click into the stack that you want to recover, and select **Associate.** ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FgEEd47Ck0VLCFqY294z2%2Fimage.png&width=768&dpr=4&quality=100&sign=6f0c8d69&sv=2) Your stack will now appear in your stack list with total control. Repeat this process for each stack you want to reassociate. [PreviousEnvironment Variable Management in Docker: .env vs. stack.env](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/environment-variable-management-in-docker-.env-vs.-stack.env) [NextUI and features](https://docs.portainer.io/sts/faqs/troubleshooting/ui-and-features) Was this helpful? --- # UI and features | 2.35 STS | Portainer Documentation [Why can't I use the console with my container?](https://docs.portainer.io/sts/faqs/troubleshooting/ui-and-features/why-cant-i-use-the-console-with-my-container) [Exposed ports in the container view redirect me to 0.0.0.0. What can I do?](https://docs.portainer.io/sts/faqs/troubleshooting/ui-and-features/exposed-ports-in-the-container-view-redirect-me-to-0.0.0.0.-what-can-i-do) [Why is a feature only available in Portainer Business Edition?](https://docs.portainer.io/sts/faqs/troubleshooting/ui-and-features/why-is-a-feature-only-available-in-portainer-business-edition) [Runtime and Resource sliders are not showing the set value on ARM](https://docs.portainer.io/sts/faqs/troubleshooting/ui-and-features/runtime-and-resource-sliders-are-not-showing-the-set-value-on-arm) [Why doesn’t the Portainer UI load inside an iframe?](https://docs.portainer.io/sts/faqs/troubleshooting/ui-and-features/why-doesnt-the-portainer-ui-load-inside-an-iframe) [PreviousHow do I recover orphaned stacks from a previously deleted environment?](https://docs.portainer.io/sts/faqs/troubleshooting/stacks-deployments-and-updates/how-do-i-recover-orphaned-stacks-from-a-previously-deleted-environment) [NextWhy can't I use the console with my container?](https://docs.portainer.io/sts/faqs/troubleshooting/ui-and-features/why-cant-i-use-the-console-with-my-container) Was this helpful? --- # Why can't I use the console with my container? | 2.35 STS | Portainer Documentation To use Portainer's Console feature, your container must first contain a shell. You can select the shell that your container uses from the dropdown. If your container image does not come with a shell included (for example, images built from Docker's scratch image) then you will not be able to use the console feature. If your container image does support a shell but the console does not work, you may receive an error message indicating that the interactive-flag and TTY-flag are not set. You can set these options on your container by editing the running container and selecting the **Interactive & TTY** option in the **Advanced container settings** section. [PreviousUI and features](https://docs.portainer.io/sts/faqs/troubleshooting/ui-and-features) [NextExposed ports in the container view redirect me to 0.0.0.0. What can I do?](https://docs.portainer.io/sts/faqs/troubleshooting/ui-and-features/exposed-ports-in-the-container-view-redirect-me-to-0.0.0.0.-what-can-i-do) Was this helpful? --- # Exposed ports in the container view redirect me to 0.0.0.0. What can I do? | 2.35 STS | Portainer Documentation **Via the Portainer UI:** 1. From the menu select **Environments**. 2. Select the environment. 3. In the **Public IP** field, enter the host IP. 4. Click **Update environment**. [PreviousWhy can't I use the console with my container?](https://docs.portainer.io/sts/faqs/troubleshooting/ui-and-features/why-cant-i-use-the-console-with-my-container) [NextWhy is a feature only available in Portainer Business Edition?](https://docs.portainer.io/sts/faqs/troubleshooting/ui-and-features/why-is-a-feature-only-available-in-portainer-business-edition) Was this helpful? --- # Why is a feature only available in Portainer Business Edition? | 2.35 STS | Portainer Documentation Portainer Community Edition requires substantial development efforts to keep it updated, and relevant in a hyper-dynamic market. The cost for this development needs to be funded one way or another, and we have elected to fund this through having a small number of our users paying for a version with premium features. Of course we need these features to be appealing, and that’s why some features that CE users might want are only in BE. [PreviousExposed ports in the container view redirect me to 0.0.0.0. What can I do?](https://docs.portainer.io/sts/faqs/troubleshooting/ui-and-features/exposed-ports-in-the-container-view-redirect-me-to-0.0.0.0.-what-can-i-do) [NextRuntime and Resource sliders are not showing the set value on ARM](https://docs.portainer.io/sts/faqs/troubleshooting/ui-and-features/runtime-and-resource-sliders-are-not-showing-the-set-value-on-arm) Was this helpful? --- # Runtime and Resource sliders are not showing the set value on ARM | 2.35 STS | Portainer Documentation #### [](https://docs.portainer.io/sts/faqs/troubleshooting/ui-and-features/runtime-and-resource-sliders-are-not-showing-the-set-value-on-arm#issue-description) Issue Description When you try to "Duplicate/Edit" a container, the tab Runtime & Resources shows the already selected value for CPU limit slider, but Memory reservation and Memory limit sliders are always reset to zero. #### [](https://docs.portainer.io/sts/faqs/troubleshooting/ui-and-features/runtime-and-resource-sliders-are-not-showing-the-set-value-on-arm#cause) Cause Docker on ARM platforms does not provide support for memory reservations or limits, so as a result this is reset to zero. This functionality works as expected on x64 platforms. [PreviousWhy is a feature only available in Portainer Business Edition?](https://docs.portainer.io/sts/faqs/troubleshooting/ui-and-features/why-is-a-feature-only-available-in-portainer-business-edition) [NextWhy doesn’t the Portainer UI load inside an iframe?](https://docs.portainer.io/sts/faqs/troubleshooting/ui-and-features/why-doesnt-the-portainer-ui-load-inside-an-iframe) Was this helpful? --- # Why doesn’t the Portainer UI load inside an iframe? | 2.35 STS | Portainer Documentation By default, Portainer cannot be embedded in an iframe. This is because the default **Content-Security-Policy (CSP)** header includes: Copy frame-ancestors 'none'; This blocks all iframing of Portainer. If you need to allow iframing, you can disable the CSP header entirely by setting the [`--no-csp` flag](https://docs.portainer.io/sts/advanced/cli#configuration-flags-available-at-the-command-line) when running Portainer. This removes **all** of the Content-Security-Policy header, so please use it with caution and at your own risk, and only if you **need** the iframing to work for you. [PreviousRuntime and Resource sliders are not showing the set value on ARM](https://docs.portainer.io/sts/faqs/troubleshooting/ui-and-features/runtime-and-resource-sliders-are-not-showing-the-set-value-on-arm) [NextLogs, errors and debugging](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging) Was this helpful? --- # Logs, errors and debugging | 2.35 STS | Portainer Documentation [Unable to Access Pod Logs in My k0s Cluster](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/unable-to-access-pod-logs-in-my-k0s-cluster) [Can you view deleted container logs in Portainer?](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/can-you-view-deleted-container-logs-in-portainer) [How can I get the logs for Portainer itself?](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/how-can-i-get-the-logs-for-portainer-itself) [Why can't my users see anything in the environment they have access to?](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/why-cant-my-users-see-anything-in-the-environment-they-have-access-to) [Why do I see a lot of TLS handshake errors in my Portainer and/or Agent logs?](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/why-do-i-see-a-lot-of-tls-handshake-errors-in-my-portainer-and-or-agent-logs) ["Failed to get license info" or "Unable to retrieve license info" message with valid license](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/failed-to-get-license-info-or-unable-to-retrieve-license-info-message-with-valid-license) [What does a 500 error code mean?](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/what-does-a-500-error-code-mean) [Why is my console closing after a certain time?](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/why-is-my-console-closing-after-a-certain-time) [“Failed logging user activity” error in Portainer](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/failed-logging-user-activity-error-in-portainer) [PreviousWhy doesn’t the Portainer UI load inside an iframe?](https://docs.portainer.io/sts/faqs/troubleshooting/ui-and-features/why-doesnt-the-portainer-ui-load-inside-an-iframe) [NextUnable to Access Pod Logs in My k0s Cluster](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/unable-to-access-pod-logs-in-my-k0s-cluster) Was this helpful? --- # Can you view deleted container logs in Portainer? | 2.35 STS | Portainer Documentation No. Portainer does not keep a history of deleted containers or their logs. [PreviousUnable to Access Pod Logs in My k0s Cluster](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/unable-to-access-pod-logs-in-my-k0s-cluster) [NextHow can I get the logs for Portainer itself?](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/how-can-i-get-the-logs-for-portainer-itself) Was this helpful? --- # How can I get the logs for Portainer itself? | 2.35 STS | Portainer Documentation Portainer runs as a container, so you can view the Portainer logs in the same way you would do for any other container. You can view the logs [through the Portainer UI](https://docs.portainer.io/sts/user/docker/containers/logs) , or alternatively if you have access to the host you can use the Docker CLI: Log into the command line of a Docker manager node (for Swarm) or the Docker host (for Standalone) and run the following command: Copy docker ps -a This will list the containers on your environment, and will look something like this: Copy CONTAINER ID IMAGE COMMAND REATED STATUS PORTS                                                                           NAMES 2c9085c1d664 portainer/portainer-ee:latest "/portainer" 3 days ago Up 3 days 0.0.0.0:8000->8000/tcp, :::8000->8000/tcp, 0.0.0.0:9443->9443/tcp, :::9443->9443/tcp, 9000/tcp portainer be84ee30270e mysql:8.0 "docker-entrypoint.s… " 4 days ago Exited (1) 4 days ago mysql 4604a2f5108e nginx:latest "/docker-entrypoint.…" 4 days ago Up 4 days 0.0.0.0:80->80/tcp, :::80->80/tcp                                                            nginx Note the CONTAINER\_ID of the Portainer container. Next, run the following command to output the logs for the container, using the CONTAINER\_ID from the previous command (in the above example, 2c9085c1d664): Copy docker container logs 2c9085c1d664 The logs from the container will be displayed. [PreviousCan you view deleted container logs in Portainer?](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/can-you-view-deleted-container-logs-in-portainer) [NextWhy can't my users see anything in the environment they have access to?](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/why-cant-my-users-see-anything-in-the-environment-they-have-access-to) Was this helpful? --- # Unable to Access Pod Logs in My k0s Cluster | 2.35 STS | Portainer Documentation You have set up a multi-control-plane node Kubernetes cluster using k0s and have successfully deployed the Portainer agent to the cluster. Portainer can connect to the Kubernetes cluster; however, you may encounter errors when accessing logs—sometimes intermittently. You might see an error message toast similar to the following when attempting to view the logs. `Unable to get pod logs: Get “https://:10250/… : No agent available` ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FF4y01IW5boNz2bO5cznY%2Fimage.png&width=768&dpr=4&quality=100&sign=25bd478d&sv=2) Based on our testing, the likely cause of this issue is the absence of node-local load balancing in a k0s-based Kubernetes cluster with multiple control-plane nodes. For more details, refer to the [Configuration file reference](https://docs.k0sproject.io/stable/k0sctl-install/) in the Mirantis, Inc. Configuration Options documentation. If you manage the cluster configuration manually by modifying the k0s.yaml file on the nodes, update the configuration accordingly and restart the services.​ If you use k0sctl to manage the cluster configuration, simply add the _**nodeLocalLoadBalancing**_ section to your k0sctl.yaml ClusterConfig object. Ensure the correct indentation is maintained. Additional configuration options for node-local load balancing are available in their documentation. Copy apiVersion: k0sctl.k0sproject.io/v1beta1 kind: Cluster metadata:   name: k0s-cluster spec:   k0s:     version: 1.30.3+k0s.0     config:       apiVersion: k0s.k0sproject.io/v1beta1       kind: ClusterConfig       metadata:         name: k0s-cluster       spec:         network:           podCIDR: 10.244.0.0/16           provider: calico           serviceCIDR: 10.96.0.0/12           nodeLocalLoadBalancing:             enabled: true             type: EnvoyProxy   hosts:     - role: controller Note that **k0sctl** is the recommended tool for bootstrapping and managing multi-node environments with high-availability requirements. [PreviousLogs, errors and debugging](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging) [NextCan you view deleted container logs in Portainer?](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/can-you-view-deleted-container-logs-in-portainer) Was this helpful? --- # Why do I see a lot of TLS handshake errors in my Portainer and/or Agent logs? | 2.35 STS | Portainer Documentation This can occur when either the Portainer Server or your Portainer Agents are exposed to the public internet, and are being subjected to port scanners. We highly recommend restricting access to your Portainer deployments to only the IPs that are required for access by using a firewall or other ACL mechanism to limit access. [PreviousWhy can't my users see anything in the environment they have access to?](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/why-cant-my-users-see-anything-in-the-environment-they-have-access-to) [Next"Failed to get license info" or "Unable to retrieve license info" message with valid license](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/failed-to-get-license-info-or-unable-to-retrieve-license-info-message-with-valid-license) Was this helpful? --- # Why can't my users see anything in the environment they have access to? | 2.35 STS | Portainer Documentation For security reasons, all resources inside an environment are assigned only to the administrator by default. To give non-admin users access, you can either: * Use the [access control tool](https://docs.portainer.io/sts/advanced/access-control) within each resource to assign ownership to users. * Make the resource public, so all users get access to it. [PreviousHow can I get the logs for Portainer itself?](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/how-can-i-get-the-logs-for-portainer-itself) [NextWhy do I see a lot of TLS handshake errors in my Portainer and/or Agent logs?](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/why-do-i-see-a-lot-of-tls-handshake-errors-in-my-portainer-and-or-agent-logs) Was this helpful? --- # "Failed to get license info" or "Unable to retrieve license info" message with valid license | 2.35 STS | Portainer Documentation In some situations, some users are receiving "Failed to get license info" or "Unable to retrieve license info" error messages when using Portainer BE, particularly during the upgrade to BE from CE but this has also been seen during regular use of the Portainer UI. To resolve this, we recommend clearing your browser's cache and local storage. **Chrome** Click on the three dots in the top right of your Chrome window and go to **Settings**, then **Privacy and Security**. Click **Clear browsing data**, change the **Time range** to **All time**, ensure **Cached images and files** is checked and click **Clear data**. You may also need to log back into Portainer after performing this step. **Firefox** Click on the three lines in the top right of your Firefox window and go to **Settings**, then **Privacy & Security**. Scroll down to the **Cookies and Site Data** section and click **Clear Data**. Ensure that both options are ticked and click **Clear**. You may also need to log back into Portainer after performing this step. **Edge** Click on the three dots in the top right of your Edge window and go to **Settings**, then **Privacy, search, and services**. Scroll down to the **Clear browsing data** section and click **Choose what to clear**. Change the **Time range** to **All time**, ensure **Cached images and files** is checked and click **Clear now**. You may also need to log back into Portainer after performing this step. [PreviousWhy do I see a lot of TLS handshake errors in my Portainer and/or Agent logs?](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/why-do-i-see-a-lot-of-tls-handshake-errors-in-my-portainer-and-or-agent-logs) [NextWhat does a 500 error code mean?](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/what-does-a-500-error-code-mean) Was this helpful? --- # What does a 500 error code mean? | 2.35 STS | Portainer Documentation When performing actions within Portainer that involve interacting with the Docker engine (for example creating or updating a container) you may run into issues where Portainer returns a 500 error message when performing the action. This can make it difficult to understand the underlying cause of the error. Improving the way that we display error messages that are passed to us from the containerization engine is something that is a high priority for us, so you can expect to see this coming in future releases. In the meantime, you can dig into the detail in many cases by first opening your web browser's developer console and then performing the action that results in the error. To open the developer tools: * **Chrome:** press **Ctrl-Shift-I** on Windows (or **Cmd-Option-I** on Mac), or click the three dot menu in the top right and go to **More tools**, then select **Developer tools**. * **Firefox:** press **Ctrl-Shift-I** on Windows (or **Cmd-Option-I** on Mac), or click the three line menu in the top right and go to **More tools**, then select **Web Developer Tools**. * **Microsoft Edge:** press **Ctrl-Shift-I** or click the three dot menu in the top right and go to **More tools**, then select **Developer tools**. * **Safari:** From the Safari menu, select **Preferences**, then **Advanced**. Check the **Show Develop menu in menu bar** option. You can then access the developer tools from the **Develop** menu in the menu bar. With the tools open, select the **Network** tab, then go back to the Portainer window (keeping the developer tools open) and perform the action. Then go back to your developer tools window and find the call in the Network tab that has reported the 500 error (it should be highlighted in red). Select it, then select the **Response** tab. This should hopefully show you the error returned from the engine. [Previous"Failed to get license info" or "Unable to retrieve license info" message with valid license](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/failed-to-get-license-info-or-unable-to-retrieve-license-info-message-with-valid-license) [NextWhy is my console closing after a certain time?](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/why-is-my-console-closing-after-a-certain-time) Was this helpful? --- # Why is my console closing after a certain time? | 2.35 STS | Portainer Documentation ### [](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/why-is-my-console-closing-after-a-certain-time#hs_cos_wrapper_kb-article-module-4) Is your container console or Kube-shell in Portainer closing on its own and you have published Portainer via reverse proxy? This could be related to a time out setting in your reverse proxy and can be changed. Below are some examples of how this can be done for nginx based proxies. In below examples, change the value `3600` to match your requirement. **Nginx Server**: add the following to the `nginx.conf` file. Copy proxy_read_timeout 3600; **Nginx Proxy Manager:** Edit the proxy host that you need to change and add `proxy_read_timeout 3600;` as below. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FkhFfWjqniwPMVijzMFKw%2Fimage.png&width=768&dpr=4&quality=100&sign=9fec30bd&sv=2) **Nginx Ingress Controller (Kubernetes)** You need to add the following annotation to the Ingress object `nginx.ingress.kubernetes.io/proxy-read-timeout: 3600` [PreviousWhat does a 500 error code mean?](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/what-does-a-500-error-code-mean) [Next“Failed logging user activity” error in Portainer](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/failed-logging-user-activity-error-in-portainer) Was this helpful? --- # “Failed logging user activity” error in Portainer | 2.35 STS | Portainer Documentation #### [](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/failed-logging-user-activity-error-in-portainer#issue) **Issue** You may encounter the following error in Portainer: > **“Failed logging user activity”** #### [](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/failed-logging-user-activity-error-in-portainer#cause) **Cause** This error typically occurs when the useractivity.db file is missing or inaccessible within the Portainer Server’s volume. This can impact: * Viewing **activity logs** within Portainer * **Creating backups**, as logging is part of the process #### [](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/failed-logging-user-activity-error-in-portainer#solution) **Solution** To resolve this issue: 1. **Restart the Portainer Server container** Restarting the container will regenerate the useractivity.db file if it is missing and restore normal logging functionality. #### [](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/failed-logging-user-activity-error-in-portainer#steps-to-restart-docker-example) **Steps to Restart (Docker Example)** Copy docker restart portainer If this happens frequently, consider checking your volume mappings and file system permissions to ensure Portainer can consistently access and write to its data volume. [PreviousWhy is my console closing after a certain time?](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/why-is-my-console-closing-after-a-certain-time) [NextCertificates and security](https://docs.portainer.io/sts/faqs/troubleshooting/certificates-and-security) Was this helpful? --- # Certificates and security | 2.35 STS | Portainer Documentation [How to enable/disable image Up-to-date indicator](https://docs.portainer.io/sts/faqs/troubleshooting/certificates-and-security/how-to-enable-disable-image-up-to-date-indicator) [How can I use my custom certificate authority (CA) with Portainer?](https://docs.portainer.io/sts/faqs/troubleshooting/certificates-and-security/how-can-i-use-my-custom-certificate-authority-ca-with-portainer) [Previous“Failed logging user activity” error in Portainer](https://docs.portainer.io/sts/faqs/troubleshooting/logs-errors-and-debugging/failed-logging-user-activity-error-in-portainer) [NextHow to enable/disable image Up-to-date indicator](https://docs.portainer.io/sts/faqs/troubleshooting/certificates-and-security/how-to-enable-disable-image-up-to-date-indicator) Was this helpful? --- # How to enable/disable image Up-to-date indicator | 2.35 STS | Portainer Documentation In Portainer, you can see if an image is out of date when you have the image up-to-date indicator enabled. This will guide you through enabling or disabling this feature for Docker Standalone and Docker Swarm. #### [](https://docs.portainer.io/sts/faqs/troubleshooting/certificates-and-security/how-to-enable-disable-image-up-to-date-indicator#enabling-or-disabling-the-image-up-to-date-indicator) **Enabling or Disabling the Image Up-to-date Indicator** To enable the image up-to-date indicator, follow these steps: Select your environment: Docker Standalone or Docker Swarm. [PreviousCertificates and security](https://docs.portainer.io/sts/faqs/troubleshooting/certificates-and-security) [NextHow can I use my custom certificate authority (CA) with Portainer?](https://docs.portainer.io/sts/faqs/troubleshooting/certificates-and-security/how-can-i-use-my-custom-certificate-authority-ca-with-portainer) Was this helpful? --- # How can I use my custom certificate authority (CA) with Portainer? | 2.35 STS | Portainer Documentation If you need to reference external resources (for example, a custom template URL) that use certificates signed by a custom certificate authority (CA), you may run into issues with Portainer out of the box. To resolve this you will need to inject your CA certificate into the Portainer containers (both the Portainer Server and any Portainer Agent containers) by first adding it to the CA store on your hosts then mounting that CA store into the Portainer containers. #### [](https://docs.portainer.io/sts/faqs/troubleshooting/certificates-and-security/how-can-i-use-my-custom-certificate-authority-ca-with-portainer#adding-your-ca-to-the-local-store) Adding your CA to the local store The procedure for this may differ depending on the underlying OS of your host. For most Linux distributions you can use the `ca-certificates` package to manage your local CA store. In Ubuntu for example, you can follow [this guide](https://ubuntu.com/server/docs/install-a-root-ca-certificate-in-the-trust-store) . Remember you will need to do this on all hosts that run either Portainer or the Portainer Agent. #### [](https://docs.portainer.io/sts/faqs/troubleshooting/certificates-and-security/how-can-i-use-my-custom-certificate-authority-ca-with-portainer#mounting-your-ca-store-in-portainer) Mounting your CA store in Portainer Once you have your CA added to your local store, you can then mount that store within the Portainer containers. This is done by modifying the command you use to create the Portainer containers, and will depend on your containerization platform. **Docker Standalone** If you have started Portainer with the `docker run` command, you can add a bind mount to the command to add the CA store: Copy -v /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt For example, here is a full `docker run` command including the CA store mount: Copy docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data -v /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt portainer/portainer-ee:2.21.0 If your local CA store is in a different location, adjust the reference on the left side of the colon (and _only_ the left side) in the above example to suit. The Portainer containers expect the CA store to exist at `/etc/ssl/certs/ca-certificates.crt` so that _must_ be the path specified on the right side of the colon. For the Portainer Agent the same process applies but with the docker run command used for the Agent. **Docker Swarm** When deploying to Docker Swarm you generally will use a YAML file with `docker stack deploy`. To add the local CA store mount you will need to edit that YAML file to include the mount. Remember to do this for both the Portainer Server and the Portainer Agent service definitions. For example: Copy services: agent: image: portainer/agent:2.21.0 volumes: - /var/run/docker.sock:/var/run/docker.sock - /var/lib/docker/volumes:/var/lib/docker/volumes      - /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt ...   portainer:     image: portainer/portainer-ee:2.21.0     command: -H tcp://tasks.agent:9001 --tlsskipverify     ports:       - "9443:9443"       - "9000:9000"       - "8000:8000"     volumes:       - portainer_data:/data - /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt If your local CA store is in a different location, adjust the reference on the left side of the colon (and _only_ the left side) in the above examples to suit. The Portainer containers expect the CA store to exist at /etc/ssl/certs/ca-certificates.crt so that _must_ be the path specified on the right side of the colon. [PreviousHow to enable/disable image Up-to-date indicator](https://docs.portainer.io/sts/faqs/troubleshooting/certificates-and-security/how-to-enable-disable-image-up-to-date-indicator) [NextRegistry and image management](https://docs.portainer.io/sts/faqs/troubleshooting/registry-and-image-management) Was this helpful? --- # Registry and image management | 2.35 STS | Portainer Documentation [Why is my node count higher than it should be?](https://docs.portainer.io/sts/faqs/troubleshooting/registry-and-image-management/why-is-my-node-count-higher-than-it-should-be) [I am unable to push an image to an AWS Elastic Container Registry](https://docs.portainer.io/sts/faqs/troubleshooting/registry-and-image-management/i-am-unable-to-push-an-image-to-an-aws-elastic-container-registry) [PreviousHow can I use my custom certificate authority (CA) with Portainer?](https://docs.portainer.io/sts/faqs/troubleshooting/certificates-and-security/how-can-i-use-my-custom-certificate-authority-ca-with-portainer) [NextWhy is my node count higher than it should be?](https://docs.portainer.io/sts/faqs/troubleshooting/registry-and-image-management/why-is-my-node-count-higher-than-it-should-be) Was this helpful? --- # Why is my node count higher than it should be? | 2.35 STS | Portainer Documentation Portainer is licensed on a per-node basis. A node is any container runtime managed by Portainer. For example: * A Docker standalone instance would be one Portainer environment and count as one node as it would manage one container runtime. It would require **1** license. * A Docker Swarm cluster would be one Portainer environment and count as the same number of nodes as are in the Docker Swarm cluster as it would manage that number of container runtimes. It would require a license for each of those nodes. * A Kubernetes cluster, like a Docker Swarm cluster, would be one Portainer environment and count as the same number of nodes as are in the Kubernetes cluster as it would manage that number of container runtimes. It would require a license for each of those nodes. * * * Even knowing this, it is possible to create situations where your node count, and therefore license count, is higher than your number of nodes. This is usually the result of adding individual worker nodes in a cluster as additional environments in Portainer. For example, if Portainer is managing a swarm consisting of one manager and three workers, **4** licenses are used. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2Fp1LdabJeVJVquYr2lkmu%2Fimage.png&width=768&dpr=4&quality=100&sign=b17b700&sv=2) ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FgRyTND0HNFQlDZaIgZnP%2Fimage.png&width=768&dpr=4&quality=100&sign=9a48b997&sv=2) This Portainer environment consists of the manager and all three worker nodes. There is no need to add anything else to Portainer in order to manager this entire cluster. The Portainer Agent is deployed to come up on every worker node, so when new workers come online, an instance of the Agent will be scheduled on them automatically and an additional license will be used. If you mistakenly add one of the workers as a **new** environment in Portainer, Portainer will gladly talk to it, see that it is a cluster consisting of four nodes, and apply licensing accordingly. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F9LYNmKE5OM4mdeZMhKeJ%2Fimage.png&width=768&dpr=4&quality=100&sign=fc0027fe&sv=2) ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FJfD5vhee8khCq0GOwVTa%2Fimage.png&width=768&dpr=4&quality=100&sign=80020171&sv=2) As you can see, now that the worker has been added as another cluster, Portainer counts the nodes in the cluster and applies a license for each of them. This uses **8** licenses where only **4** licenses were needed. If this approach were to continue for all of the workers, **16** license would be used for a four node cluster. If you find yourself in this situation, you can simply remove the extraneously added environments by clicking **Environments** in the navigation menu, then selecting the environment to be removed, and clicking the **Remove** button. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F9E9qDv26WXAwd1ndR1TP%2Fremove-environment-png.png&width=768&dpr=4&quality=100&sign=fc43c29b&sv=2) This will not affect the workloads running on the worker or the cluster. It will simply remove it from being seen by Portainer as a unique environment and adjust your licensing count appropriately. [PreviousRegistry and image management](https://docs.portainer.io/sts/faqs/troubleshooting/registry-and-image-management) [NextI am unable to push an image to an AWS Elastic Container Registry](https://docs.portainer.io/sts/faqs/troubleshooting/registry-and-image-management/i-am-unable-to-push-an-image-to-an-aws-elastic-container-registry) Was this helpful? --- # Contributing | 2.35 STS | Portainer Documentation * [How do I report a bug?](https://docs.portainer.io/sts/faqs/contributing/how-do-i-report-a-bug) * [How do I raise a feature request?](https://docs.portainer.io/sts/faqs/contributing/how-do-i-raise-a-feature-request) * [How do you decide which bugs and features to work on first?](https://docs.portainer.io/sts/faqs/contributing/how-do-you-decide-which-bugs-and-features-to-work-on-first) * [How do I log a Support Request?](https://docs.portainer.io/sts/faqs/contributing/how-do-i-log-a-support-request) [PreviousI am unable to push an image to an AWS Elastic Container Registry](https://docs.portainer.io/sts/faqs/troubleshooting/registry-and-image-management/i-am-unable-to-push-an-image-to-an-aws-elastic-container-registry) [NextHow do I report a bug?](https://docs.portainer.io/sts/faqs/contributing/how-do-i-report-a-bug) Was this helpful? --- # I am unable to push an image to an AWS Elastic Container Registry | 2.35 STS | Portainer Documentation AWS Elastic Container Registry [requires users to pre-create all repositories](https://www.portainer.io/blog/using-portainer-with-aws-elastic-container-registry?hsLang=en) before they can be pushed to. If the AWS Elastic Container Registry does not have a repository created, the user will receive the following error message while attempting to push an image in Portainer: ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FclkTQbrZXnPK65RM6wTX%2Fimage.png&width=768&dpr=4&quality=100&sign=c8dd3aa&sv=2) [PreviousWhy is my node count higher than it should be?](https://docs.portainer.io/sts/faqs/troubleshooting/registry-and-image-management/why-is-my-node-count-higher-than-it-should-be) [NextContributing](https://docs.portainer.io/sts/faqs/contributing) Was this helpful? --- # How do I report a bug? | 2.35 STS | Portainer Documentation If you find a bug, please tell us so we can triage it. All bugs are managed in this [GitHub](https://github.com/portainer/portainer/issues/new?assignees=&labels=bug%2Fneed-confirmation%2C+kind%2Fbug&template=Bug_report.md&title=) repo. When you click through, our template makes it easy to record all of the details. Before you report a bug, please check our list of [open bugs](https://github.com/portainer/portainer/labels/kind%2Fbug) in case someone else has already reported it. Go [here](https://docs.portainer.io/sts/faqs/contributing/how-do-you-decide-which-bugs-and-features-to-work-on-first) to learn how we prioritize bug fixes. [PreviousContributing](https://docs.portainer.io/sts/faqs/contributing) [NextHow do I raise a feature request?](https://docs.portainer.io/sts/faqs/contributing/how-do-i-raise-a-feature-request) Was this helpful? --- # How do I raise a feature request? | 2.35 STS | Portainer Documentation You can request new features in this [GitHub](https://github.com/portainer/portainer/issues/new?assignees=&labels=&template=Feature_request.md&title=) repo. When you click through, our template makes it easy to record all of the details. We also publish a list of [open](https://github.com/portainer/portainer/issues?q=is%3Aissue+is%3Aopen+label%3Abug%2Fconfirmed) feature requests in GitHub. Check to see if someone has already requested the feature you want, and give it a thumbs up. Learn how we prioritize feature development [here](https://docs.portainer.io/sts/faqs/contributing/how-do-you-decide-which-bugs-and-features-to-work-on-first) . [PreviousHow do I report a bug?](https://docs.portainer.io/sts/faqs/contributing/how-do-i-report-a-bug) [NextHow do you decide which bugs and features to work on first?](https://docs.portainer.io/sts/faqs/contributing/how-do-you-decide-which-bugs-and-features-to-work-on-first) Was this helpful? --- # How do you decide which bugs and features to work on first? | 2.35 STS | Portainer Documentation Here at Portainer, we encourage feedback from our customers, and we truly value our user community. That being said, our [features](https://github.com/orgs/portainer/discussions/categories/ideas) and [bugs](https://github.com/portainer/portainer/issues) lists are long and at times seem never ending. Our decision-making process aims to balance user needs with the reality of Portainer's limited time and resources. Despite our best intentions, we know that at times we will disappoint some of you. **Our process** When prioritizing which feature requests to work on, if we answer "yes" to any of the following questions, we will be more likely to add that feature: * Will it address a security vulnerability or potential exploitation? * Will it have a wide appeal? * Will it benefit professional Portainer users? * Does the request have at least 20 upvotes in GitHub? **Feature parity** We don't automatically maintain feature parity with Docker or Kubernetes. When a new feature comes out, we ask the same four questions before deciding whether or not to add it to Portainer. And we only add support for features that we feel are stable and are in high demand. **The importance of voting** We receive many feature requests for issues that exist only because of a specific use case. These stay pending until we identify an opportunity, or our community indicates its demand by voting (using the upvote functionality of GitHub discussions). [PreviousHow do I raise a feature request?](https://docs.portainer.io/sts/faqs/contributing/how-do-i-raise-a-feature-request) [NextHow do I log a Support Request?](https://docs.portainer.io/sts/faqs/contributing/how-do-i-log-a-support-request) Was this helpful? --- # How do I log a Support Request? | 2.35 STS | Portainer Documentation Only Portainer Business (BE) customers with a Professional or Enterprise subscription can log tickets directly with Portainer. For all other users, we recommend our [community support resources](https://www.portainer.io/get-support-for-portainer?hsLang=en) . **How to log a support request:** * Go to the [Get Support](https://www.portainer.io/get-support-for-portainer?hsLang=en) page on the Portainer website. * After reviewing the existing resources to see if your question has already been answered, scroll down to the **Get Business Edition Support** section and complete the form. * Tickets are checked and resolved by Portainer staff within the SLA. * If we think it's easier to speak to you about a ticket directly, we'll reach out to organize a meeting via Zoom (or similar platform). [PreviousHow do you decide which bugs and features to work on first?](https://docs.portainer.io/sts/faqs/contributing/how-do-you-decide-which-bugs-and-features-to-work-on-first) [NextKnown issues](https://docs.portainer.io/sts/faqs/known-issues) Was this helpful? --- # Email Protection | Cloudflare Please enable cookies. Email Protection ================ You are unable to access this email address docs.portainer.io ------------------------------------------------------------- The website from which you got to this page is protected by Cloudflare. Email addresses on that page have been hidden in order to keep them from being accessed by malicious bots. **You must enable Javascript in your browser in order to decode the e-mail address**. If you have a website and are interested in protecting it in a similar way, you can [sign up for Cloudflare](https://www.cloudflare.com/sign-up?utm_source=email_protection) . * [How does Cloudflare protect email addresses on website from spammers?](https://developers.cloudflare.com/waf/tools/scrape-shield/email-address-obfuscation/) * [Can I sign up for Cloudflare?](https://developers.cloudflare.com/fundamentals/setup/account/create-account/) Cloudflare Ray ID: **99f160a1095ae63f** • Your IP: Click to reveal 54.237.218.47 • Performance & security by [Cloudflare](https://www.cloudflare.com/5xx-error-landing) --- # Known issues | 2.35 STS | Portainer Documentation * [Edge stacks do not support authenticating against a private registry to deploy applications stored on private registries](https://docs.portainer.io/sts/faqs/known-issues/edge-stacks-do-not-support-authenticating-to-deploy-applications-from-private-registries.) * [Known issues with VMware](https://docs.portainer.io/sts/faqs/known-issues/known-issues-with-vmware) * [Groups info issue with OAuth using Microsoft AD](https://docs.portainer.io/sts/faqs/known-issues/groups-info-issue-with-oauth-using-microsoft-ad) * [Resource limits in a compose file are not applying](https://docs.portainer.io/sts/faqs/known-issues/resource-limits-in-a-compose-file-are-not-applying) * [Hardware Acceleration GPU button is missing](https://docs.portainer.io/sts/faqs/known-issues/hardware-acceleration-gpu-button-is-missing) * [Unable to update environment variables when running on Synology NAS](https://docs.portainer.io/sts/faqs/known-issues/unable-to-update-environment-variables-when-running-on-synology-nas) * [Unable to remove the Group Configuration from Active Directory authentication configuration](https://docs.portainer.io/sts/faqs/known-issues/unable-to-remove-the-group-configuration-from-active-directory-authentication-configuration) * [Nomad Jobs only displays Service Jobs](https://docs.portainer.io/sts/faqs/known-issues/nomad-jobs-only-displays-service-jobs) * ["Image not found on registry" error when upgrading from CE to BE, or using the self-update feature running on a Synology NAS](https://docs.portainer.io/sts/faqs/known-issues/image-not-found-on-registry-error-when-upgrading-from-ce-to-be-or-self-updating-on-synology-nas) * [MicroK8s Known Issues](https://docs.portainer.io/sts/faqs/known-issues/microk8s-known-issues) * ["Unauthorized" error when pushing images to ACR with Service Principal account](https://docs.portainer.io/sts/faqs/known-issues/unauthorized-error-when-pushing-images-to-acr-with-service-principal-account) * ["Invalid certificate file" error when browsing empty Azure Container Registry](https://docs.portainer.io/sts/faqs/known-issues/invalid-certificate-file-error-when-browsing-empty-azure-container-registry) [PreviousHow do I log a Support Request?](https://docs.portainer.io/sts/faqs/contributing/how-do-i-log-a-support-request) [NextEdge stacks do not support authenticating to deploy applications from private registries.](https://docs.portainer.io/sts/faqs/known-issues/edge-stacks-do-not-support-authenticating-to-deploy-applications-from-private-registries.) Was this helpful? --- # Edge stacks do not support authenticating to deploy applications from private registries. | 2.35 STS | Portainer Documentation **Affected versions:** 2.14.2 and previous **Fixed in:** 2.15.0 and above #### [](https://docs.portainer.io/sts/faqs/known-issues/edge-stacks-do-not-support-authenticating-to-deploy-applications-from-private-registries.#issue-description) Issue Description When using Edge Stacks to deploy services from a private repository, images are not able to be pulled. #### [](https://docs.portainer.io/sts/faqs/known-issues/edge-stacks-do-not-support-authenticating-to-deploy-applications-from-private-registries.#fix) Fix Update Portainer to 2.15.0 or above. #### [](https://docs.portainer.io/sts/faqs/known-issues/edge-stacks-do-not-support-authenticating-to-deploy-applications-from-private-registries.#workaround) Workaround Deploy a [Docker registry container](https://hub.docker.com/_/registry) , put it in ["cache" mode](https://docs.docker.com/registry/recipes/mirror/) , and configure it to authenticate using your Docker Hub credentials. Locally to the edge device, it pulls from the cache locally as anonymous, but the cache knows how to retrieve from a secure repository. This workaround only applies for Docker Hub, and does not work for other registries such as AWS ECR. [PreviousKnown issues](https://docs.portainer.io/sts/faqs/known-issues) [NextKnown issues with VMware](https://docs.portainer.io/sts/faqs/known-issues/known-issues-with-vmware) Was this helpful? --- # Known issues with VMware | 2.35 STS | Portainer Documentation **Affected versions:** All **Fixed in:** n/a When running a containerized environment on a VMware system there are a few caveats to be aware of before you start. We've outlined those we've run into below. If you do find anything else or think we should expand on what we have below, please let us know. ### [](https://docs.portainer.io/sts/faqs/known-issues/known-issues-with-vmware#docker-swarm) Docker Swarm #### [](https://docs.portainer.io/sts/faqs/known-issues/known-issues-with-vmware#overlay-networking-and-nsx) Overlay networking and NSX If you are running NSX on your VMware environment you will likely run into issues with Docker's overlay networking. In particular, overlay networking uses UDP port 4789 by default which conflicts with VMware NSX's communication port for VXLAN. To resolve this, you can change the data path port for your Docker Swarm setup to a different value (for example, 9789): Copy docker swarm init --data-path-port=9789 Alternatively you can (depending on your setup) reconfigure NSX to use a different VXLAN port. You'll find instructions on how to do this in the VMware documentation. #### [](https://docs.portainer.io/sts/faqs/known-issues/known-issues-with-vmware#vmware-and-swarm-routing) VMware and Swarm routing When running Docker Swarm under VMware you may run into issues with communication over the swarm node routing mesh. We have traced this back to UDP packets being dropped by the source node. Disabling checksum offloading appears to resolve this issue. Run the following on **all** the VMs in your cluster: Copy ethtool -K [network] tx-checksum-ip-generic off Replace \[network\] with the name of your network adapter. You will likely need to restart the services on your cluster that communicate with each other (such as the Portainer Agent) for this change to be picked up. We have seen this issue occur on RedHat-based distributions including CentOS and Photon OS, but also occasionally on Ubuntu so it is worth checking if you are experiencing issues. Note: Changes made via ethtool only apply until your server is rebooted, at which point they will be lost. If you find this change is required, we recommend adding it to your network startup scripts. #### [](https://docs.portainer.io/sts/faqs/known-issues/known-issues-with-vmware#large-packets-are-being-dropped) Large packets are being dropped In certain configurations, packets being sent on overlay networks can be silently dropped, in particular when vmw\_conn\_notifyd is being used. There is an open issue with VMware discussing the behavior which we are following, and is worth reading for potential workarounds until this is patched. #### [](https://docs.portainer.io/sts/faqs/known-issues/known-issues-with-vmware#fault-tolerance) Fault Tolerance The "Failed Loading Environment - Unable to find an agent on any Manager Node" error can occur when the VMware "Fault Tolerance" feature is enabled on the virtual machine (VM) of the swarm manager node. This feature can disrupt communication. To resolve the communication issue, follow these steps: 1. Disable the Fault Tolerance feature for the virtual machine. 2. Restart/update the portainer\_agent service. By disabling Fault Tolerance and restarting/updating the portainer\_agent service, communication can be restored. [PreviousEdge stacks do not support authenticating to deploy applications from private registries.](https://docs.portainer.io/sts/faqs/known-issues/edge-stacks-do-not-support-authenticating-to-deploy-applications-from-private-registries.) [NextGroups info issue with OAuth using Microsoft AD](https://docs.portainer.io/sts/faqs/known-issues/groups-info-issue-with-oauth-using-microsoft-ad) Was this helpful? --- # Resource limits in a compose file are not applying | 2.35 STS | Portainer Documentation **Affected versions:** 2.14.0, 2.14.1, 2.14.2 **Fixed in:** 2.15.0 and above #### [](https://docs.portainer.io/sts/faqs/known-issues/resource-limits-in-a-compose-file-are-not-applying#issue-description) Issue Description When using a compose file to apply resource limits on a Docker Standalone environment, some values (such as cpus and cpu\_percent) are not applying: Copy version: "2" services: mynginx: container_name: mynginx image: nginx:latest cpus: 1 cpu_percent: 50 #### [](https://docs.portainer.io/sts/faqs/known-issues/resource-limits-in-a-compose-file-are-not-applying#cause) Cause This issue is [the result of a bug](https://github.com/docker/compose/issues/9268) in the version of the docker compose v2 plugin that is used in version 2.14 of Portainer. #### [](https://docs.portainer.io/sts/faqs/known-issues/resource-limits-in-a-compose-file-are-not-applying#fix) Fix Update Portainer to 2.15.0 or above. #### [](https://docs.portainer.io/sts/faqs/known-issues/resource-limits-in-a-compose-file-are-not-applying#workaround) Workaround You can manually apply limits on a per-container basis after deployment [through the Portainer UI](https://docs.portainer.io/sts/user/docker/containers/edit) . [PreviousGroups info issue with OAuth using Microsoft AD](https://docs.portainer.io/sts/faqs/known-issues/groups-info-issue-with-oauth-using-microsoft-ad) [NextHardware Acceleration GPU button is missing](https://docs.portainer.io/sts/faqs/known-issues/hardware-acceleration-gpu-button-is-missing) Was this helpful? --- # Groups info issue with OAuth using Microsoft AD | 2.35 STS | Portainer Documentation **Affected versions:** 2.14.2 and previous **Fixed in:** 2.15.0 and above #### [](https://docs.portainer.io/sts/faqs/known-issues/groups-info-issue-with-oauth-using-microsoft-ad#issue-description) Issue Description If you have configured OAuth using Microsoft AD in Portainer and trying to use Automatic Team membership you may run into an issue where group membership information is not returned correctly and users are not populated into the correct teams in Portainer. #### [](https://docs.portainer.io/sts/faqs/known-issues/groups-info-issue-with-oauth-using-microsoft-ad#fix) Fix Update Portainer to 2.15.0 or above. #### [](https://docs.portainer.io/sts/faqs/known-issues/groups-info-issue-with-oauth-using-microsoft-ad#workaround) Workaround In OAuth Config, use the following URL for Resource URL (replace the existing graph.windows.net URL) Copy https://login.microsoftonline.com//openid/userinfo User Identifier: unique\_name Scopes: openid profile You will also need to have following permissions on your App Registration in Azure: ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FYK2JVgdrg33IUVl8iadx%2Fimage.png&width=768&dpr=4&quality=100&sign=c38ff511&sv=2) [PreviousKnown issues with VMware](https://docs.portainer.io/sts/faqs/known-issues/known-issues-with-vmware) [NextResource limits in a compose file are not applying](https://docs.portainer.io/sts/faqs/known-issues/resource-limits-in-a-compose-file-are-not-applying) Was this helpful? --- # Hardware Acceleration GPU button is missing | 2.35 STS | Portainer Documentation **Affected versions:** 2.15.0 and above **Fixed in:** Upcoming release #### [](https://docs.portainer.io/sts/faqs/known-issues/hardware-acceleration-gpu-button-is-missing#issue-description) Issue Description After upgrading a Portainer installation from 2.14.2 to a newer version, the Hardware Acceleration GPU button is missing. #### [](https://docs.portainer.io/sts/faqs/known-issues/hardware-acceleration-gpu-button-is-missing#cause) Cause This issue is the result of a bug in the upgrade process of Portainer where a value is set incorrectly. #### [](https://docs.portainer.io/sts/faqs/known-issues/hardware-acceleration-gpu-button-is-missing#workaround) Workaround You can manually resolve this issue in your configuration through the Portainer API by setting the Gpus option to the correct value of \[\]. Here is an example API command: Copy http --verify=no PUT https://localhost:9443/api/endpoints/1 X-API-Key:my-api-key Gpus:='[]' [PreviousResource limits in a compose file are not applying](https://docs.portainer.io/sts/faqs/known-issues/resource-limits-in-a-compose-file-are-not-applying) [NextUnable to update environment variables when running on Synology NAS](https://docs.portainer.io/sts/faqs/known-issues/unable-to-update-environment-variables-when-running-on-synology-nas) Was this helpful? --- # Nomad Jobs only displays Service Jobs | 2.35 STS | Portainer Documentation **Affected Versions:** 2.14.0 to 2.19.4 (Nomad support was removed in 2.20.0) #### [](https://docs.portainer.io/sts/faqs/known-issues/nomad-jobs-only-displays-service-jobs#issue-description) Issue Description Nomad Jobs are only displaying Service Jobs. #### [](https://docs.portainer.io/sts/faqs/known-issues/nomad-jobs-only-displays-service-jobs#cause) Cause This issue is the result of a bug where System, Batch and Sysbatch Jobs are causing the Portainer UI to break. To avoid this bug we currently only display Service Jobs in the Portainer UI. [PreviousUnable to remove the Group Configuration from Active Directory authentication configuration](https://docs.portainer.io/sts/faqs/known-issues/unable-to-remove-the-group-configuration-from-active-directory-authentication-configuration) [Next"Image not found on registry" error when upgrading from CE to BE or self-updating on Synology NAS](https://docs.portainer.io/sts/faqs/known-issues/image-not-found-on-registry-error-when-upgrading-from-ce-to-be-or-self-updating-on-synology-nas) Was this helpful? --- # Unable to update environment variables when running on Synology NAS | 2.35 STS | Portainer Documentation **Affected versions:** All **Fixed in:** n/a #### [](https://docs.portainer.io/sts/faqs/known-issues/unable-to-update-environment-variables-when-running-on-synology-nas#issue-description) Issue Description When using Portainer on a Synology NAS device running Synology DSM, changes made to environment variables for containers and stacks in the Portainer interface are not applied to the respective container or stack. #### [](https://docs.portainer.io/sts/faqs/known-issues/unable-to-update-environment-variables-when-running-on-synology-nas#cause) Cause Our team has narrowed this down to Synology's custom implementation of Docker. Unfortunately without cooperation from Synology we have been unable to find a reliable solution to this and recommend the workarounds below. #### [](https://docs.portainer.io/sts/faqs/known-issues/unable-to-update-environment-variables-when-running-on-synology-nas#workaround) Workaround Some users have reported success when editing environment variables through Synology's interface instead of Portainer's interface. You can also export the container settings to JSON through Synology's interface, edit the JSON directly, then reimport the updated JSON. This lets you specify environment variables with blank values, which you cannot do through the Synology interface. You can find more detail on this issue [in the Github report](https://github.com/portainer/portainer/issues/5813) . [PreviousHardware Acceleration GPU button is missing](https://docs.portainer.io/sts/faqs/known-issues/hardware-acceleration-gpu-button-is-missing) [NextUnable to remove the Group Configuration from Active Directory authentication configuration](https://docs.portainer.io/sts/faqs/known-issues/unable-to-remove-the-group-configuration-from-active-directory-authentication-configuration) Was this helpful? --- # "Image not found on registry" error when upgrading from CE to BE or self-updating on Synology NAS | 2.35 STS | Portainer Documentation **Affected versions:** 2.17.0 and above #### [](https://docs.portainer.io/sts/faqs/known-issues/image-not-found-on-registry-error-when-upgrading-from-ce-to-be-or-self-updating-on-synology-nas#issue-description) Issue Description When running an in-app upgrade within Portainer that is running on a Synology NAS, users may receive an error "Image not found on registry". #### [](https://docs.portainer.io/sts/faqs/known-issues/image-not-found-on-registry-error-when-upgrading-from-ce-to-be-or-self-updating-on-synology-nas#cause) Cause Our team is currently investigating the cause of this issue, but we suspect this is a consequence of Synology's custom Docker build. #### [](https://docs.portainer.io/sts/faqs/known-issues/image-not-found-on-registry-error-when-upgrading-from-ce-to-be-or-self-updating-on-synology-nas#workaround) Workaround The workaround for this is to follow the legacy upgrade steps found in the [Portainer documentation](https://docs.portainer.io/sts/start/upgrade) and follow the manual steps option for your environment. This will guide you through the steps to update your Portainer install. Some users have also reported success with [manually pulling](https://docs.portainer.io/sts/user/docker/images/pull) the missing image first, then attempting the in-app upgrade. You can find more details on this issue in the [GitHub Issue](https://github.com/portainer/portainer/issues/8590) . [PreviousNomad Jobs only displays Service Jobs](https://docs.portainer.io/sts/faqs/known-issues/nomad-jobs-only-displays-service-jobs) [NextMicroK8s Known Issues](https://docs.portainer.io/sts/faqs/known-issues/microk8s-known-issues) Was this helpful? --- # Unable to remove the Group Configuration from Active Directory authentication configuration | 2.35 STS | Portainer Documentation **Affected versions:** 2.14.0 to 2.16.2 **Fixed in:** 2.17.0 and above #### [](https://docs.portainer.io/sts/faqs/known-issues/unable-to-remove-the-group-configuration-from-active-directory-authentication-configuration#issue-description) Issue Description Users are unable to remove the Group Configuration from the Active Directory authentication after the configuration has been saved. #### [](https://docs.portainer.io/sts/faqs/known-issues/unable-to-remove-the-group-configuration-from-active-directory-authentication-configuration#cause) Cause This issue is the result of a bug not allowing the Group Configuration fields to be edited after saving the configuration. The fields are static and greyed out. #### [](https://docs.portainer.io/sts/faqs/known-issues/unable-to-remove-the-group-configuration-from-active-directory-authentication-configuration#fix) Fix Update Portainer to 2.17.0 or above. #### [](https://docs.portainer.io/sts/faqs/known-issues/unable-to-remove-the-group-configuration-from-active-directory-authentication-configuration#workaround) Workaround Use LDAP or Custom Authentication. [PreviousUnable to update environment variables when running on Synology NAS](https://docs.portainer.io/sts/faqs/known-issues/unable-to-update-environment-variables-when-running-on-synology-nas) [NextNomad Jobs only displays Service Jobs](https://docs.portainer.io/sts/faqs/known-issues/nomad-jobs-only-displays-service-jobs) Was this helpful? --- # MicroK8s Known Issues | 2.35 STS | Portainer Documentation ### [](https://docs.portainer.io/sts/faqs/known-issues/microk8s-known-issues#installing) Installing #### [](https://docs.portainer.io/sts/faqs/known-issues/microk8s-known-issues#metrics-server) **Metrics server** For single-node clusters, if you have the metrics server addon selected when provisioning, you will most likely still need to enable the metrics API toggle manually in the Cluster Setup screen. This may be because the cluster creation finishes while the metrics server is still starting up, meaning it gets missed by the detection logic that sets the Cluster Setup defaults. For multi-node clusters the toggle defaults to on as expected. #### [](https://docs.portainer.io/sts/faqs/known-issues/microk8s-known-issues#microk8s-status-command-showing-portainer-server-as-enabled) **MicroK8s status command showing Portainer Server as enabled** On versions of MicroK8s previous to 1.29, if a `microk8s status` command is run on the cluster, Portainer Server is incorrectly shown as enabled when only the Agent is running on the cluster. This is an issue with MicroK8s rather than Portainer, and is fixed in 1.29. For those users that are on previous versions of MicroK8s and want to upgrade to 1.29, to resolve this issue you can uninstall the Portainer Agent (`sudo microk8s kubectl delete namespace portainer`), upgrade MicroK8s to 1.29, then re-install the Portainer Agent. ### [](https://docs.portainer.io/sts/faqs/known-issues/microk8s-known-issues#upgrading-and-downgrading) Upgrading and downgrading #### [](https://docs.portainer.io/sts/faqs/known-issues/microk8s-known-issues#upgrading-the-microk8s-version) **Upgrading the MicroK8s version** When an upgrade of MicroK8s is performed on a multi-node cluster, Portainer performs the following steps on every node in the cluster: 1. Drain the node 2. Update the MicroK8s version (using the snap refresh command) 3. Uncordon the node to allow workloads to be redistributed onto it. For single-node clusters, as there is nowhere to drain to we don’t do this and instead just perform step 2. If upgrading a node fails, we try to revert MicroK8s to the previous version on the node and any others that have already been upgraded. To drain a node, there should be enough resources available on the other nodes, otherwise it may fail. If a node is stuck in SchedulingDisabled status, you can always uncordon it using the CLI or by clicking on the node and choosing the Active option in the dropdown on the Node Details screen. There may be a chance that a cluster could have nodes not upgraded and left with an older version. It is better to SSH into the node and refresh the version manually. #### [](https://docs.portainer.io/sts/faqs/known-issues/microk8s-known-issues#hetzner-1.25-to-1.26-upgrade-issues) **Hetzner 1.25 to 1.26 upgrade issues** When attempting to upgrade from 1.25 to 1.26 on Hetzner environments, the upgrade reports successful but the cluster remains at 1.25. The upgrade logs show errors similar to the following: ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FvFOqoRA5ajmEQ4PQ3q2o%2Fimage.png&width=768&dpr=4&quality=100&sign=d7f703e6&sv=2) We recommend either remaining at 1.25 or upgrading manually. #### [](https://docs.portainer.io/sts/faqs/known-issues/microk8s-known-issues#upgrading-with-node-specific-addons) **Upgrading with node-specific addons** If you have manually disabled an addon on a particular node (for those addons where it's possible to have them enabled on only certain nodes), on upgrading the cluster, Portainer currently re-enables the addon on all nodes (even those where you had manually disabled them via the CLI). We are looking at fixing this behavior in an upcoming release. In the meantime, we recommend taking note of any node-specific addon configurations and manually disabling addons on specific nodes after the upgrade is complete. #### [](https://docs.portainer.io/sts/faqs/known-issues/microk8s-known-issues#cilium-and-adding-worker-nodes) **Cilium and adding worker nodes** If you have Cilium enabled, when you attempt to add a worker node, the node fails to be added and the following error is shown: Copy Scaling error: failed to get cluster join information Process exited with status 1 We recommend disabling Cilium before adding/removing nodes or upgrading your cluster. #### [](https://docs.portainer.io/sts/faqs/known-issues/microk8s-known-issues#multi-node-cluster-upgrade-issues) **Multi-node cluster upgrade issues** Upgrading of a multi-node cluster fails on some nodes when: 1. The hostpath-storage addon is enabled 2. A persistent volume claim (PVC) is using hostpath-storage 3. A pod is using the PVC as a volume To avoid this, we recommend removing the PVC before upgrading MicroK8s. ### [](https://docs.portainer.io/sts/faqs/known-issues/microk8s-known-issues#addons) Addons #### [](https://docs.portainer.io/sts/faqs/known-issues/microk8s-known-issues#resource-limitations) **Resource limitations** If you attempt to enable addons but do not have enough resources (CPU, RAM, disk) on your nodes, you will likely have them silently fail to enable (and so, not show as enabled). We recommend checking your resource availability and the requirements of your addons to ensure you can support them. #### [](https://docs.portainer.io/sts/faqs/known-issues/microk8s-known-issues#removing-addons) **Removing addons** In some cases when attempting to remove an addon, the removal may fail with errors similar to the following: Copy failure to disable microk8s addon gopaddle-lite on node, error: | error="Process exited with status 1" Copy failure to disable microk8s addon argocd on node, error: | error="Process exited with status 127" If this occurs we recommend attempting to remove the addon manually from the CLI. ### [](https://docs.portainer.io/sts/faqs/known-issues/microk8s-known-issues#specific-addon-issues) **Specific addon issues** #### [](https://docs.portainer.io/sts/faqs/known-issues/microk8s-known-issues#openfaas-and-gopaddle-lite) **openfaas and gopaddle-lite** When you enable the openfaas addon, Portainer will also show that the gopaddle-lite addon is enabled, which is not the case. This is because openfaas creates a gateway deployment which gopaddle-lite uses to check whether it is enabled. The same situation occurs in reverse; if gopaddle-lite is enabled, openfaas will report as enabled as well. #### [](https://docs.portainer.io/sts/faqs/known-issues/microk8s-known-issues#knative) **knative** When performing an update, the knative addon can sometimes fail to re-enable after the update completes. If this happens you can manually re-enable the addon. #### [](https://docs.portainer.io/sts/faqs/known-issues/microk8s-known-issues#hostpath-storage) **hostpath-storage** If you have the hostpath-storage addon enabled for your cluster and store some data in that storage, that data will be deleted if you disable the hostpath-storage addon. We recommend either leaving the addon enabled or ensuring you back up any data before disabling it. #### [](https://docs.portainer.io/sts/faqs/known-issues/microk8s-known-issues#kube-ovn) **kube-ovn** The Kube-OVN (all core) addon has certain prerequisites that must be set up before enabling. This addon has not been included in the list of those that can be enabled/disabled via the Portainer UI. We hope to add support for it in a future Portainer release. [Previous"Image not found on registry" error when upgrading from CE to BE or self-updating on Synology NAS](https://docs.portainer.io/sts/faqs/known-issues/image-not-found-on-registry-error-when-upgrading-from-ce-to-be-or-self-updating-on-synology-nas) [Next"Unauthorized" error when pushing images to ACR with Service Principal account](https://docs.portainer.io/sts/faqs/known-issues/unauthorized-error-when-pushing-images-to-acr-with-service-principal-account) Was this helpful? --- # Where can I find the documentation for Portainer? | 2.35 STS | Portainer Documentation You can find our full documentation portal at [https://docs.portainer.io/](https://docs.portainer.io/) . [PreviousGetting support](https://docs.portainer.io/sts/faqs/getting-support) [NextHow to get support for Community Edition and 5 Nodes Free Users](https://docs.portainer.io/sts/faqs/getting-support/how-to-get-support-for-community-edition-and-5-nodes-free-users) Was this helpful? --- # Which versions of Portainer do you provide support for? | 2.35 STS | Portainer Documentation The Portainer Support Team provides the following version support: **Portainer Business Edition** Latest and 3 previous major releases **Portainer Community Edition** Latest release only [PreviousHow to get support for Business Edition Customers with a subscription](https://docs.portainer.io/sts/faqs/getting-support/how-to-get-support-for-business-edition-customers-with-a-subscription) [NextCLI configuration options](https://docs.portainer.io/sts/advanced/cli) Was this helpful? --- # Access control | 2.35 STS | Portainer Documentation All Docker and Docker Swarm resources (except images) deployed through Portainer have access control settings. You can set these when resources are deployed or at a later time. Resources deployed through a stack or a service will inherit the same access as the parent. [](https://docs.portainer.io/sts/advanced/access-control#resources-deployed-through-portainer) Resources deployed through Portainer ---------------------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.portainer.io/sts/advanced/access-control#access-to-administrators-only) Access to administrators only This is an example access control section, showing access control enabled. With these settings, only Portainer administrators will have access to the resource and any other resources created by it (for example, a stack that creates containers, services, volumes, networks and secrets). ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FBz77YY88HnVlrYLSdci3%2F2.15-advanced-accesscontrol-admin.png&width=768&dpr=4&quality=100&sign=70e1b3f6&sv=2) ### [](https://docs.portainer.io/sts/advanced/access-control#access-to-all-users) Access to all users This is an example access control section showing access control disabled. All Portainer users will have access to the resource and any resources created by it. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FPfNKQsrxrUTDNDpvB4Uk%2F2.15-advanced-accesscontrol-public.png&width=768&dpr=4&quality=100&sign=38b346d3&sv=2) ### [](https://docs.portainer.io/sts/advanced/access-control#access-restricted-to-specific-groups-or-users) Access restricted to specific groups or users This is an example access control section showing access control enabled in **Restricted** mode. After you select the Restricted option, you can select more teams and users and give them access to the resource. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FZCKhLZHxUnxxTwzY4JP7%2F2.15-advanced-accesscontrol-restricted.png&width=768&dpr=4&quality=100&sign=1c5001ed&sv=2) [](https://docs.portainer.io/sts/advanced/access-control#resources-deployed-outside-of-portainer) Resources deployed outside of Portainer ---------------------------------------------------------------------------------------------------------------------------------------------- Any resources deployed to Docker or Docker Swarm outside of Portainer will be marked as `external` and you will have limited control over these resources. By default, these resources will have administrator-only access, but you can enable access control using these labels (examples used, swap out for your own parameters): Label Access Granted `io.portainer.accesscontrol.public` All Portainer users have access to the resource. Takes precedence over team/user assignments. `io.portainer.accesscontrol.teams=dev,prod` Access restricted to teams `dev` and `prod` only. Can be used in conjunction with `io.portainer.accesscontrol.users` `io.portainer.accesscontrol.users=bob,adam` Access is restricted to users `bob` and `adam` only. Can be used in conjunction with `io.portainer.accesscontrol.teams` ### [](https://docs.portainer.io/sts/advanced/access-control#examples) Example 1 Deploy a stack using Docker Compose and restrict access to teams `dev` and `prod`: Copy version: '3.2' services: ltest: image: busybox:latest command: "ping localhost" labels: io.portainer.accesscontrol.teams: dev,prod ### [](https://docs.portainer.io/sts/advanced/access-control#example-2) Example 2 Deploy a stack using the Docker CLI and restrict access to team `testers` and users `bob` and `adam`: Copy version: '3.2' services: ltest: image: busybox:latest command: "ping localhost" labels: io.portainer.accesscontrol.teams: testers io.portainer.accesscontrol.users: bob,adam ### [](https://docs.portainer.io/sts/advanced/access-control#example-3) Example 3 Deploy a container using the Docker CLI and make it accessible to all Portainer users: Copy docker run -d --label io.portainer.accesscontrol.public nginx:latest ### [](https://docs.portainer.io/sts/advanced/access-control#example-4) Example 4 Deploy a container using the Docker CLI and restrict access to teams `dev` and `prod` and users `bob`: Copy docker run -d --label io.portainer.accesscontrol.teams=dev,prod --label io.portainer.accesscontrol.users=bob nginx:latest [PreviousThe Portainer Edge Agent](https://docs.portainer.io/sts/advanced/edge-agent) [NextReset the admin user's password](https://docs.portainer.io/sts/advanced/reset-admin) Was this helpful? --- # Getting support | 2.35 STS | Portainer Documentation * [Where can I find the documentation for Portainer?](https://docs.portainer.io/sts/faqs/getting-support/where-can-i-find-the-documentation-for-portainer) * [How to get support for Community Edition and 5 Nodes Free Users](https://docs.portainer.io/sts/faqs/getting-support/how-to-get-support-for-community-edition-and-5-nodes-free-users) * [How to get support for Business Edition Customers with a subscription](https://docs.portainer.io/sts/faqs/getting-support/how-to-get-support-for-business-edition-customers-with-a-subscription) * [Which versions of Portainer do you provide support for?](https://docs.portainer.io/sts/faqs/getting-support/which-versions-of-portainer-do-you-provide-support-for) [PreviousKnown compatibility issues with Docker Engine 29.0.0](https://docs.portainer.io/sts/faqs/known-issues/known-compatibility-issues-with-docker-engine-29.0.0) [NextWhere can I find the documentation for Portainer?](https://docs.portainer.io/sts/faqs/getting-support/where-can-i-find-the-documentation-for-portainer) Was this helpful? --- # How to get support for Community Edition and 5 Nodes Free Users | 2.35 STS | Portainer Documentation #### [](https://docs.portainer.io/sts/faqs/getting-support/how-to-get-support-for-community-edition-and-5-nodes-free-users#hs_cos_wrapper_kb-article-module-4) If you're a Community Edition or 5 Nodes Free User here are the ways to get support. 1. Check our documentation and knowledge base first. 2. Then if you are still having trouble you can post your issue or question on: 1. Our [Portainer Community Slack Channel](https://portainer.slack.com/join/shared_invite/zt-txh3ljab-52QHTyjCqbe5RibC2lcjKA#) 2. Our [Discord Channel](https://discord.com/invite/j8fVken) 3. If you need personalized, prioritized support then talk to our [Success team](https://www.portainer.io/portainer-business-buy-more-nodes?hsLang=en) regarding a purchase of Business Edition. [PreviousWhere can I find the documentation for Portainer?](https://docs.portainer.io/sts/faqs/getting-support/where-can-i-find-the-documentation-for-portainer) [NextHow to get support for Business Edition Customers with a subscription](https://docs.portainer.io/sts/faqs/getting-support/how-to-get-support-for-business-edition-customers-with-a-subscription) Was this helpful? --- # Security and compliance | 2.35 STS | Portainer Documentation Portainer runs exclusively on your servers, within your network, behind your own firewalls. As a result, we do not currently hold any SOC or PCI/DSS compliance because we do not host any of your infrastructure. You can even run Portainer completely disconnected (air-gapped) without any impact on functionality. We comply with GDPR in relation to the anonymous analytics we collect. Data collection can be disabled at startup (or at any time), and if you are disconnected, it silently fails. The Portainer code itself does not undergo any formal code analysis, however we scan our published images for vulnerabilities as part of the DockerHub process. We are also the subject of regular third-party vulnerability analyses. No issues have been reported for some time, and any issues that are discovered are resolved within six weeks. [PreviousReset the admin user's password](https://docs.portainer.io/sts/advanced/reset-admin) [NextEncrypting the Portainer database](https://docs.portainer.io/sts/advanced/db-encryption) Was this helpful? --- # Reset the admin user's password | 2.35 STS | Portainer Documentation If your Portainer admin forgets their password, follow these steps to reset it. There are three methods depending on your Portainer environment. [](https://docs.portainer.io/sts/advanced/reset-admin#method-1-resetting-the-admin-password-if-portainer-runs-as-a-container) Method 1: Resetting the admin password if Portainer runs as a container ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You would typically use this method if you run the Portainer Server on Docker Standalone. First, go to our [reset password container helper](https://github.com/portainer/helper-reset-password) in GitHub, then stop the Portainer container by running this command: Copy docker stop "id-portainer-container" Next, run the helper using the following command (you'll need to mount the Portainer data volume): If your Portainer data volume has a different name than `portainer_data` or you are using a bind mount for your data volume, you will need to adjust the mount in the below `docker run` command to suit your path. Copy docker pull portainer/helper-reset-password docker run --rm -v portainer_data:/data portainer/helper-reset-password If successful, the output should look like this: Copy 2020/06/04 00:13:58 Password successfully updated for user: admin 2020/06/04 00:13:58 Use the following password to login: &_4#\3^5V8vLTd)E"NWiJBs26G*9HPl1 If the helper is unable to find an admin user to update, it will create a new one for you. If the username `admin` is already used, it will create a user named `admin-[randomstring]`: Copy 2022/08/10 07:36:33 [WARN] Unable to retrieve user with ID 1, will try to create, err: object not found inside the database 2022/08/10 07:36:33 Admin user admin-u0512b3f0v4dqk7o successfully created 2022/08/10 07:36:33 Use the following password to login: Sr#]YL_6D0k8Pd{pA9^|}F32j5J4I=av Finally, use this command to start the Portainer container then try logging in with the new password: Copy docker start "id-portainer-container" [](https://docs.portainer.io/sts/advanced/reset-admin#method-2-resetting-the-admin-password-if-portainer-runs-as-a-stack-service) Method 2: Resetting the admin password if Portainer runs as a stack/service ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ You would typically use this method if you run the Portainer Server on Docker Swarm. First, scale the Portainer service to zero using this command: Copy docker service scale portainer_portainer=0 Next, run the [reset password container helper](https://github.com/portainer/helper-reset-password) using the same bind-mount/volume as the data volume: If your Portainer data volume has a different name than `portainer_data` or you are using a bind mount for your data volume, you will need to adjust the mount in the below `docker run` command to suit your path. Copy docker pull portainer/helper-reset-password docker run --rm -v portainer_portainer_data:/data portainer/helper-reset-password If successful, the output should look like this: Copy 2020/06/04 00:13:58 Password successfully updated for user: admin 2020/06/04 00:13:58 Use the following password to login: &_4#\3^5V8vLTd)E"NWiJBs26G*9HPl1 If the helper is unable to find an admin user to update, it will create a new one for you. If the username `admin` is already used, it will create a user named `admin-[randomstring]`: Copy 2022/08/10 07:36:33 [WARN] Unable to retrieve user with ID 1, will try to create, err: object not found inside the database 2022/08/10 07:36:33 Admin user admin-u0512b3f0v4dqk7o successfully created 2022/08/10 07:36:33 Use the following password to login: Sr#]YL_6D0k8Pd{pA9^|}F32j5J4I=av Finally, start up the Portainer service scaling using this command then try logging in with the new password: Copy docker service scale portainer_portainer=1 [](https://docs.portainer.io/sts/advanced/reset-admin#method-3-resetting-the-admin-password-if-portainer-is-deployed-in-a-kubernetes-cluster) Method 3: Resetting the admin password if Portainer is deployed in a Kubernetes cluster ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ You would typically use this method if you run the Portainer Server on a Kubernetes cluster. First, scale the Portainer deployment to zero using this command: Copy kubectl scale deploy portainer --replicas=0 -n portainer Next, create a pod using the [reset password container helper](https://github.com/portainer/helper-reset-password) image and mount the Portainer data volume. Create a pod YAML file using the command below: You may need to change the YAML below to match your Portainer deployment (for example if using a different `claimName`). Copy cat > passreset.yml<< EOF apiVersion: v1 kind: Pod metadata: name: passreset spec: volumes: - name: data persistentVolumeClaim: claimName: portainer containers: - name: passreset image: portainer/helper-reset-password volumeMounts: - mountPath: "/data" name: data restartPolicy: Never EOF Create the password reset pod using the command below: Copy kubectl apply -f passreset.yml -n portainer Once the new pod is created and transitions into a completed state, you can see the new password in the pod logs: Copy kubectl logs passreset -n portainer If successful, the output should look something like this: Copy 2020/06/04 00:13:58 Password successfully updated for user: admin 2020/06/04 00:13:58 Use the following password to login: &_4#\3^5V8vLTd)E"NWiJBs26G*9HPl1 Finally, scale up the Portainer deployment using this command then try logging in with the new password: Copy kubectl scale deploy portainer --replicas=1 -n portainer You can delete the password reset pod using the below command: Copy kubectl delete pod passreset -n portainer [PreviousAccess control](https://docs.portainer.io/sts/advanced/access-control) [NextSecurity and compliance](https://docs.portainer.io/sts/advanced/security) Was this helpful? --- # App templates | 2.35 STS | Portainer Documentation You can deploy containers and services using Portainer's set of built-in app templates, or replace them with your own set of templates. [Build and host your own app templates](https://docs.portainer.io/sts/advanced/app-templates/build) [App template JSON format](https://docs.portainer.io/sts/advanced/app-templates/format) [PreviousCLI configuration options](https://docs.portainer.io/sts/advanced/cli) [NextBuild and host your own app templates](https://docs.portainer.io/sts/advanced/app-templates/build) Was this helpful? --- # "Unauthorized" error when pushing images to ACR with Service Principal account | 2.35 STS | Portainer Documentation **Affected versions:** 2.13.0 and above **Fixed in:** Upcoming release #### [](https://docs.portainer.io/sts/faqs/known-issues/unauthorized-error-when-pushing-images-to-acr-with-service-principal-account#issue-description) Issue Description Users are unable to push images to the Azure Container Registry. The following error appears: Copy `Unauthorized: authentication required, visit for more information."},"error":"unauthorized: authentication required, visit for more information."}` #### [](https://docs.portainer.io/sts/faqs/known-issues/unauthorized-error-when-pushing-images-to-acr-with-service-principal-account#cause) Cause This issue is the result of using Service Principal accounts in the Azure Container Registry configuration in Portainer. #### [](https://docs.portainer.io/sts/faqs/known-issues/unauthorized-error-when-pushing-images-to-acr-with-service-principal-account#workaround) Workaround You will need to configure your Azure Container Registry using the Access Key (Admin) account. [PreviousMicroK8s Known Issues](https://docs.portainer.io/sts/faqs/known-issues/microk8s-known-issues) [Next"Invalid certificate file" error when browsing empty Azure Container Registry](https://docs.portainer.io/sts/faqs/known-issues/invalid-certificate-file-error-when-browsing-empty-azure-container-registry) Was this helpful? --- # Known compatibility issues with Docker Engine 29.0.0 | 2.35 STS | Portainer Documentation The latest Docker Engine 29.0.0 introduces breaking changes that prevent current Portainer versions from connecting to Docker Standalone environments. Until support is added, please keep using the Docker versions listed on our [requirements page](https://docs.portainer.io/sts/start/requirements-and-prerequisites) . A temporary workaround has been found by our community and is detailed under [GitHub Issue 12925](https://github.com/portainer/portainer/issues/12925#issuecomment-3516549977) . [Previous"Invalid certificate file" error when browsing empty Azure Container Registry](https://docs.portainer.io/sts/faqs/known-issues/invalid-certificate-file-error-when-browsing-empty-azure-container-registry) [NextGetting support](https://docs.portainer.io/sts/faqs/getting-support) Last updated 2 days ago Was this helpful? --- # How to get support for Business Edition Customers with a subscription | 2.35 STS | Portainer Documentation #### [](https://docs.portainer.io/sts/faqs/getting-support/how-to-get-support-for-business-edition-customers-with-a-subscription#hs_cos_wrapper_kb-article-module-4) If you're a Business Edition Customer here are the ways to get support. 1. Go to [Get Business Support](https://www.portainer.io/portainer-business-support?hsLang=en) and log a support case 1. Complete the form, providing as much detail as possible (we love screenshots!) then submit. 2. Ticket updates are managed in the portal (you'll also receive an email notification). 3. Note: If we think it's easier to speak to you about a ticket, we'll set up a Zoom meeting. [PreviousHow to get support for Community Edition and 5 Nodes Free Users](https://docs.portainer.io/sts/faqs/getting-support/how-to-get-support-for-community-edition-and-5-nodes-free-users) [NextWhich versions of Portainer do you provide support for?](https://docs.portainer.io/sts/faqs/getting-support/which-versions-of-portainer-do-you-provide-support-for) Was this helpful? --- # The Portainer Edge Agent | 2.35 STS | Portainer Documentation [](https://docs.portainer.io/sts/advanced/edge-agent#the-back-story) The back story ---------------------------------------------------------------------------------------- For standard deployments, we used to assume that the Portainer instance and any environments shared the same network and could communicate seamlessly. If remote environments were on a different network (say, across the Internet) we could not manage them. Then we changed the Edge agent architecture so only the environments need to access Portainer. There is now no need to expose the Portainer agents to the Internet. Portainer now requires that only the `9443` and `8000` TCP ports are exposed. We used to serve the UI and the Portainer API from port `9000`, but we extended the API to allow the remote agents to poll for instructions. Port `8000` is a TLS tunnel server used to create a secure tunnel between the agent and the Portainer instance. More about that soon. If your Portainer instance is deployed with TLS, the agent will use HTTPS for the connection it makes back to Portainer. However, if your Portainer instance uses a self-signed certificate, the Edge Agent must be deployed with the `-e EDGE_INSECURE_POLL=1` flag. If you do not deploy the Edge Agent with this flag, the agent won't be able to communicate with the Portainer instance. [](https://docs.portainer.io/sts/advanced/edge-agent#creating-an-edge-agent-in-portainer) Creating an Edge Agent in Portainer ---------------------------------------------------------------------------------------------------------------------------------- When you create an Edge Agent, you are first asked for a human-friendly endpoint name. You are then asked to confirm the FQDN:PORT of your Portainer instance. This is what agents will use to connect, so make sure it’s correct and that the DNS resolves. During the creation process, an Edge ID is dynamically generated. This is a random UUID which is assigned to each environment. You can see it in the command syntax which is provided during the setup process. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FSe5bwcPFn1WK7bOQ2F1Y%2F2.15-advanced-edgeagent-command.png&width=768&dpr=4&quality=100&sign=baee6eb9&sv=2) The Edge ID and the join token are unique per environment. The join token (`EDGE_KEY`) is made up of the following base64 encoded data separated by the pipe (`|`) character: * The Portainer instance API URL. This is how the Edge Agent knows how to ‘call home’ to your Portainer instance. * The Portainer instance reverse tunnel server address. This is identical to the API URL (unless [changed during deployment](https://docs.portainer.io/sts/admin/environments/add/docker/edge#deploying) or in [Edge Compute settings](https://docs.portainer.io/sts/admin/settings/edge#edge-compute-settings) ) but with the tunnel server port (`8000` is the default). * The Portainer instance reverse-tunnel server fingerprint (prevents MITM when creating a tunnel). * The environment identifier key (endpoint / environment ID). Use the command syntax to deploy an Edge Agent across your remote node or remote swarm cluster. [](https://docs.portainer.io/sts/advanced/edge-agent#how-portainer-and-the-edge-agent-communicate) How Portainer and the Edge Agent communicate ---------------------------------------------------------------------------------------------------------------------------------------------------- ### [](https://docs.portainer.io/sts/advanced/edge-agent#polling) Polling Agents poll the Portainer instance every 5 seconds by default (this is defined in Portainer settings). ### [](https://docs.portainer.io/sts/advanced/edge-agent#connection-process-and-checks) Connection process and checks The agent says to Portainer, “Hi, I'm an agent. My join token is `abc123`. Do you need me right now?”. Portainer checks its database to ensure the Edge UUID and the join token match. If no UUID can be associated with the join token provided, Portainer will associate the UUID provided by the agent to the environment’s join token. If the UUID/join token do not match, the connection is rejected. If the UUID/join token match, the Portainer instance responds with either: "No, I don’t need you. Please check in again in X seconds." (where X is the agent polling frequency), or "Yes, I do need you. Please connect using these tunnel credentials.”. Portainer encrypts the tunnel credentials using the Edge UUID as the encryption key (intended as one-time-use credentials). ### [](https://docs.portainer.io/sts/advanced/edge-agent#opening-a-tunnel-between-the-agent-and-portainer) Opening a tunnel between the agent and Portainer Once confirmation is received, the Edge Agent decrypts the credentials and opens a tunnel on port `8000` to the Portainer instance. If a remote environment is a swarm cluster, every node will run an instance of the agent (and every instance will poll Portainer). The 'you are required' flag causes the first agent in the cluster to establish the tunnel. Once in place, Portainer can then query the agent where the tunnel is open. If the tunnel closes for any reason, the agent will immediately re-establish it. ### [](https://docs.portainer.io/sts/advanced/edge-agent#when-portainer-forces-the-edge-agent-to-establish-a-tunnel) When Portainer forces the Edge Agent to establish a tunnel Sometimes Portainer will ask the agent to establish a tunnel. This happens when an admin selects an Edge environment for interactive management via the Portainer UI or the API. Once selected, the 'you are required' flag triggers the connection process. If default settings are in use, it takes about 10 seconds for the agent to poll and establish a tunnel. That’s about 5 seconds wait time until polling then a few seconds for the tunnel to open. The admin is shown this message while this happens: ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FDD4a2va9nviGIGI0pMHe%2Fedge-advanced-2.png&width=768&dpr=4&quality=100&sign=7eff58d7&sv=2) ### [](https://docs.portainer.io/sts/advanced/edge-agent#terminating-the-connection) Terminating the connection The agent keeps a record of when Portainer last communicated with it. After 5 minutes of inactivity, it sends a snapshot of the current config to Portainer for its records, closes the tunnel and revokes the credentials. When admins have an active session with an Edge environment, ‘keep alives’ are sent every minute (even if the admin is not performing a task) so they are not kicked out by mistake. [](https://docs.portainer.io/sts/advanced/edge-agent#network-performance) Network performance -------------------------------------------------------------------------------------------------- ### [](https://docs.portainer.io/sts/advanced/edge-agent#adjusting-the-polling-frequency-to-improve-performance) Adjusting the polling frequency to improve performance Thousands of endpoints polling Portainer every 5 seconds is a lot. That’s about 324b/second per agent, not per environment. If you don’t do a lot of environment admin, we suggest you go into Portainer settings and increase the polling frequency. Simply change it back when you need to do some admin so you are not kept waiting. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2Fbbb46CxI1lTo51ZktvTp%2F2.15-advanced-edgeagent-pollfreq.png&width=768&dpr=4&quality=100&sign=6f43a421&sv=2) ### [](https://docs.portainer.io/sts/advanced/edge-agent#ongoing-improvements) Ongoing improvements We load-tested Portainer with 15,000 actively connected environments with a polling frequency of 5 seconds. This generated 7Mbps of network traffic to the Portainer instance, and Portainer needed 4 CPUs to handle the encryption/tunnel load. This Edge Agent release is our first attempt at massive-scale centralized management. Our end goal is to reduce the network overhead associated with polling. [PreviousApp template JSON format](https://docs.portainer.io/sts/advanced/app-templates/format) [NextAccess control](https://docs.portainer.io/sts/advanced/access-control) Was this helpful? --- # Build and host your own app templates | 2.35 STS | Portainer Documentation To provide your own template files, you will need to host your files somewhere accessible by the Portainer Server instance. This could be somewhere like GitHub, a web server, or perhaps a container running nginx. As an example, the Portainer templates repository includes a `Dockerfile` that lets you start it as a container to serve the JSON file. To set this up, first clone the [Portainer templates repository](https://github.com/portainer/templates) , edit the templates file, then build and run the container: Copy 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 Access your template 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: Copy docker run -d -p "8080:80" -v "${PWD}/templates.json:/usr/share/nginx/html/templates.json" portainer-templates For more information about the format of the app template, go [here](https://docs.portainer.io/sts/advanced/app-templates/format) . [PreviousApp templates](https://docs.portainer.io/sts/advanced/app-templates) [NextApp template JSON format](https://docs.portainer.io/sts/advanced/app-templates/format) Was this helpful? --- # "Invalid certificate file" error when browsing empty Azure Container Registry | 2.35 STS | Portainer Documentation **Affected versions:** 2.13.0 to 2.17.1 **Fixed in:** 2.18.1 and above #### [](https://docs.portainer.io/sts/faqs/known-issues/invalid-certificate-file-error-when-browsing-empty-azure-container-registry#issue-description) Issue Description Users are unable to browse the Azure Container Registry. The following error will appear: Copy Invalid certificate file. Ensure that the file is uploaded correctly #### [](https://docs.portainer.io/sts/faqs/known-issues/invalid-certificate-file-error-when-browsing-empty-azure-container-registry#cause) Cause This issue is the result attempting to browse an empty Azure Container Registry. #### [](https://docs.portainer.io/sts/faqs/known-issues/invalid-certificate-file-error-when-browsing-empty-azure-container-registry#fix) Fix Upgrade Portainer to 2.18.1 or above. #### [](https://docs.portainer.io/sts/faqs/known-issues/invalid-certificate-file-error-when-browsing-empty-azure-container-registry#workaround) Workaround Users will need to manually create create a repository in the Azure Container Registry and while logged in with the Access Key in Portainer, push an image. Users can then navigate back to the Registry and browse. [Previous"Unauthorized" error when pushing images to ACR with Service Principal account](https://docs.portainer.io/sts/faqs/known-issues/unauthorized-error-when-pushing-images-to-acr-with-service-principal-account) [NextKnown compatibility issues with Docker Engine 29.0.0](https://docs.portainer.io/sts/faqs/known-issues/known-compatibility-issues-with-docker-engine-29.0.0) Was this helpful? --- # Stream auth and activity logs to an external provider | 2.35 STS | Portainer Documentation This is an experimental feature. With Portainer 2.20 and later, you can configure the streaming of Portainer's authentication and activity logs to an external Security Information and Event Management (SIEM) system in Syslog format. This is done via CLI flags when starting the Portainer container. [](https://docs.portainer.io/sts/advanced/siem#available-cli-flags) Available CLI flags -------------------------------------------------------------------------------------------- Flag Description `--syslog-address` Syslog Address to stream authentication and activity logs. FQDN or IP Address only. `--syslog-port` Syslog Port for the address above. Defaults to `514`. `--syslog-protocol` Syslog Protocol to send logs to the Syslog Server. Supported values are `udp`, `tcp`, or `tcp+tls`. Defaults to `udp`. `--syslog-format` Syslog Format to be used. Supported values are `rfc3164` or `rfc5424`. Defaults to `rfc5424.` `--syslog-source-hostname` The hostname value that will be shown in the Syslog server in the messages. Defaults to `portainer`. `--syslog-insecure-skip-verify` Disable TLS server verification when using `tcp+tls` protocol. Should only be enabled for testing. Defaults to `false`. `--syslog-ca-cert` The path to the trusted CA used by the Syslog server. Defaults to `/syslog/certs/ca.pem`. `--syslog-cert` The path to the client certificate that is used to authenticate to the Syslog server via mTLS. Defaults to `/syslog/certs/cert.pem`. `--syslog-key` The path to the client key that is used to authenticate to the Syslog server via mTLS. Defaults to `/syslog/certs/key.pem`. [](https://docs.portainer.io/sts/advanced/siem#example-usage) Example usage -------------------------------------------------------------------------------- The following is an example `docker run` command to start Portainer using the above options to stream logs to a SIEM provider at `syslog.mydomain.com` on UDP port `514`. As the flags are Portainer options, they must be specified after the image specification. Copy docker run -d -p 8000:8000 -p 9443:9443 \ --name portainer \ --restart=always \ -v /var/run/docker.sock:/var/run/docker.sock \ -v portainer_data:/data \ portainer/portainer-ee:sts \ --syslog-addr=syslog.mydomain.com \ --syslog-port=514 \ --syslog-source-hostname="my-portainer-instance" [PreviousUsing mTLS with Portainer](https://docs.portainer.io/sts/advanced/mtls) [NextUsing Portainer with reverse proxies](https://docs.portainer.io/sts/advanced/reverse-proxy) Was this helpful? --- # Using Portainer with reverse proxies | 2.35 STS | Portainer Documentation If you need to, you can run Portainer behind a reverse proxy. We have guides for Traefik and nginx: [Deploying Portainer behind Traefik Proxy](https://docs.portainer.io/sts/advanced/reverse-proxy/traefik) [Deploying Portainer behind nginx reverse proxy](https://docs.portainer.io/sts/advanced/reverse-proxy/nginx) [PreviousStream auth and activity logs to an external provider](https://docs.portainer.io/sts/advanced/siem) [NextDeploying Portainer behind Traefik Proxy](https://docs.portainer.io/sts/advanced/reverse-proxy/traefik) Was this helpful? --- # Using your own SSL certificate with Portainer | 2.35 STS | Portainer Documentation By default, Portainer’s web interface and API is exposed over HTTPS with a self-signed certificate generated by the installation. This can be replaced with your own SSL certificate either after installation [via the Portainer UI](https://docs.portainer.io/sts/admin/settings#ssl-certificate) or during installation, as explained in this article. When using your own externally-issued certificate, ensure that you include the full certificate chain (including any intermediate certificates) in the file you provide via `--sslcert`. Without this you may face certificate validation issues. Your certificate chain can be obtained either from your certificate issuer or the [What's My Chain Cert?](https://whatsmychaincert.com/) website. [](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-docker-standalone) Using your own SSL certificate on Docker Standalone ----------------------------------------------------------------------------------------------------------------------------------------------------------- Portainer expects certificates in PEM format. Use the `--sslcert` and `--sslkey` flags during installation. Upload your certificate (including the chain) and key to the server running Portainer, then start Portainer referencing them. The following command assumes your certificates are stored in `/path/to/your/certs` with the filenames `portainer.crt` and `portainer.key`, and bind-mounts the directory to `/certs` in the Portainer container: Business Edition Community Edition Copy docker run -d -p 9443:9443 -p 8000:8000 \ --name portainer --restart always \ -v /var/run/docker.sock:/var/run/docker.sock \ -v portainer_data:/data \ -v /path/to/your/certs:/certs \ portainer/portainer-ee:sts \ --sslcert /certs/portainer.crt \ --sslkey /certs/portainer.key Copy docker run -d -p 9443:9443 -p 8000:8000 \ --name portainer --restart always \ -v /var/run/docker.sock:/var/run/docker.sock \ -v portainer_data:/data \ -v /path/to/your/certs:/certs \ portainer/portainer-ce:sts \ --sslcert /certs/portainer.crt \ --sslkey /certs/portainer.key Alternatively, Certbot can be used to generate a certificate and a key. Because Docker has issues with symlinks, if you use Certbot you will need to pass both the 'live' and 'archive' directories as volumes, as well as use the full chain certificate. For example: Business Edition Community Edition Copy docker run -d -p 9443:9443 -p 8000:8000 \ --name portainer --restart always \ -v /var/run/docker.sock:/var/run/docker.sock \ -v portainer_data:/data \ -v /etc/letsencrypt/live/yourdomain:/certs/live/yourdomain:ro \ -v /etc/letsencrypt/archive/yourdomain:/certs/archive/yourdomain:ro \ portainer/portainer-ee:sts \ --sslcert /certs/live/yourdomain/fullchain.pem \ --sslkey /certs/live/yourdomain/privkey.pem Copy docker run -d -p 9443:9443 -p 8000:8000 \ --name portainer --restart always \ -v /var/run/docker.sock:/var/run/docker.sock \ -v portainer_data:/data \ -v /etc/letsencrypt/live/yourdomain:/certs/live/yourdomain:ro \ -v /etc/letsencrypt/archive/yourdomain:/certs/archive/yourdomain:ro \ portainer/portainer-ce:sts \ --sslcert /certs/live/yourdomain/fullchain.pem \ --sslkey /certs/live/yourdomain/privkey.pem When you're finished, you can navigate to `https://$ip-docker-host:9443`. [](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-docker-swarm) Using your own SSL certificate on Docker Swarm ------------------------------------------------------------------------------------------------------------------------------------------------- To provide your own SSL certificate for Docker Swarm, simply define the `portainer.sslcert` and `portainer.sslkey` secrets, and the installation manifest will automatically detect and use them: Copy docker secret create portainer.sslcert /path/to/your/certificate.crt docker secret create portainer.sslkey /path/to/your/certificate.key Next, retrieve the stack YML manifest: Linux and Windows with Docker Desktop Windows Container Services **Business Edition:** Copy curl -L https://downloads.portainer.io/ee-sts/portainer-agent-stack-ssl.yml -o portainer-agent-stack.yml **Community Edition:** Copy curl -L https://downloads.portainer.io/ce-sts/portainer-agent-stack-ssl.yml -o portainer-agent-stack.yml **Business Edition:** Copy curl https://downloads.portainer.io/ee-sts/portainer-windows-stack-ssl.yml -o portainer-agent-stack.yml **Community Edition:** Copy curl https://downloads.portainer.io/ce-sts/portainer-windows-stack-ssl.yml -o portainer-agent-stack.yml Finally, use the downloaded YML manifest to deploy your stack: Copy docker stack deploy -c portainer-agent-stack.yml portainer For more information about secrets, read [Docker's own documentation](https://docs.docker.com/compose/compose-file/#secrets) . [](https://docs.portainer.io/sts/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) Using your own SSL certificate on Kubernetes (via Helm) ----------------------------------------------------------------------------------------------------------------------------------------------------------------- If it doesn't already exist, create the `portainer` namespace: Copy kubectl create namespace portainer Next, create a TLS secret containing the full certificate chain and matching private key: Copy kubectl create secret tls portainer-tls-secret -n portainer \ --cert=/path/to/cert/file \ --key=/path/to/key/file Install via helm with the `tls.existingSecret` parameter set to the name of the secret you just created: NodePort Load Balancer **Business Edition:** Copy helm install -n portainer portainer portainer/portainer \ --set tls.existingSecret=portainer-tls-secret \ --set enterpriseEdition.enabled=true **Community Edition:** Copy helm install -n portainer portainer portainer/portainer \ --set tls.existingSecret=portainer-tls-secret Business Edition: Copy helm install -n portainer portainer portainer/portainer \ --set tls.existingSecret=portainer-tls-secret \ --set service.type=LoadBalancer \ --set enterpriseEdition.enabled=true Community Edition: Copy helm install -n portainer portainer portainer/portainer \ --set tls.existingSecret=portainer-tls-secret \ --set service.type=LoadBalancer [PreviousEncrypting the Portainer database](https://docs.portainer.io/sts/advanced/db-encryption) [NextUsing mTLS with Portainer](https://docs.portainer.io/sts/advanced/mtls) Was this helpful? --- # Privacy Policy | 2.35 STS | Portainer Documentation You can find our privacy policy [on our website](https://www.portainer.io/legal/privacy-policy) . [PreviousSet up a Linux build environment](https://docs.portainer.io/sts/contribute/build/linux) Was this helpful? --- # Build instructions | 2.35 STS | Portainer Documentation This article explains how to set up your local development environment so you can contribute to the Portainer codebase. Make sure you have installed the dependencies for this project on your [Mac](https://docs.portainer.io/sts/contribute/build/mac) or [Linux](https://docs.portainer.io/sts/contribute/build/linux) machine before continuing. Windows is currently not supported by the Portainer development environment. [](https://docs.portainer.io/sts/contribute/build#instructions) Instructions --------------------------------------------------------------------------------- Navigate to the folder where you will store Portainer project code. This can be anywhere such as on your desktop or in your downloads folder. Now, download the Portainer project: Copy git clone https://github.com/portainer/portainer.git Next, navigate into the Portainer project you downloaded: Copy cd portainer Install the development dependencies: Copy make deps And finally, build and run the project: Copy make dev You should now be able to access Portainer at `https://localhost:9443` and UI dev server runs on `http://localhost:8999`. For additional commands, run `make help`. The frontend application will update and refresh when you save your changes to any of the sources. [](https://docs.portainer.io/sts/contribute/build#contribution-guidelines) Contribution Guidelines ------------------------------------------------------------------------------------------------------- When contributing to the Portainer codebase, please follow [our contribution guidelines](https://github.com/portainer/portainer/blob/develop/CONTRIBUTING.md) . [PreviousContribute](https://docs.portainer.io/sts/contribute/contribute) [NextSet up a macOS build environment](https://docs.portainer.io/sts/contribute/build/mac) Was this helpful? --- # Deprecated and removed features | 2.35 STS | Portainer Documentation This table lists deprecated and removed features and functionality that are no longer supported and should not be used. The **Deprecated** column shows the release in which the feature was tagged as deprecated. The **Remove** column shows the release in which the feature was or will be removed (TBD means 'to be decided'). Feature Deprecated Remove Experimental OpenAI integration 2.32.0 2.33.0 Published Portainer images being built using the Docker manifest list format in favor of the OCI image index format 2.31.0 TBD [Provision KaaS Cluster](https://docs.portainer.io/sts/admin/environments/add/kaas) feature 2.30.0 TBD [Create a MicroK8s cluster](https://docs.portainer.io/sts/admin/environments/add/kube-create/microk8s) feature 2.30.0 TBD `PUT /kubernetes/{id}/namespaces` API endpoint 2.25.0 TBD Nomad support 2.20.0 2.20.0 `POST /stacks` endpoint (use `/stacks/create/standalone`, `/stacks/create/swarm`, `/stacks/create/kubernetes` etc instead) 2.20.0 2.27.0 Enabling SSL via `--ssl` (now enabled by default) 2.9.0 TBD Disabling analytics via `--no-analytics` 2.0 TBD Kompose deployments 2.15.0 2.17.0 Specifying external environments in JSON via `--external-endpoints` 2.0 Setting time between environment synchronization requests via `--sync-interval` 2.0 Disabling Portainer internal authentication via `--no-auth` 2.0 Specifying a templates file to load on first run via `--templates-file` 2.0 Preventing Portainer from running a snapshot of environments via `--no-snapshot` 2.0 [PreviousKubernetes roles and bindings](https://docs.portainer.io/sts/advanced/kubernetes-roles-and-bindings) [NextAccessing the Portainer API](https://docs.portainer.io/sts/api/access) Was this helpful? --- # Deploying Portainer behind Traefik Proxy | 2.35 STS | Portainer Documentation [Traefik Proxy](https://traefik.io/traefik/) is a reverse proxy and load balancing solution focused on micro services. [](https://docs.portainer.io/sts/advanced/reverse-proxy/traefik#deploying-in-a-docker-standalone-scenario) Deploying in a Docker Standalone scenario --------------------------------------------------------------------------------------------------------------------------------------------------------- To deploy Portainer behind Traefik Proxy in a Docker standalone scenario you must use a Docker Compose file. In the following `docker-compose.yml` you will find the configuration for Portainer Traefik with SSL support and the Portainer Server. Business Edition Community Edition Copy version: "3.3" services: traefik: container_name: traefik image: "traefik:latest" command: - --entrypoints.web.address=:80 - --entrypoints.websecure.address=:443 - --providers.docker - --log.level=ERROR - --certificatesresolvers.leresolver.acme.httpchallenge=true - --certificatesresolvers.leresolver.acme.email=your-email #Set your email address here, is for the generation of SSL certificates with Let's Encrypt. - --certificatesresolvers.leresolver.acme.storage=./acme.json - --certificatesresolvers.leresolver.acme.httpchallenge.entrypoint=web ports: - "80:80" - "443:443" volumes: - "/var/run/docker.sock:/var/run/docker.sock:ro" - "./acme.json:/acme.json" labels: - "traefik.http.routers.http-catchall.rule=hostregexp(`{host:.+}`)" - "traefik.http.routers.http-catchall.entrypoints=web" - "traefik.http.routers.http-catchall.middlewares=redirect-to-https" - "traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https" portainer: image: portainer/portainer-ee:sts command: -H unix:///var/run/docker.sock restart: always volumes: - /var/run/docker.sock:/var/run/docker.sock - portainer_data:/data labels: # Frontend - "traefik.enable=true" - "traefik.http.routers.frontend.rule=Host(`portainer.yourdomain.com`)" - "traefik.http.routers.frontend.entrypoints=websecure" - "traefik.http.services.frontend.loadbalancer.server.port=9000" - "traefik.http.routers.frontend.service=frontend" - "traefik.http.routers.frontend.tls.certresolver=leresolver" # Edge - "traefik.http.routers.edge.rule=Host(`edge.yourdomain.com`)" - "traefik.http.routers.edge.entrypoints=websecure" - "traefik.http.services.edge.loadbalancer.server.port=8000" - "traefik.http.routers.edge.service=edge" - "traefik.http.routers.edge.tls.certresolver=leresolver" volumes: portainer_data: Copy version: "3.3" services: traefik: container_name: traefik image: "traefik:latest" command: - --entrypoints.web.address=:80 - --entrypoints.websecure.address=:443 - --providers.docker - --log.level=ERROR - --certificatesresolvers.leresolver.acme.httpchallenge=true - --certificatesresolvers.leresolver.acme.email=your-email #Set your email address here, is for the generation of SSL certificates with Let's Encrypt. - --certificatesresolvers.leresolver.acme.storage=./acme.json - --certificatesresolvers.leresolver.acme.httpchallenge.entrypoint=web ports: - "80:80" - "443:443" volumes: - "/var/run/docker.sock:/var/run/docker.sock:ro" - "./acme.json:/acme.json" labels: - "traefik.http.routers.http-catchall.rule=hostregexp(`{host:.+}`)" - "traefik.http.routers.http-catchall.entrypoints=web" - "traefik.http.routers.http-catchall.middlewares=redirect-to-https" - "traefik.http.middlewares.redirect-to-https.redirectscheme.scheme=https" portainer: image: portainer/portainer-ce:sts command: -H unix:///var/run/docker.sock restart: always volumes: - /var/run/docker.sock:/var/run/docker.sock - portainer_data:/data labels: # Frontend - "traefik.enable=true" - "traefik.http.routers.frontend.rule=Host(`portainer.yourdomain.com`)" - "traefik.http.routers.frontend.entrypoints=websecure" - "traefik.http.services.frontend.loadbalancer.server.port=9000" - "traefik.http.routers.frontend.service=frontend" - "traefik.http.routers.frontend.tls.certresolver=leresolver" # Edge - "traefik.http.routers.edge.rule=Host(`edge.yourdomain.com`)" - "traefik.http.routers.edge.entrypoints=websecure" - "traefik.http.services.edge.loadbalancer.server.port=8000" - "traefik.http.routers.edge.service=edge" - "traefik.http.routers.edge.tls.certresolver=leresolver" volumes: portainer_data: Before you run this file in Docker, you will need to create the `acme.json` file with permission `600` that will store the SSL certificates. Once it has been created, you can define the file path in the following sections in the Docker Compose file: In the volumes and command section of the Traefik Proxy container: Copy - "./acme.json:/acme.json" Copy - --certificatesresolvers.leresolver.acme.storage=./acme.json You also need to enter your email address for Let's Encrypt registration. Copy - --certificatesresolvers.leresolver.acme.email=your-email Next, customize some labels in the Traefik container. The following labels need to be updated with the URL that you want use to access Portainer: Copy - "traefik.http.routers.frontend.rule=Host(`portainer.yourdomain.com`)" Copy - "traefik.http.routers.edge.rule=Host(`edge.yourdomain.com`)" Once this is done, you're ready to deploy Portainer: Copy docker-compose up -d After the images have been downloaded and deployed you will able to access Portainer from the URL you defined earlier, for example: `https://portainer.yourdomain.com`. [](https://docs.portainer.io/sts/advanced/reverse-proxy/traefik#deploying-in-a-docker-swarm-scenario) Deploying in a Docker Swarm scenario ----------------------------------------------------------------------------------------------------------------------------------------------- To deploy Portainer behind Traefik Proxy in a Docker Swarm scenario you must use a Docker Compose file. In the following `docker-compose.yml` you will find the configuration for Portainer Traefik with SSL support and the Portainer Server. This deployment assumes you are running one manager node. If you are using multiple managers we advise [reading this article](https://docs.portainer.io/sts/faqs/installing/how-can-i-ensure-portainers-configuration-is-retained) before proceeding. Before deploying the Docker Compose file, you need to create two elements: networks and volumes. First, create two overlay networks: Copy docker network create -d overlay agent_network Copy docker network create -d overlay public Then create the volume: Copy docker volume create portainer_data Save this recipe as `portainer.yml`: Business Edition Community Edition Copy version: '3.2' services: traefik: image: "traefik:latest" command: - --entrypoints.web.address=:80 - --entrypoints.websecure.address=:443 - --providers.docker=true - --providers.swarm=true - --providers.docker.exposedbydefault=false - --providers.docker.network=public - --api - --log.level=ERROR ports: - "80:80" - "443:443" networks: - public volumes: - "/var/run/docker.sock:/var/run/docker.sock:ro" agent: image: portainer/agent:sts environment: # REQUIRED: Should be equal to the service name prefixed by "tasks." when # deployed inside an overlay network AGENT_CLUSTER_ADDR: tasks.agent # AGENT_PORT: 9001 # LOG_LEVEL: debug volumes: - /var/run/docker.sock:/var/run/docker.sock - /var/lib/docker/volumes:/var/lib/docker/volumes networks: - agent_network deploy: mode: global placement: constraints: [node.platform.os == linux] portainer: image: portainer/portainer-ee:sts command: -H tcp://tasks.agent:9001 --tlsskipverify volumes: - data:/data networks: - public - agent_network deploy: mode: replicated replicas: 1 placement: constraints: [node.role == manager] labels: - "traefik.enable=true" - "traefik.http.routers.portainer.rule=Host(`portainer.yourdomain.com`)" - "traefik.http.routers.portainer.entrypoints=web" - "traefik.http.services.portainer.loadbalancer.server.port=9000" - "traefik.http.routers.portainer.service=portainer" # Edge - "traefik.http.routers.edge.rule=Host(`edge.yourdomain.com`)" - "traefik.http.routers.edge.entrypoints=web" - "traefik.http.services.edge.loadbalancer.server.port=8000" - "traefik.http.routers.edge.service=edge" networks: public: external: true agent_network: external: true volumes: data: Copy version: '3.2' services: traefik: image: "traefik:latest" command: - --entrypoints.web.address=:80 - --entrypoints.websecure.address=:443 - --providers.docker=true - --providers.swarm=true - --providers.docker.exposedbydefault=false - --providers.docker.network=public - --api - --log.level=ERROR ports: - "80:80" - "443:443" networks: - public volumes: - "/var/run/docker.sock:/var/run/docker.sock:ro" agent: image: portainer/agent:sts environment: # REQUIRED: Should be equal to the service name prefixed by "tasks." when # deployed inside an overlay network AGENT_CLUSTER_ADDR: tasks.agent # AGENT_PORT: 9001 # LOG_LEVEL: debug volumes: - /var/run/docker.sock:/var/run/docker.sock - /var/lib/docker/volumes:/var/lib/docker/volumes networks: - agent_network deploy: mode: global placement: constraints: [node.platform.os == linux] portainer: image: portainer/portainer-ce:sts command: -H tcp://tasks.agent:9001 --tlsskipverify volumes: - data:/data networks: - public - agent_network deploy: mode: replicated replicas: 1 placement: constraints: [node.role == manager] labels: - "traefik.enable=true" - "traefik.http.routers.portainer.rule=Host(`portainer.yourdomain.com`)" - "traefik.http.routers.portainer.entrypoints=web" - "traefik.http.services.portainer.loadbalancer.server.port=9000" - "traefik.http.routers.portainer.service=portainer" # Edge - "traefik.http.routers.edge.rule=Host(`edge.yourdomain.com`)" - "traefik.http.routers.edge.entrypoints=web" - "traefik.http.services.edge.loadbalancer.server.port=8000" - "traefik.http.routers.edge.service=edge" networks: public: external: true agent_network: external: true volumes: data: Finally, customize these labels to match the URL that you want to use to access Portainer: Copy - "traefik.http.routers.frontend.rule=Host(`portainer.yourdomain.com`)" Copy - "traefik.http.routers.edge.rule=Host(`edge.yourdomain.com`)" You can now deploy Portainer by executing the following: Copy docker stack deploy portainer -c portainer.yml To check the deployment, run `docker service ls`. You should see an output similar to the following: Copy ID NAME MODE REPLICAS IMAGE PORTS lt21zrypsll6 portainer_agent global 1/1 portainer/agent:sts m6912ynwdcd7 portainer_portainer replicated 1/1 portainer/portainer-ee:sts tw2nb4i640e4 portainer_traefik replicated 1/1 traefik:latest *:80->80/tcp, *:443->443/tcp Once the services are running, you will able to access Portainer from the URL you defined earlier, for example: `portainer.yourdomain.com`. [PreviousUsing Portainer with reverse proxies](https://docs.portainer.io/sts/advanced/reverse-proxy) [NextDeploying Portainer behind nginx reverse proxy](https://docs.portainer.io/sts/advanced/reverse-proxy/nginx) Was this helpful? --- # Using mTLS with Portainer | 2.35 STS | Portainer Documentation Mutual TLS (or **mTLS**) is a certificate-based system whereby the client and server (in this case, the Portainer Edge Agent and the Portainer Server) authenticate each other cryptographically via a trusted source (a certificate authority). This can be used as an extra layer of security to protect the communications between the Edge Agent and Portainer. Under this setup, if a third-party system attempts to communicate with the Portainer Server and is not using a certificate signed by the certificate authority it will be rejected. This article will walk you through the process of deploying the Portainer Server and the Edge Agents with mTLS support. mTLS support is only available in Portainer Business Edition. [](https://docs.portainer.io/sts/advanced/mtls#requirements) Requirements ------------------------------------------------------------------------------ In order to configure Portainer with mTLS support, you will need the following: * A Portainer Server and a Portainer Edge Agent. * A certificate authority (CA). You can use your own corporate CA or a CA for which you completely control the certificate issuance policy. * The CA certificate for your certificate authority, in PEM format (`mtlsca.crt`). * A domain (or subdomain) you can point to your Portainer Server instance to be specifically used for mTLS. This will be the domain the server certificate is issued for. * A server certificate (`mtlsserver.crt`) and corresponding key (`mtlsserver.key`) issued by your CA for the Portainer Server, in PEM format. Ensure these are issued with `serverAuth` selected for `extendedKeyUsage`. This certificate should have the domain (or subdomain) that will be used for mTLS as the Subject Alternative Name (SAN). * A client certificate (`client.crt`) and corresponding key (`client.key`) issued by your CA for the Edge Agent, in PEM format. Ensure these are issued with `clientAuth` selected for `extendedKeyUsage`. [](https://docs.portainer.io/sts/advanced/mtls#configuring-the-portainer-server) Configuring the Portainer Server ---------------------------------------------------------------------------------------------------------------------- To use mTLS with your Edge Agents, the Portainer Server instance must be configured with mTLS support. This can either be done during the initial installation of the Portainer Server instance, or after installation through the [Edge Compute settings](https://docs.portainer.io/sts/admin/settings/edge#mtls-certificate) . ### [](https://docs.portainer.io/sts/advanced/mtls#configure-mtls-during-installation) Configure mTLS during installation When deploying your Portainer Server, you will need to make the CA certificate, server certificate and server key available to Portainer. How you do this will depend on your deployment. #### [](https://docs.portainer.io/sts/advanced/mtls#docker-standalone) Docker Standalone On your Docker host, upload your CA certificate (`mtlsca.crt`), server certificate (`mtlsserver.crt`) and server key (`mtlsserver.key`) into a directory that will be bind mounted into the Portainer container. In this example we assume your certificates are located at `/root/certs`. Modify your `docker run` command to mount the `/root/certs` directory to `/certs` and add the `--mtlscacert`, `--mtlscert`, and `--mtlskey` options: Copy docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always \ -v /var/run/docker.sock:/var/run/docker.sock \ -v portainer_data:/data \ -v /root/certs:/certs \ portainer/portainer-ee:sts \ --mtlscacert /certs/mtlsca.crt \ --mtlscert /certs/mtlsserver.crt \ --mtlskey /certs/mtlsserver.key This will start Portainer using your provided CA and certificates. #### [](https://docs.portainer.io/sts/advanced/mtls#docker-swarm) Docker Swarm To add mTLS certificates to Portainer Server on Docker Swarm during installation, we recommend adding the necessary files as secrets and then referencing those secrets within the YAML used to deploy Portainer. First, upload your CA certificate (`mtlsca.crt`), server certificate (`mtlsserver.crt`) and server key (`mtlsserver.key`) into a directory that will be referenced by the secret creation. In this example we assume your certificates are located at `/root/certs`. Once you have uploaded the files, create your secrets as follows: Copy docker secret create portainer.mtlscacert /root/certs/mtlsca.crt docker secret create portainer.mtlscert /root/certs/mtlsserver.crt docker secret create portainer.mtlskey /root/certs/mtlsserver.key Modify your Portainer YAML file to attach the secrets and add the `--mtlscacert`, `--mtlscert` and `--mtlskey` options: Copy portainer: image: portainer/portainer-ee:sts command: -H tcp://tasks.agent:9001 --tlsskipverify --mtlscacert /run/secrets/portainer.mtlscacert --mtlscert /run/secrets/portainer.mtlscert --mtlskey /run/secrets/portainer.mtlskey ports: - "9443:9443" - "9000:9000" - "8000:8000" volumes: - portainer_data:/data networks: - agent_network deploy: mode: replicated replicas: 1 placement: constraints: [node.role == manager] secrets: - portainer.mtlscacert - portainer.mtlsscert - portainer.mtlskey and to add the `secrets` definitions to include the secrets we just created: Copy secrets: portainer.mtlscacert: external: true portainer.mtlscert: external: true portainer.mtlskey: external: true #### [](https://docs.portainer.io/sts/advanced/mtls#kubernetes-via-helm) Kubernetes (via Helm) If it doesn't already exist, create the `portainer` namespace: Copy kubectl create namespace portainer Next, create a secret containing the CA, certificate and matching private key: Copy kubectl create secret generic portainer-mtls-certs-secret -n portainer \ --from-file=mtlsca.crt=ca.crt \ --from-file=mtlscert.crt=server.crt \ --from-file=mtlskey.key=server.key Replace `ca.crt`, `server.crt` and `server.key` in the above command with the paths to your CA certificate, certificate and matching key respectively. Install Portainer via Helm with the `mtls.existingSecret` parameter set to the name of the secret you just created: NodePort Load Balancer Copy helm install -n portainer portainer portainer/portainer \ --set mtls.existingSecret=portainer-mtls-certs-secret \ --set enterpriseEdition.enabled=true Copy helm install -n portainer portainer portainer/portainer \ --set mtls.existingSecret=portainer-mtls-secret \ --set service.type=LoadBalancer \ --set enterpriseEdition.enabled=true ### [](https://docs.portainer.io/sts/advanced/mtls#configure-mtls-post-installation) Configure mTLS post installation If you already have Portainer Server deployed, you can configure mTLS support through the Portainer UI. As an admin user, from the left menu select **Settings** then **Edge Compute**. Toggle on **Enable Edge Compute features** if it isn't already on and click **Save Settings**. Then scroll down to the **mTLS Certificate** section. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FtQIDyturKmBSy0OTVHyV%2F2.18-settings-edge-mtls.png&width=768&dpr=4&quality=100&sign=27ab2168&sv=2) Here you can enable the use of mTLS with the **Use separate mTLS cert** toggle, and upload the CA certificate, server certificate and server key using the buttons for **TLS CA certificate**, **TLS certificate** and **TLS key** respectively. If you add or change the mTLS CA certificate through this method you will need to restart the Portainer Server in order for the change to apply. You should also ensure any Edge Agents that are using mTLS are also updated to use the new CA certificate. [](https://docs.portainer.io/sts/advanced/mtls#deploying-the-edge-agents) Deploying the Edge Agents -------------------------------------------------------------------------------------------------------- Once you have the Portainer Server instance configured to use mTLS, you can then configure your Edge Agent deployments to use it as well. When deploying an Edge Agent you will be provided with a command to run by the Portainer UI. We will take that command and modify it for mTLS support. ### [](https://docs.portainer.io/sts/advanced/mtls#docker-standalone-1) Docker Standalone On your Docker host, upload your CA certificate (`mtlsca.crt`), client certificate (`client.crt`) and client key (`client.key`) into a directory that will be bind mounted into the Edge Agent container. In this example we assume your certificates are located at `/root/certs`. Once the certificates are in place and the secrets created, you can begin to set up your Edge Agent within the Portainer UI. When doing so, remember to use the domain (or subdomain) you chose for mTLS usage (and that the server certificate was issued for) as the Portainer API server URL and tunnel address (if appropriate). When you have completed the Edge Agent setup in the Portainer UI and have your deployment command, modify the command to mount the `/root/certs` directory to `/certs`, change the `EDGE_INSECURE_POLL` option to `0`, and add the `--mtlscacert`, `--mtlscert`, and `--mtlskey` options: Copy docker run -d \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /var/lib/docker/volumes:/var/lib/docker/volumes \ -v /:/host \ -v /root/certs:/certs \ -v portainer_agent_data:/data \ --restart always \ -e EDGE=1 \ -e EDGE_ID=your-edge-id \ -e EDGE_KEY=your-edge-key \ -e EDGE_INSECURE_POLL=0 \ --name portainer_edge_agent \ portainer/agent:sts \ --mtlscacert /certs/mtlsca.crt \ --mtlscert /certs/client.crt \ --mtlskey /certs/client.key Run the command to deploy your Edge Agent with mTLS support. ### [](https://docs.portainer.io/sts/advanced/mtls#docker-swarm-1) Docker Swarm To add mTLS certificates to the Edge Agent, we recommend adding the necessary files as secrets and then referencing those secrets within the YAML used to deploy Portainer. First, upload your CA certificate (`mtlsca.crt`), client certificate (`client.crt`) and client key (`client.key`) into a directory that will be referenced by the secret creation. In this example we assume your certificates are located at `/root/certs`. Once you have uploaded the files, create your secrets as follows: Copy docker secret create portainer.mtlscacert /root/certs/mtlsca.crt docker secret create portainer.mtlscert /root/certs/client.crt docker secret create portainer.mtlskey /root/certs/client.key Once the certificates are in place and the secrets created, you can begin to set up your Edge Agent within the Portainer UI. When doing so, remember to use the domain (or subdomain) you chose for mTLS usage (and that the server certificate was issued for) as the Portainer API server URL and tunnel address (if appropriate). When you have completed the Edge Agent setup in the Portainer UI and have your deployment command, modify the command to change the `EDGE_INSECURE_POLL` option to `0` and add the `--mtlscacert`, `--mtlscert` and `--mtlskey` options, using the secrets we defined above: Copy docker network create \ --driver overlay \ portainer_agent_network; docker service create \ --name portainer_edge_agent \ --network portainer_agent_network \ -e EDGE=1 \ -e EDGE_ID=your-edge-id \ -e EDGE_KEY=your-edge-key \ -e EDGE_INSECURE_POLL=0 \ -e AGENT_CLUSTER_ADDR=tasks.portainer_edge_agent \ --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 \ --mount type=bind,src=//,dst=/host \ --mount type=volume,src=portainer_agent_data,dst=/data \ portainer/agent:sts \ --mtlscacert /run/secrets/portainer.mtlscacert \ --mtlscert /run/secrets/portainer.mtlscert \ --mtlskey /run/secrets/portainer.mtlskey Run the commands to deploy your Edge Agent with mTLS support. ### [](https://docs.portainer.io/sts/advanced/mtls#kubernetes) Kubernetes At present, mTLS support for the Portainer Agent running on a Kubernetes environment is a work in progress. If you require instructions for deploying a Portainer Agent with mTLS on a Kubernetes environment, please [get in touch with our support team](https://docs.portainer.io/sts#getting-support) . [PreviousUsing your own SSL certificate with Portainer](https://docs.portainer.io/sts/advanced/ssl) [NextStream auth and activity logs to an external provider](https://docs.portainer.io/sts/advanced/siem) Was this helpful? --- # Accessing the Portainer API | 2.35 STS | Portainer Documentation To access the Portainer API, you will need a few things: * A user in Portainer * An access token for that user * The ability to make HTTPS requests to the Portainer server on port `9443` (or `9000` for legacy HTTP) [](https://docs.portainer.io/sts/api/access#creating-a-new-user) Creating a new user ----------------------------------------------------------------------------------------- API access is provided on a per-user basis, with each users' API access dependent on that user's permissions within Portainer. For example, if your user had access to only one environment, API calls for that user would also be restricted to that environment. To create a new user within Portainer, refer to our documentation: [Add a new user](https://docs.portainer.io/sts/admin/user/add) Once the user has been created, log in to Portainer as that user to create an API access token. [](https://docs.portainer.io/sts/api/access#creating-an-access-token) Creating an access token --------------------------------------------------------------------------------------------------- Once the user has been created, you can add an access token to that user. The access token will provide the same level of access to Portainer functionality as would be available to that user had they logged into the Portainer UI. Once logged in as the user, click on your username in the top right and then select **My account**. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F9O41624JYTyj6ReRwqy8%2F2.20-api-access-myaccount.gif&width=768&dpr=4&quality=100&sign=b4804284&sv=2) Scroll down to the **Access tokens** section. Here you can see any access tokens that exist for the user. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2FTR5mfP2jmx5ESKX8jZja%2F2.15-accountsettings-apitokens.png&width=768&dpr=4&quality=100&sign=369cd2c&sv=2) To add a new access token, click the **Add access token** button. You will be taken to a new page where you can set a **Description** for your access token. We recommend making this something recognizable for future reference. For security we require you to re-enter your password when creating an access token. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F4oK8EbrisHAv0G0s3uNW%2F2.20-api-access-createtoken.png&width=768&dpr=4&quality=100&sign=2d7df63d&sv=2) Once you have provided a description, click the **Add access token** button to generate your access token. Your new access token will now be displayed. Please copy the access token and keep it in a safe place, as you will not be able to view the token again after creation. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FoeG1zgfd7OQLVZtVK5LC%2Fblobs%2F6NMjMZaXBbYNresrTKqG%2F2.20-api-access-createdtoken.png&width=768&dpr=4&quality=100&sign=65e1a64d&sv=2) When you have copied the access token, click the **Done** button to return to the User settings page. Your access token is ready to use. [](https://docs.portainer.io/sts/api/access#using-your-access-token) Using your access token ------------------------------------------------------------------------------------------------- Now that you have created a user and access token, you are ready to access the API. The Portainer API follows the RESTful architecture, accepting `GET` / `POST` / `PUT` / `DELETE` requests and responding with JSON objects. The following examples use [httpie](https://httpie.org/) to execute API calls against Portainer. Feel free to replace this with your method of choice. To make an API request, you will need to include your access token in the `X-API-Key` header to authenticate your request. For example, you can use the `/stacks` endpoint to list the stacks you have access to: Copy http GET https://portainer-url:9443/api/stacks X-API-Key:your_api_key_here This will return a JSON object listing your stacks: Copy [\ {\ "AdditionalFiles": null,\ "AutoUpdate": null,\ "CreatedBy": "admin",\ "CreationDate": 1631852794,\ "EndpointId": 4,\ "EntryPoint": "docker-compose.yml",\ "Env": null,\ "GitConfig": {\ "Authentication": null,\ "ConfigFilePath": "docker-compose.yml",\ "ConfigHash": "2e71920bf1ee1bbac976d320f8f274411fba3bad",\ "ReferenceName": "refs/heads/master",\ "URL": "https://github.com/mygithubaccount/wordpress-stack"\ },\ "Id": 5,\ "IsComposeFormat": true,\ "Name": "",\ "Namespace": "my-namespace",\ "ProjectPath": "/data/compose/5",\ "ResourceControl": null,\ "Status": 1,\ "SwarmId": "",\ "Type": 3,\ "UpdateDate": 0,\ "UpdatedBy": ""\ },\ ] If a user tries to access an area they do not have permission to access, an error message will be returned. For example, assume that a non-administrator user attempted to access the `/settings` endpoint, which requires administrator access: Copy http GET https://portainer:9443/api/settings X-API-Key:your_api_key_here The user would be presented with the following response: Copy { "details": "Unauthorized", "message": "Access denied" } Now that you have access to the Portainer API, you can learn more about how to use it from the [API documentation](https://docs.portainer.io/sts/api/docs) and our [usage examples](https://docs.portainer.io/sts/api/examples) . [PreviousDeprecated and removed features](https://docs.portainer.io/sts/advanced/deprecated) [NextAPI documentation](https://docs.portainer.io/sts/api/docs) Was this helpful? --- # Encrypting the Portainer database | 2.35 STS | Portainer Documentation Portainer uses a BoltDB database to store the configuration, kept in the `portainer_data` volume created during installation. This database can be encrypted for additional security through the use of a secret provided when the Portainer Server is started. Encryption can be added during the initial installation or at a later date. At present, encryption of the database is not reversible. [](https://docs.portainer.io/sts/advanced/db-encryption#docker-standalone) Docker Standalone ------------------------------------------------------------------------------------------------- To enable encryption on Docker Standalone, you will first need to create a secret key, then modify your docker run command to mount the secret in the container. ### [](https://docs.portainer.io/sts/advanced/db-encryption#create-a-secret) Create a secret Create a text file on the system running Docker Standalone that is accessible to the Docker executable, yet somewhere secure. For this example, we'll assume the file is called `/root/secrets/portainer`. In this file enter a secret. This will be the key used to encrypt the Portainer database. ### [](https://docs.portainer.io/sts/advanced/db-encryption#mount-the-secret) Mount the secret If Portainer is already running, you will need to stop and remove the Portainer container before continuing: Copy docker stop portainer docker rm portainer To encrypt the database, add a bind mount to the `docker run` command that mounts your secret in `/run/secrets/portainer`: Copy -v /root/secrets/portainer:/run/secrets/portainer Your final `docker run` command may look like this: Copy docker run -d -p 8000:8000 -p 9443:9443 --name portainer \ --restart=always \ -v /var/run/docker.sock:/var/run/docker.sock \ -v portainer_data:/data \ -v /root/secrets/portainer:/run/secrets/portainer \ portainer/portainer-ee:sts When the Portainer container starts, it will encrypt any existing database, or for a fresh install will create a new encrypted database as part of the install process. [](https://docs.portainer.io/sts/advanced/db-encryption#docker-swarm) Docker Swarm --------------------------------------------------------------------------------------- To enable encryption on Docker Swarm, you will first need to create a secret. You will then either update the service to incorporate the new secret (if you have an existing Portainer installation) or edit the compose file used to create the stack to include the secret (if this is a fresh installation of Portainer). ### [](https://docs.portainer.io/sts/advanced/db-encryption#create-a-secret-1) Create a secret On a manager node, you can run the following command to create a secret: Copy echo "This is a secret" | docker secret create portainer - Replace `This is a secret` with your secret. This will create a secret named `portainer`, which will be the key used to encrypt the Portainer database. You can also create a secret in Portainer if you are adding encryption to an existing installation. ### [](https://docs.portainer.io/sts/advanced/db-encryption#existing-installations-update-the-service) Existing installations: Update the service To add encryption to an existing Portainer deployment on Docker Swarm, you can use the following command on a manager node: Copy docker service update \ --secret-add src=portainer,target="/run/secrets/portainer" \ portainer The service will add the new secret and encrypt the database. ### [](https://docs.portainer.io/sts/advanced/db-encryption#new-installations-edit-the-compose-file) New installations: Edit the compose file To install Portainer on Docker Swarm with encryption, you will need to edit the compose file you downloaded as part of the installation process. Add a secrets section to the `portainer` service definition: Copy secrets: - portainer This tells the service to use the `portainer` secret created earlier. In addition, because we created it separately earlier we will need to specify it as `external` so that Docker knows not to create it when creating the stack. To do this we add a `secrets:` definition outside of the `services:` definition for the `portainer` secret: Copy secrets: portainer: external: true With the secret added, your full Portainer stack file may look like this: Copy version: '3.2' services: agent: image: portainer/agent:sts volumes: - /var/run/docker.sock:/var/run/docker.sock - /var/lib/docker/volumes:/var/lib/docker/volumes networks: - agent_network deploy: mode: global placement: constraints: [node.platform.os == linux] portainer: image: portainer/portainer-ee:sts command: -H tcp://tasks.agent:9001 --tlsskipverify ports: - "9443:9443" - "9000:9000" - "8000:8000" volumes: - portainer_data:/data networks: - agent_network deploy: mode: replicated replicas: 1 placement: constraints: [node.role == manager] secrets: - portainer networks: agent_network: driver: overlay attachable: true volumes: portainer_data: secrets: portainer: external: true Save your changes, then use the compose file to deploy your Portainer installation as covered in the Swarm installation instructions. The database will be deployed encrypted as part of the installation process. [](https://docs.portainer.io/sts/advanced/db-encryption#kubernetes) Kubernetes ----------------------------------------------------------------------------------- To enable encryption on Kubernetes you will first need to create a secret. You will then mount this secret as a volume in Portainer. ### [](https://docs.portainer.io/sts/advanced/db-encryption#create-a-secret-2) Create a secret From the command line on your Kubernetes cluster, you can run the following command to create your secret: Copy kubectl create secret generic portainer-key --from-literal=secret=IAmASecretKey --namespace portainer Replace `IAmASecretKey` with your secret. This will create a secret named `portainer-key`, which will be the key used to encrypt the Portainer database. ### [](https://docs.portainer.io/sts/advanced/db-encryption#modify-the-yaml-file) Modify the YAML file Once the secret has been created, we need to modify the YAML file to mount the secret as a volume in Portainer. Download the YAML file for your particular deployment and locate the `container` definition for the `portainer` container. It should look something like this: Copy containers: - name: portainer image: "portainer/portainer-ee:sts" imagePullPolicy: Always args: volumeMounts: - name: data mountPath: /data In the `volumeMounts` section, add a definition for the secret created earlier: Copy volumeMounts: - name: data mountPath: /data - name: portainer-key mountPath: /run/secrets/portainer subPath: portainer We also need to add a definition to the `volumes` definition for the `spec`: Copy spec: containers: portainer: ... volumes: - name: portainer-key secret: secretName: portainer-key items: - key: secret path: portainer Save the file, then apply it to your running configuration: Copy kubectl apply -f portainer.yaml Replace `portainer.yaml` with the name of your modified YAML file. [PreviousSecurity and compliance](https://docs.portainer.io/sts/advanced/security) [NextUsing your own SSL certificate with Portainer](https://docs.portainer.io/sts/advanced/ssl) Was this helpful? --- # API documentation | 2.35 STS | Portainer Documentation Portainer exposes an HTTP API that you can use to automate everything you do via the Portainer UI. You can also use Portainer as a gateway (HTTP queries against the Portainer API) to the underlying Docker/Kubernetes API. You will need an access token in order to use the Portainer API. If you have not already set up an access token for the API, we have [instructions on how to do so](https://docs.portainer.io/sts/api/access) . You can find our API documentation at SwaggerHub: * [Business Edition (BE) 2.35.0 API Documentation](https://app.swaggerhub.com/apis/portainer/portainer-ee/2.35.0) * [Community Edition (CE) 2.35.0 API Documentation](https://app.swaggerhub.com/apis/portainer/portainer-ce/2.35.0) We have also provided some examples of API usage. [API usage examples](https://docs.portainer.io/sts/api/examples) [PreviousAccessing the Portainer API](https://docs.portainer.io/sts/api/access) [NextAPI usage examples](https://docs.portainer.io/sts/api/examples) Last updated 1 month ago Was this helpful? --- # How Relative Path Support works in Portainer | 2.35 STS | Portainer Documentation The relative path volumes support in Portainer Business Edition is intended to provide you with a way to reference files and directories that are supplied within the Git repository alongside your compose file without needing to know the absolute path at which they will appear when they are deployed to your environment. Relative path support is only present in Portainer Business Edition, and needs to be [enabled when deploying your stack from Git](https://docs.portainer.io/sts/user/docker/stacks/add#relative-path-volumes) for this article to apply. In the background the way this works is as follows: 1. In Portainer, a stack deployment is initiated where the stack is located in a Git repository, **Enable relative path volumes** is selected and a **Local (or Network) filesystem path** is specified. 2. Portainer creates a temporary unpacker container that bind mounts the path specified in the Local (or Network) filesystem path field. 3. The unpacker container clones the Git repository to a subdirectory under the bind mounted path. 4. Portainer creates the stack using the compose file provided, specifying the working directory as where the specified compose file is located within where the Git repo was cloned. 5. Now that the stack has been deployed, the temporary unpacker container is removed. To take advantage of this with your compose file, you can specify any references to files that are within your repository in a _relative_ manner to your compose file. For example, imagine this simple nginx deployment: Copy . ├── docker-compose.yml └── static └── index.html In this example, the `docker-compose.yml` file is at the base directory of the repository. Alongside it there is a directory named `static`, and within that directory is an `index.html` file. The `docker-compose.yml` file looks like this: Copy version: '3.1' services: webapp: image: nginx:latest restart: always ports: - "3002:80" volumes: - ./static:/usr/share/nginx/html The last line is the important one here - you'll note that we're referencing the static directory with a leading `.` and `/` - this tells compose that the path specified is _relative_ to the working directory, which Portainer specified during deployment. If we excluded the leading `.` this would be an _absolute_ path, and would refer to `/static` at the root of the host filesystem. Let's look at an example where you had your compose file in a subdirectory of your repository, and your content in a different subdirectory: Copy . ├── nginx │ └── docker-compose.yml └── static └── index.html In this scenario, you would specify the compose file when deploying as `nginx/docker-compose.yml`. Portainer will pull the contents of the repository to the specified location and set the working directory to the location of the compose file (ie, within the `nginx` subdirectory). As such, relative references within the compose need to be aware of this. To mount the contents of the `static` directory, your compose file would look like: Copy version: '3.1' services: webapp: image: nginx:latest restart: always ports: - "3002:80" volumes: - ../static:/usr/share/nginx/html The double dots (`..`) indicate that the files are at a directory level above the working directory. ### [](https://docs.portainer.io/sts/advanced/relative-paths#a-note-about-the-local-or-network-filesystem-path) A note about the local (or network) filesystem path The path on the local (or network) filesystem that the Git repository is cloned to will be in: Copy portainer-compose-unpacker/stacks/yourstackname/ For example, if you deployed a stack named `nginx` and specified the local filesystem path as: Copy /mnt/stacks/ it would result in: Copy /mnt/stacks/portainer-compose-unpacker/stacks/nginx/ This is generally not relevant for relative path referencing as the definition of the working directory avoids needing to be aware of this full path, but it does mean the same local (or network) filesystem path can be used to deploy multiple stacks without worrying about collisions (as long as they don't share the same stack name). This path is where your stack's mounted files will be sourced from, so you will want to ensure this path remains intact and unchanged. When a stack deployed with this method is removed, the file and directory structure for that stack are removed as well. [PreviousDeploying Portainer behind nginx reverse proxy](https://docs.portainer.io/sts/advanced/reverse-proxy/nginx) [NextHelm chart configuration options](https://docs.portainer.io/sts/advanced/helm-chart-configuration-options) Was this helpful? --- # Set up a macOS build environment | 2.35 STS | Portainer Documentation As an open source product, we encourage users to edit our code and submit patches to it. This article explains how to set up a local environment on Mac so you can build your own copy of Portainer and test your changes. We tested these instructions on macOS 10.14.3 (Mojave). [](https://docs.portainer.io/sts/contribute/build/mac#dependencies) Dependencies ------------------------------------------------------------------------------------- * [Docker for Mac](https://www.docker.com/products/docker-desktop) installs the Docker application and other Docker tools. The latest version is not a requirement for this development stack, however we recommend staying up to date with the latest improvements and security fixes. * [Yarn](https://yarnpkg.com/en/docs/install#mac-stable) is a package manager for installing new software packages on your system, and is used to run the Portainer development environment. * [Node.JS](https://nodejs.org/en/download/) is a JavaScript package used when building applications that leverage networking, such as Portainer. Version 18 or later is required. * ​[Golang](https://golang.org/dl/) is the open source language that we use to build the majority of Portainer software. Version 1.18 of Golang is required. * Wget is a package used to retrieve files using common internet protocols such as HTTP and FTP. [](https://docs.portainer.io/sts/contribute/build/mac#part-1-installing-docker-for-macos) Part 1: Installing Docker for macOS ---------------------------------------------------------------------------------------------------------------------------------- Docker for macOS requires OSX Mountain Lion or later or it will not work. Please check that you have the right version before you begin. ### [](https://docs.portainer.io/sts/contribute/build/mac#step-1-install-docker) Step 1: Install Docker We always recommend installing software using the most up-to-date instructions from the official vendor. This step is based on Docker's own [installation instructions for Docker on macOS](https://runnable.com/docker/install-docker-on-macos) . [Download Docker](https://www.docker.com/products/docker-desktop) then navigate to the `Docker.dmg` file and double-click to open. Drag and drop Docker into your applications folder. Authorize the installation using your system password then wait for Docker to finish installing. To check that Docker installed successfully, double-click Docker inside your applications folder to start it. The whale icon should appear in your status bar, indicating Docker is running and accessible. ### [](https://docs.portainer.io/sts/contribute/build/mac#step-2-check-the-installed-docker-version) Step 2: Check the installed Docker version Click the Docker icon in the status bar then select **About Docker Desktop** from the menu (or a similarly named menu item, depending on your Docker version). A window should open, displaying the current version of Docker and its supporting software. [](https://docs.portainer.io/sts/contribute/build/mac#part-2-installing-yarn) Part 2: Installing Yarn ---------------------------------------------------------------------------------------------------------- This procedure uses the Homebrew package manager. Go [here](https://brew.sh/) to learn how install it. If you don't want to use Homebrew, Yarn provides [some alternatives](https://yarnpkg.com/en/docs/install#mac-stable) . If you have issues installing or using Yarn, read their [official documentation](https://yarnpkg.com/en/docs/install#mac-stable) . Running `brew install yarn` in the macOS terminal will install Yarn. To confirm it installed successfully, run `yarn --version` in the macOS terminal. If successful, the current version of Yarn should print out in your terminal, indicating that it installed successfully and is running on your system. [](https://docs.portainer.io/sts/contribute/build/mac#part-3-installing-or-updating-node.js) Part 3: Installing or updating Node.JS ---------------------------------------------------------------------------------------------------------------------------------------- If you used Homebrew to install Yarn, Node.JS should have automatically installed alongside it. If not, you can install it by following the [Node.JS documentation](https://nodejs.org/en/download/) . If you have issues installing or updating Node.JS using Homebrew, read [Homebrew's troubleshooting guide](https://docs.brew.sh/Common-Issues) . To check if Node.JS is installed on your system, run `node --version` in your terminal. The current version of Node.JS should print out. If the version is version 6 or later, updating it to the latest version is optional (but we recommend it because it's good practice to stay up to date). If you are running a version of Node.JS that is older than version 6, you must upgrade in order to run the Portainer development environment. If Homebrew was installed at the same time as Yarn (using Homebrew), follow these steps to update Node.JS: [PreviousBuild instructions](https://docs.portainer.io/sts/contribute/build) [NextSet up a Linux build environment](https://docs.portainer.io/sts/contribute/build/linux) Was this helpful? --- # Contribute | 2.35 STS | Portainer Documentation We value contributions from the Portainer community and encourage developers to propose fixes, improvements, and new ideas. The following guidelines outline our engineering workflows, please review these before making a contribution to ensure any changes can be integrated smoothly. [](https://docs.portainer.io/sts/contribute/contribute#contributing-to-the-portainer-ce-codebase) Contributing to the Portainer CE codebase ------------------------------------------------------------------------------------------------------------------------------------------------ The Portainer CE codebase is available in [GitHub](https://github.com/portainer/portainer) . Please follow our [build instructions](https://docs.portainer.io/sts/contribute/build) and the following guidelines when making a contribution. ### [](https://docs.portainer.io/sts/contribute/contribute#repository-structure) Repository structure * Our main development occurs in private repositories, which are mirrored to public GitHub repos (e.g. [portainer/portainer](https://github.com/portainer/portainer/) ). * The `develop` and `release/*` branches in public repositories are **read-only**: merges into these branches are blocked to preserve synchronization with our internal repositories. * We maintain a separate `community` branch in each public repository to accept and review external contributions. ### [](https://docs.portainer.io/sts/contribute/contribute#contribution-process) Contribution process 1. **Fork the repository** * Create your own fork of the relevant Portainer public repository. 2. **Create a feature branch** * Base your changes on the current `develop` branch (not `main`, `release/*`, or `community`). This ensures you are working off the latest version of the codebase. 3. **Submit a Pull Request (PR)** * Open your PR against the `develop` branch. * Portainer engineers will update the target branch to `community` when the contribution is ready to be merged. 4. **Review and feedback** * Contributions will be reviewed by Portainer engineers. * We may request changes to align with coding standards, tests, or design decisions. * In some cases, we may adapt or refactor a contribution before merging. 5. **Integration** * Once approved and merged into `community`, Portainer engineers will cherry-pick contributions into the upstream private repository. * These changes will then flow into `develop` and subsequent releases through our normal sync process. * Not all contributions will be integrated upstream. Decisions will be based on roadmap alignment, technical fit, and quality. ### [](https://docs.portainer.io/sts/contribute/contribute#contribution-expectations) Contribution expectations * **Coding standards**: Please follow existing project style and conventions. * **Tests**: Include tests where applicable. Contributions without tests may be delayed. * **Documentation**: Update relevant docs (e.g. README, usage notes) when changing functionality. * **Scope**: Focus on well-defined features, fixes, or improvements. Large architectural changes should be discussed in an issue first. ### [](https://docs.portainer.io/sts/contribute/contribute#communication) Communication * For significant changes or new features, use [GitHub Discussions](https://github.com/orgs/portainer/discussions/categories/ideas) to start a discussion before starting the change. * PR discussions are the best place for clarifications on specific contributions. [](https://docs.portainer.io/sts/contribute/contribute#reporting-bugs) Reporting bugs ------------------------------------------------------------------------------------------ If you find a bug, [please tell us](https://github.com/portainer/portainer/issues/new?assignees=&labels=bug%2Fneed-confirmation%2C+kind%2Fbug&template=Bug_report.md&title=) so we can triage it. All bugs are managed in the [GitHub issues repo](https://github.com/portainer/portainer/issues) . When you click through, our template makes it easy to record all of the details. Check the list of [open bugs](https://github.com/portainer/portainer/labels/kind%2Fbug) before reporting to avoid duplicates. [This article](https://docs.portainer.io/sts/faqs/contributing/how-do-you-decide-which-bugs-and-features-to-work-on-first) covers how we prioritize bug fixes. [](https://docs.portainer.io/sts/contribute/contribute#feature-requests) Feature requests ---------------------------------------------------------------------------------------------- You can request new features by posting an Idea in our [GitHub Discussions](https://github.com/orgs/portainer/discussions/categories/ideas) forum. Please check to see if someone has already requested the feature you want, and give it an upvote if so. Learn how we prioritize feature development [in this article](https://docs.portainer.io/sts/faqs/contributing/how-do-you-decide-which-bugs-and-features-to-work-on-first) . [PreviousAPI usage examples](https://docs.portainer.io/sts/api/examples) [NextBuild instructions](https://docs.portainer.io/sts/contribute/build) Was this helpful? --- # Deploying Portainer behind nginx reverse proxy | 2.35 STS | Portainer Documentation [](https://docs.portainer.io/sts/advanced/reverse-proxy/nginx#deploying-in-a-docker-standalone-scenario) Deploying in a Docker Standalone scenario ------------------------------------------------------------------------------------------------------------------------------------------------------- To deploy Portainer behind an nginx proxy in a Docker standalone scenario you must use a Docker Compose file. In the following docker-compose.yml you will find the configuration of the nginx proxy and the Portainer Server. This example uses the excellent [nginxproxy/nginx-proxy](https://hub.docker.com/r/nginxproxy/nginx-proxy) image as the proxy container, which requires no additional configuration beyond the two environment variables added to the `portainer` container's definition. Business Edition Community Edition Copy version: "2" services: nginx-proxy: image: nginxproxy/nginx-proxy restart: always ports: - "80:80" volumes: - "/var/run/docker.sock:/tmp/docker.sock:ro" portainer: image: portainer/portainer-ee:sts command: -H unix:///var/run/docker.sock restart: always environment: - VIRTUAL_HOST=portainer.yourdomain.com - VIRTUAL_PORT=9000 ports: - 8000:8000 volumes: - /var/run/docker.sock:/var/run/docker.sock - portainer_data:/data volumes: portainer_data: Copy version: "2" services: nginx-proxy: image: nginxproxy/nginx-proxy restart: always ports: - "80:80" volumes: - "/var/run/docker.sock:/tmp/docker.sock:ro" portainer: image: portainer/portainer-ce:sts command: -H unix:///var/run/docker.sock restart: always environment: - VIRTUAL_HOST=portainer.yourdomain.com - VIRTUAL_PORT=9000 ports: - 8000:8000 volumes: - /var/run/docker.sock:/var/run/docker.sock - portainer_data:/data volumes: portainer_data: To start working with this recipe, change the `VIRTUAL_HOST` value then deploy Portainer by running the following: Copy docker-compose up -d When this has finished, run `docker ps` . You should see an output similar to this: Copy CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 8c8f2eac7c9a portainer/portainer-ee:sts "/portainer -H unix:…" 4 minutes ago Up 4 minutes 9000/tcp, 0.0.0.0:8000->8000/tcp, :::8000->8000/tcp, 9443/tcp portainer_portainer_1 3e7c8b5d71d7 nginxproxy/nginx-proxy "/app/docker-entrypo…" 4 minutes ago Up 4 minutes 0.0.0.0:80->80/tcp, :::80->80/tcp portainer_nginx-proxy_1 Once the deployment has finished you can browse `portainer.yourdomain.com`. [](https://docs.portainer.io/sts/advanced/reverse-proxy/nginx#deploying-in-a-docker-swarm-scenario) Deploying in a Docker Swarm scenario --------------------------------------------------------------------------------------------------------------------------------------------- Deploying Portainer in Docker Swarm behind nginx has similar steps to the Docker Standalone scenario. Before deploying, you need to create two elements: networks and volumes. This deployment assumes you are running one manager node. If you are using multiple managers we advise [reading this article](https://docs.portainer.io/sts/faqs/installing/how-can-i-ensure-portainers-configuration-is-retained) before proceeding. First, create two networks: * One for the agent and the communication with the Portainer Server. * One to 'expose' the Portainer container to the same network as the reverse proxy. Copy docker network create -d overlay proxy Copy docker network create -d overlay agent_network Next, create the volume: Copy docker volume create portainer_data And finally, save the following recipe as `portainer.yml`: Business Edition Community Edition Copy version: '3.2' services: nginx-proxy: image: nginxproxy/nginx-proxy networks: - proxy ports: - "80:80" volumes: - "/var/run/docker.sock:/tmp/docker.sock:ro" - "./vhost.d:/etc/nginx/vhost.d:ro" agent: image: portainer/agent:sts environment: # REQUIRED: Should be equal to the service name prefixed by "tasks." when # deployed inside an overlay network AGENT_CLUSTER_ADDR: tasks.agent # AGENT_PORT: 9001 # LOG_LEVEL: DEBUG volumes: - /var/run/docker.sock:/var/run/docker.sock - /var/lib/docker/volumes:/var/lib/docker/volumes networks: - agent_network deploy: mode: global placement: constraints: [node.platform.os == linux] portainer: image: portainer/portainer-ee:sts command: -H tcp://tasks.agent:9001 --tlsskipverify volumes: - data:/data environment: - VIRTUAL_HOST=portainer.yourdomain.com - VIRTUAL_PORT=9000 ports: - 8000:8000 networks: - proxy - agent_network deploy: mode: replicated replicas: 1 placement: constraints: [node.role == manager] networks: proxy: external: true agent_network: external: true volumes: data: Copy version: '3.2' services: nginx-proxy: image: nginxproxy/nginx-proxy networks: - proxy ports: - "80:80" volumes: - "/var/run/docker.sock:/tmp/docker.sock:ro" - "./vhost.d:/etc/nginx/vhost.d:ro" agent: image: portainer/agent:sts environment: # REQUIRED: Should be equal to the service name prefixed by "tasks." when # deployed inside an overlay network AGENT_CLUSTER_ADDR: tasks.agent # AGENT_PORT: 9001 # LOG_LEVEL: DEBUG volumes: - /var/run/docker.sock:/var/run/docker.sock - /var/lib/docker/volumes:/var/lib/docker/volumes networks: - agent_network deploy: mode: global placement: constraints: [node.platform.os == linux] portainer: image: portainer/portainer-ce:sts command: -H tcp://tasks.agent:9001 --tlsskipverify volumes: - data:/data environment: - VIRTUAL_HOST=portainer.yourdomain.com - VIRTUAL_PORT=9000 ports: - 8000:8000 networks: - proxy - agent_network deploy: mode: replicated replicas: 1 placement: constraints: [node.role == manager] networks: proxy: external: true agent_network: external: true volumes: data: To start working with this recipe, change the `VIRTUAL_HOST` value then deploy Portainer by running the following: Copy docker stack deploy portainer -c portainer.yml To check the deployment, run `docker service ls`. You should see an output similar to the following: Copy ID NAME MODE REPLICAS IMAGE PORTS gy2bjxid0g4p portainer_agent global 1/1 portainer/agent:sts jwvjp5bux4sz portainer_nginx-proxy replicated 1/1 nginxproxy/nginx-proxy:latest *:80->80/tcp 5nflcvoxl3c7 portainer_portainer replicated 1/1 portainer/portainer-ee:sts *:8000->8000/tcp Once the services are running, you will be able to access Portainer from the URL you defined earlier, for example: `portainer.yourdomain.com`. [PreviousDeploying Portainer behind Traefik Proxy](https://docs.portainer.io/sts/advanced/reverse-proxy/traefik) [NextHow Relative Path Support works in Portainer](https://docs.portainer.io/sts/advanced/relative-paths) Was this helpful? --- # Deprecated and removed features | Portainer Documentation This table lists deprecated and removed features and functionality that are no longer supported and should not be used. The **Deprecated** column shows the release in which the feature was tagged as deprecated. The **Remove** column shows the release in which the feature was or will be removed (TBD means 'to be decided'). Feature Deprecated Remove `--sslcert` and `--sslkey` options (use `--tlscert` and `--tlskey` instead) 2.33.2 TBD Experimental OpenAI integration 2.32.0 2.33.0 Published Portainer images being built using the Docker manifest list format in favor of the OCI image index format 2.31.0 TBD [Provision KaaS Cluster](https://docs.portainer.io/admin/environments/add/kaas) feature 2.30.0 TBD [Create a MicroK8s cluster](https://docs.portainer.io/admin/environments/add/kube-create/microk8s) feature 2.30.0 TBD `PUT /kubernetes/{id}/namespaces` API endpoint 2.25.0 TBD Nomad support 2.20.0 2.20.0 `POST /stacks` endpoint (use `/stacks/create/standalone`, `/stacks/create/swarm`, `/stacks/create/kubernetes` etc instead) 2.20.0 2.27.0 Enabling SSL via `--ssl` (now enabled by default) 2.9.0 TBD Disabling analytics via `--no-analytics` 2.0 TBD Kompose deployments 2.15.0 2.17.0 Specifying external environments in JSON via `--external-endpoints` 2.0 Setting time between environment synchronization requests via `--sync-interval` 2.0 Disabling Portainer internal authentication via `--no-auth` 2.0 Specifying a templates file to load on first run via `--templates-file` 2.0 Preventing Portainer from running a snapshot of environments via `--no-snapshot` 2.0 [PreviousKubernetes roles and bindings](https://docs.portainer.io/advanced/kubernetes-roles-and-bindings) [NextAccessing the Portainer API](https://docs.portainer.io/api/access) Last updated 1 month ago Was this helpful? --- # Helm chart configuration options | 2.35 STS | Portainer Documentation The following table lists the configurable parameters of the Portainer Helm chart and their default values. Find the values file under `deploy/helm/portainer/values.yaml`. Parameter Description Default `replicaCount` Number of Portainer service replicas (always set to 1). `1` `image.repository` Portainer Docker Hub repository. `portainer/portainer-ce` `image.tag` Tag for the Portainer image. `latest` `image.pullPolicy` Portainer image-pulling policy. `IfNotPresent` `imagePullSecrets` If the Portainer image needs to be in a private repository. `nil` `nodeSelector` Used to apply a nodeSelector to the deployment. `{}` `serviceAccount.annotations` Annotations to add to the service account. `null` `serviceAccount.name` The name of the service account to use. `portainer-sa-clusteradmin` `service.type` Service type for the main Portainer Service. Valid values: `ClusterIP`, `NodePort`, `LoadBalancer`. `LoadBalancer` `service.httpPort` HTTP port for accessing the Portainer web interface. `9000` `service.httpNodePort` Static NodePort for accessing the Portainer web interface. Specify only if the type is `NodePort`. `30777` `service.edgePort` TCP port for accessing Portainer Edge. `8000` `service.edgeNodePort` Static NodePort for accessing Portainer Edge. Specify only if the type is `NodePort`. `30776` `service.annotations` Annotations to add to the service. `{}` `ingress.enabled` Creates an ingress for Portainer. `false` `ingress.annotations` Annotations to add to the ingress. For example: `kubernetes.io/ingress.class: nginx` `{}` `ingress.hosts.host` URL for Portainer Web. For example, `portainer.example.io`. `nil` `ingress.hosts.paths.path` Path for the Portainer web interface. `/` `ingress.hosts.paths.port` Port for the Portainer web interface. `9000` `ingress.tls` TLS support on ingress. Must create a secret with TLS certificates in advance. `[]` `resources` Portainer resource requests and limits. `{}` `persistence.enabled` Whether or not to enable data persistence. `true` `persistence.existingClaim` Name of an existing PVC to use for data persistence. `nil` `persistence.size` Size of the PVC used for persistence. `10Gi` `persistence.annotations` Annotations to apply to PVC used for persistence. `{}` `persistence.storageClass` StorageClass to apply to PVC used for persistence. `default` `persistence.accessMode` AccessMode for persistence. `ReadWriteOnce` `persistence.selector` Selector for persistence. `nil` [PreviousHow Relative Path Support works in Portainer](https://docs.portainer.io/sts/advanced/relative-paths) [NextDocker roles and permissions](https://docs.portainer.io/sts/advanced/docker-roles-and-permissions) Was this helpful? --- # The Portainer Edge Agent | Portainer Documentation [](https://docs.portainer.io/advanced/edge-agent#the-back-story) The back story ------------------------------------------------------------------------------------ For standard deployments, we used to assume that the Portainer instance and any environments shared the same network and could communicate seamlessly. If remote environments were on a different network (say, across the Internet) we could not manage them. Then we changed the Edge agent architecture so only the environments need to access Portainer. There is now no need to expose the Portainer agents to the Internet. Portainer now requires that only the `9443` and `8000` TCP ports are exposed. We used to serve the UI and the Portainer API from port `9000`, but we extended the API to allow the remote agents to poll for instructions. Port `8000` is a TLS tunnel server used to create a secure tunnel between the agent and the Portainer instance. More about that soon. If your Portainer instance is deployed with TLS, the agent will use HTTPS for the connection it makes back to Portainer. However, if your Portainer instance uses a self-signed certificate, the Edge Agent must be deployed with the `-e EDGE_INSECURE_POLL=1` flag. If you do not deploy the Edge Agent with this flag, the agent won't be able to communicate with the Portainer instance. [](https://docs.portainer.io/advanced/edge-agent#creating-an-edge-agent-in-portainer) Creating an Edge Agent in Portainer ------------------------------------------------------------------------------------------------------------------------------ When you create an Edge Agent, you are first asked for a human-friendly endpoint name. You are then asked to confirm the FQDN:PORT of your Portainer instance. This is what agents will use to connect, so make sure it’s correct and that the DNS resolves. During the creation process, an Edge ID is dynamically generated. This is a random UUID which is assigned to each environment. You can see it in the command syntax which is provided during the setup process. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2F2oWyHKlCMIJ281cw4DtV%2F2.15-advanced-edgeagent-command.png&width=768&dpr=4&quality=100&sign=32587783&sv=2) The Edge ID and the join token are unique per environment. The join token (`EDGE_KEY`) is made up of the following base64 encoded data separated by the pipe (`|`) character: * The Portainer instance API URL. This is how the Edge Agent knows how to ‘call home’ to your Portainer instance. * The Portainer instance reverse tunnel server address. This is identical to the API URL (unless [changed during deployment](https://docs.portainer.io/admin/environments/add/docker/edge#deploying) or in [Edge Compute settings](https://docs.portainer.io/admin/settings/edge#edge-compute-settings) ) but with the tunnel server port (`8000` is the default). * The Portainer instance reverse-tunnel server fingerprint (prevents MITM when creating a tunnel). * The environment identifier key (endpoint / environment ID). Use the command syntax to deploy an Edge Agent across your remote node or remote swarm cluster. [](https://docs.portainer.io/advanced/edge-agent#how-portainer-and-the-edge-agent-communicate) How Portainer and the Edge Agent communicate ------------------------------------------------------------------------------------------------------------------------------------------------ ### [](https://docs.portainer.io/advanced/edge-agent#polling) Polling Agents poll the Portainer instance every 5 seconds by default (this is defined in Portainer settings). ### [](https://docs.portainer.io/advanced/edge-agent#connection-process-and-checks) Connection process and checks The agent says to Portainer, “Hi, I'm an agent. My join token is `abc123`. Do you need me right now?”. Portainer checks its database to ensure the Edge UUID and the join token match. If no UUID can be associated with the join token provided, Portainer will associate the UUID provided by the agent to the environment’s join token. If the UUID/join token do not match, the connection is rejected. If the UUID/join token match, the Portainer instance responds with either: "No, I don’t need you. Please check in again in X seconds." (where X is the agent polling frequency), or "Yes, I do need you. Please connect using these tunnel credentials.”. Portainer encrypts the tunnel credentials using the Edge UUID as the encryption key (intended as one-time-use credentials). ### [](https://docs.portainer.io/advanced/edge-agent#opening-a-tunnel-between-the-agent-and-portainer) Opening a tunnel between the agent and Portainer Once confirmation is received, the Edge Agent decrypts the credentials and opens a tunnel on port `8000` to the Portainer instance. If a remote environment is a swarm cluster, every node will run an instance of the agent (and every instance will poll Portainer). The 'you are required' flag causes the first agent in the cluster to establish the tunnel. Once in place, Portainer can then query the agent where the tunnel is open. If the tunnel closes for any reason, the agent will immediately re-establish it. ### [](https://docs.portainer.io/advanced/edge-agent#when-portainer-forces-the-edge-agent-to-establish-a-tunnel) When Portainer forces the Edge Agent to establish a tunnel Sometimes Portainer will ask the agent to establish a tunnel. This happens when an admin selects an Edge environment for interactive management via the Portainer UI or the API. Once selected, the 'you are required' flag triggers the connection process. If default settings are in use, it takes about 10 seconds for the agent to poll and establish a tunnel. That’s about 5 seconds wait time until polling then a few seconds for the tunnel to open. The admin is shown this message while this happens: ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2Fz52evtIYEKvxvyhuozQs%2Fedge-advanced-2.png&width=768&dpr=4&quality=100&sign=f57216c9&sv=2) ### [](https://docs.portainer.io/advanced/edge-agent#terminating-the-connection) Terminating the connection The agent keeps a record of when Portainer last communicated with it. After 5 minutes of inactivity, it sends a snapshot of the current config to Portainer for its records, closes the tunnel and revokes the credentials. When admins have an active session with an Edge environment, ‘keep alives’ are sent every minute (even if the admin is not performing a task) so they are not kicked out by mistake. [](https://docs.portainer.io/advanced/edge-agent#network-performance) Network performance ---------------------------------------------------------------------------------------------- ### [](https://docs.portainer.io/advanced/edge-agent#adjusting-the-polling-frequency-to-improve-performance) Adjusting the polling frequency to improve performance Thousands of endpoints polling Portainer every 5 seconds is a lot. That’s about 324b/second per agent, not per environment. If you don’t do a lot of environment admin, we suggest you go into Portainer settings and increase the polling frequency. Simply change it back when you need to do some admin so you are not kept waiting. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FTnwMFdvhlbamDQaFN0zO%2F2.15-advanced-edgeagent-pollfreq.png&width=768&dpr=4&quality=100&sign=c7a4e6dc&sv=2) ### [](https://docs.portainer.io/advanced/edge-agent#ongoing-improvements) Ongoing improvements We load-tested Portainer with 15,000 actively connected environments with a polling frequency of 5 seconds. This generated 7Mbps of network traffic to the Portainer instance, and Portainer needed 4 CPUs to handle the encryption/tunnel load. This Edge Agent release is our first attempt at massive-scale centralized management. Our end goal is to reduce the network overhead associated with polling. [PreviousApp template JSON format](https://docs.portainer.io/advanced/app-templates/format) [NextAccess control](https://docs.portainer.io/advanced/access-control) Was this helpful? --- # Access control | Portainer Documentation All Docker and Docker Swarm resources (except images) deployed through Portainer have access control settings. You can set these when resources are deployed or at a later time. Resources deployed through a stack or a service will inherit the same access as the parent. [](https://docs.portainer.io/advanced/access-control#resources-deployed-through-portainer) Resources deployed through Portainer ------------------------------------------------------------------------------------------------------------------------------------ ### [](https://docs.portainer.io/advanced/access-control#access-to-administrators-only) Access to administrators only This is an example access control section, showing access control enabled. With these settings, only Portainer administrators will have access to the resource and any other resources created by it (for example, a stack that creates containers, services, volumes, networks and secrets). ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FEpg4BW6BEOdoZZNcRuXc%2F2.15-advanced-accesscontrol-admin.png&width=768&dpr=4&quality=100&sign=26272bcd&sv=2) ### [](https://docs.portainer.io/advanced/access-control#access-to-all-users) Access to all users This is an example access control section showing access control disabled. All Portainer users will have access to the resource and any resources created by it. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FC4zZzFNesxw95aNeGSkt%2F2.15-advanced-accesscontrol-public.png&width=768&dpr=4&quality=100&sign=77ec57e7&sv=2) ### [](https://docs.portainer.io/advanced/access-control#access-restricted-to-specific-groups-or-users) Access restricted to specific groups or users This is an example access control section showing access control enabled in **Restricted** mode. After you select the Restricted option, you can select more teams and users and give them access to the resource. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FHxHaLAupNLTX2hiXxhuU%2F2.15-advanced-accesscontrol-restricted.png&width=768&dpr=4&quality=100&sign=4e8691c2&sv=2) [](https://docs.portainer.io/advanced/access-control#resources-deployed-outside-of-portainer) Resources deployed outside of Portainer ------------------------------------------------------------------------------------------------------------------------------------------ Any resources deployed to Docker or Docker Swarm outside of Portainer will be marked as `external` and you will have limited control over these resources. By default, these resources will have administrator-only access, but you can enable access control using these labels (examples used, swap out for your own parameters): Label Access Granted `io.portainer.accesscontrol.public` All Portainer users have access to the resource. Takes precedence over team/user assignments. `io.portainer.accesscontrol.teams=dev,prod` Access restricted to teams `dev` and `prod` only. Can be used in conjunction with `io.portainer.accesscontrol.users` `io.portainer.accesscontrol.users=bob,adam` Access is restricted to users `bob` and `adam` only. Can be used in conjunction with `io.portainer.accesscontrol.teams` ### [](https://docs.portainer.io/advanced/access-control#examples) Example 1 Deploy a stack using Docker Compose and restrict access to teams `dev` and `prod`: Copy version: '3.2' services: ltest: image: busybox:latest command: "ping localhost" labels: io.portainer.accesscontrol.teams: dev,prod ### [](https://docs.portainer.io/advanced/access-control#example-2) Example 2 Deploy a stack using the Docker CLI and restrict access to team `testers` and users `bob` and `adam`: Copy version: '3.2' services: ltest: image: busybox:latest command: "ping localhost" labels: io.portainer.accesscontrol.teams: testers io.portainer.accesscontrol.users: bob,adam ### [](https://docs.portainer.io/advanced/access-control#example-3) Example 3 Deploy a container using the Docker CLI and make it accessible to all Portainer users: Copy docker run -d --label io.portainer.accesscontrol.public nginx:latest ### [](https://docs.portainer.io/advanced/access-control#example-4) Example 4 Deploy a container using the Docker CLI and restrict access to teams `dev` and `prod` and users `bob`: Copy docker run -d --label io.portainer.accesscontrol.teams=dev,prod --label io.portainer.accesscontrol.users=bob nginx:latest [PreviousThe Portainer Edge Agent](https://docs.portainer.io/advanced/edge-agent) [NextReset the admin user's password](https://docs.portainer.io/advanced/reset-admin) Was this helpful? --- # Security and compliance | Portainer Documentation Portainer runs exclusively on your servers, within your network, behind your own firewalls. As a result, we do not currently hold any SOC or PCI/DSS compliance because we do not host any of your infrastructure. You can even run Portainer completely disconnected (air-gapped) without any impact on functionality. We comply with GDPR in relation to the anonymous analytics we collect. Data collection can be disabled at startup (or at any time), and if you are disconnected, it silently fails. The Portainer code itself does not undergo any formal code analysis, however we scan our published images for vulnerabilities as part of the DockerHub process. We are also the subject of regular third-party vulnerability analyses. No issues have been reported for some time, and any issues that are discovered are resolved within six weeks. [PreviousReset the admin user's password](https://docs.portainer.io/advanced/reset-admin) [NextEncrypting the Portainer database](https://docs.portainer.io/advanced/db-encryption) Was this helpful? --- # API documentation | Portainer Documentation Portainer exposes an HTTP API that you can use to automate everything you do via the Portainer UI. You can also use Portainer as a gateway (HTTP queries against the Portainer API) to the underlying Docker/Kubernetes API. You will need an access token in order to use the Portainer API. If you have not already set up an access token for the API, we have [instructions on how to do so](https://docs.portainer.io/api/access) . You can find our API documentation at SwaggerHub: * [Business Edition (BE) 2.33.3 API Documentation](https://app.swaggerhub.com/apis/portainer/portainer-ee/2.33.3) * [Community Edition (CE) 2.33.3 API Documentation](https://app.swaggerhub.com/apis/portainer/portainer-ce/2.33.3) We have also provided some examples of API usage. [API usage examples](https://docs.portainer.io/api/examples) [PreviousAccessing the Portainer API](https://docs.portainer.io/api/access) [NextAPI usage examples](https://docs.portainer.io/api/examples) Last updated 16 days ago Was this helpful? --- # App template JSON format | 2.35 STS | Portainer Documentation App template definitions are written in JSON. Valid templates consist of an array, and every template definition consists of one element. [](https://docs.portainer.io/sts/advanced/app-templates/format#container-template-definition-format) Container template definition format ---------------------------------------------------------------------------------------------------------------------------------------------- A container template element must be a valid JSON object, composed of both mandatory and optional data fields. Here's an example of the format: Copy { "version": "2", "templates": [\ {\ // template1\ },\ {\ // template2\ },\ ...\ ] } ### [](https://docs.portainer.io/sts/advanced/app-templates/format#type) type * **Description:** The template type. * **Format:** Integer * **Valid values:** `1` = container; `2` = Swarm stack; `3` = Compose stack * **Required/Optional:** Required * **Other information:** Type `3` is limited to using the version `"2"` stack format (this is a docker/libcompose limitation). ### [](https://docs.portainer.io/sts/advanced/app-templates/format#title) title * **Description:** The template title. * **Format:** String * **Valid values:** Any string value. * **Required/Optional:** Required ### [](https://docs.portainer.io/sts/advanced/app-templates/format#description) description * **Description:** The template description. * **Format:** String * **Valid values:** Any string value. * **Required/Optional:** Required ### [](https://docs.portainer.io/sts/advanced/app-templates/format#image) image * **Description:** The Docker image associated with a template. * **Format:** String * **Valid values:** Any valid URL. * **Required/Optional:** Required ### [](https://docs.portainer.io/sts/advanced/app-templates/format#administrator-only) administrator-only * **Description:** Indicates whether or not a template should be available just to admin users. * **Format:** Boolean * **Valid values:** `true` = available to admins only; `false` = available to all users * **Required/Optional:** Optional * **Example:** See below. Copy { "administrator-only": true } ### [](https://docs.portainer.io/sts/advanced/app-templates/format#name) name * **Description:** The default name of a template (shows in the Portainer UI). * **Format:** String * **Valid values:** Any valid string. * **Required/Optional:** Optional ### [](https://docs.portainer.io/sts/advanced/app-templates/format#logo) logo * **Description:** The template logo. * **Format:** String * **Valid values:** Any valid URL. * **Required/Optional:** Optional ### [](https://docs.portainer.io/sts/advanced/app-templates/format#registry) registry * **Description:** The registry where the Docker image is stored. If not specified, Portainer will use Docker Hub as the default. * **Format:** String * **Valid values:** Any string value. * **Required/Optional:** Optional ### [](https://docs.portainer.io/sts/advanced/app-templates/format#command) command * **Description:** The command to run in the container. If not specified, the container will use the default command in its Dockerfile. * **Format:** String * **Valid values:** Any string value. * **Required/Optional:** Optional * **Example:** See below. Copy { "command": "/bin/bash -c \"echo hello\" && exit 777" } ### [](https://docs.portainer.io/sts/advanced/app-templates/format#env) env * **Description:** A JSON array describing the environment variables required by a 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). * **Format:** Array * **Required/Optional:** Optional Array format: Copy { "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: Copy { "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."\ }\ ] } ### [](https://docs.portainer.io/sts/advanced/app-templates/format#network) network * **Description:** A string that corresponds to the name of an existing Docker network. Will auto-select the network in the templates view. * **Format:** String * **Valid values:** Any string value. If the string does not match an existing network name when the template is used it will fall back to the first available network. * **Required/Optional:** Optional * **Example:** See below. Copy { "network": "host" } ### [](https://docs.portainer.io/sts/advanced/app-templates/format#volumes) volumes * **Description:** A JSON array describing the volumes associated with a template. Each element in the array must be a valid JSON object with 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 `readonly` mode. * **Format:** Array * **Required/Optional:** Optional * **Example:** See below. Copy { "volumes": [\ {\ "container": "/etc/nginx"\ },\ {\ "container": "/usr/share/nginx/html",\ "bind": "/var/www",\ "readonly": true\ }\ ] } ### [](https://docs.portainer.io/sts/advanced/app-templates/format#ports) ports * **Description:** A JSON array describing the ports exposed by a template. Each element in the array must be a valid JSON string specifying the port number in the container, as well as the protocol. Can be optionally prefixed with a port number and colon (for example `8080:`) to define the port to be mapped on the host. If the host port is not specified, the Docker host will automatically assign it when starting the container. * **Format:** Array * **Required/Optional:** Optional * **Example:** See below. Copy { "ports": ["8080:80/tcp", "443/tcp"] } ### [](https://docs.portainer.io/sts/advanced/app-templates/format#labels) labels * **Description:** A JSON array describing the labels associated with a template. Each element in the array must be a valid JSON object with two properties (`name:` and `""`). * **Format:** Array * **Required/Optional:** Optional * **Example:** See below. Copy { "labels": [\ { "name": "com.example.vendor", "value": "Acme" },\ { "name": "com.example.license", "value": "GPL" },\ { "name": "com.example.version", "value": "1.0" }\ ] } ### [](https://docs.portainer.io/sts/advanced/app-templates/format#privileged) privileged * **Description:** Indicates whether or not the container should be started in `privileged` mode. Defaults to `false` if not specified. * **Format:** Boolean * **Valid values:** `true` = start the container in privileged mode; `false` = do not start the container in privileged mode * **Required/Optional:** Optional * **Example:** See below. Copy { "privileged": true } ### [](https://docs.portainer.io/sts/advanced/app-templates/format#interactive) interactive * **Description:** Indicates whether or not the container should be started in `foreground` mode. Defaults to `false` if not specified. * **Format:** Boolean * **Valid values:** `true` = start the container in foreground mode; `false` = do not start the container in foreground mode * **Required/Optional:** Optional * **Example:** See below. Copy { "interactive": true } ### [](https://docs.portainer.io/sts/advanced/app-templates/format#restart_policy) restart\_policy * **Description:** The restart policy associated with the container. Will default to `"always"` if no value is specified. * **Format:** String * **Valid values:** * `"always"` Always restart the container regardless of the exit status. * `"no"` Never automatically restart the container. * `"on-failure"` Restart the container only if it exits with a non-zero status. * `"unless-stopped"` Always restart the container regardless of the exit status (unless the container was manually stopped). * **Required/Optional:** Optional * **Example:** See below. Copy { "restart_policy": "unless-stopped" } ### [](https://docs.portainer.io/sts/advanced/app-templates/format#hostname) hostname * **Description:** The hostname of the container. Will default to Docker if not specified. * **Format:** String * **Valid values:** Any string value. * **Required/Optional:** Optional * **Example:** See below. Copy { "hostname": "mycontainername" } ### [](https://docs.portainer.io/sts/advanced/app-templates/format#note) note * **Description:** Extra information about a template, for example what it is used for. Displayed inside the template-creation form in the Portainer UI. Supports HTML. * **Format:** String * **Valid values:** Any string value. * **Required/Optional:** Optional * **Example:** See below. Copy { "note": "You can use this field to record extra information about a template." } ### [](https://docs.portainer.io/sts/advanced/app-templates/format#platform) platform * **Description:** The supported platform. Displays a small platform-related icon in the Portainer UI. Must contain a valid value. * **Format:** String * **Valid values:** `"linux"`; `"windows"` * **Required/Optional:** Optional * **Example:** See below. Copy { "platform": "linux" } ### [](https://docs.portainer.io/sts/advanced/app-templates/format#categories) categories * **Description:** An array of categories associated with a template. Populates the category filter in the Portainer UI. * **Format:** Array * **Required/Optional:** Optional * **Example:** See below. Copy { "categories": ["webserver", "open-source"] } [](https://docs.portainer.io/sts/advanced/app-templates/format#stack-template-definition-format) Stack template definition format -------------------------------------------------------------------------------------------------------------------------------------- A stack template element must be a valid JSON object, composed of mandatory and optional data fields. Here's an example of the format: Copy { "type": 2, "title": "CockroachDB", "description": "CockroachDB cluster", "note": "Deploys an insecure CockroachDB cluster, please refer to CockroachDB documentation 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" } } ### [](https://docs.portainer.io/sts/advanced/app-templates/format#type-1) type * **Description:** The template type. A Swarm stack will be deployed using the equivalent of `docker stack deploy`. A Compose stack will be deployed using the equivalent of `docker-compose.` * **Format:** Integer * **Valid values:** `1` = container; `2` = Swarm stack; `3` = Compose stack * **Required/Optional:** Required * **Other information:** Type `3` is limited to using the version `"2"` stack format (this is a docker/libcompose limitation). ### [](https://docs.portainer.io/sts/advanced/app-templates/format#title-1) title * **Description:** The template title. * **Format:** String * **Valid values:** Any string value. * **Required/Optional:** Required ### [](https://docs.portainer.io/sts/advanced/app-templates/format#description-1) description * **Description:** The template description. * **Format:** String * **Valid values:** Any string value. * **Required/Optional:** Required ### [](https://docs.portainer.io/sts/advanced/app-templates/format#repository) repository * **Description:** 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. * **Format:** Object * **Valid values:** See the example below. * **Required/Optional:** Required This value **must** reference a Git repository. Object format: Copy { "url": "URL of the public git repository (mandatory)", "stackfile": "Path to the Compose file inside the repository (mandatory)", } Example: Copy { "url": "https://github.com/portainer/templates", "stackfile": "stacks/cockroachdb/docker-stack.yml" } ### [](https://docs.portainer.io/sts/advanced/app-templates/format#administrator_only) administrator\_only * **Description:** Indicates whether or not a template should be available just to admin users. * **Format:** Boolean * **Valid values:** `true` = available to admins only; `false` = available to all users * **Required/Optional:** Optional * **Example:** See below. Copy { "administrator_only": true } ### [](https://docs.portainer.io/sts/advanced/app-templates/format#name-1) name * **Description:** The default name of a template (shows in the Portainer UI). * **Format:** String * **Valid values:** Any valid string. * **Required/Optional:** Optional ### [](https://docs.portainer.io/sts/advanced/app-templates/format#logo-1) logo * **Description:** The template logo. * **Format:** String * **Valid values:** Any valid URL. * **Required/Optional:** Optional ### [](https://docs.portainer.io/sts/advanced/app-templates/format#env-1) env * **Description:** A JSON array describing the environment variables required by a 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). * **Format:** Array * **Required/Optional:** Optional 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). Array format: Copy { "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: Copy { "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."\ }\ ] } ### [](https://docs.portainer.io/sts/advanced/app-templates/format#note-1) note * **Description:** Extra information about a template, for example what it is used for. Displayed inside the template-creation form in the Portainer UI. Supports HTML. * **Format:** String * **Valid values:** Any string value. * **Required/Optional:** Optional * **Example:** See below. Copy { "note": "You can use this field to record extra information about a template." } ### [](https://docs.portainer.io/sts/advanced/app-templates/format#platform-1) platform * **Description:** The supported platform. Displays a small platform-related icon in the Portainer UI. Must contain a valid value. * **Format:** String * **Valid values:** `"linux"`; `"windows"` * **Required/Optional:** Optional * **Example:** See below. Copy { "platform": "linux" } ### [](https://docs.portainer.io/sts/advanced/app-templates/format#categories-1) categories * **Description:** An array of categories associated with a template. Populates the category filter in the Portainer UI. * **Format:** Array * **Required/Optional:** Optional * **Example:** See below. Copy { "categories": ["webserver", "open-source"] [PreviousBuild and host your own app templates](https://docs.portainer.io/sts/advanced/app-templates/build) [NextThe Portainer Edge Agent](https://docs.portainer.io/sts/advanced/edge-agent) Was this helpful? --- # Using your own SSL certificate with Portainer | Portainer Documentation By default, Portainer’s web interface and API is exposed over HTTPS with a self-signed certificate generated by the installation. This can be replaced with your own SSL certificate either after installation [via the Portainer UI](https://docs.portainer.io/admin/settings#ssl-certificate) or during installation, as explained in this article. When using your own externally-issued certificate, ensure that you include the full certificate chain (including any intermediate certificates) in the file you provide via `--sslcert`. Without this you may face certificate validation issues. Your certificate chain can be obtained either from your certificate issuer or the [What's My Chain Cert?](https://whatsmychaincert.com/) website. [](https://docs.portainer.io/advanced/ssl#using-your-own-ssl-certificate-on-docker-standalone) Using your own SSL certificate on Docker Standalone ------------------------------------------------------------------------------------------------------------------------------------------------------- Portainer expects certificates in PEM format. Use the `--tlscert` and `--tlskey` flags during installation. Upload your certificate (including the chain) and key to the server running Portainer, then start Portainer referencing them. The following command assumes your certificates are stored in `/path/to/your/certs` with the filenames `portainer.crt` and `portainer.key`, and bind-mounts the directory to `/certs` in the Portainer container: Business Edition Community Edition Copy docker run -d -p 9443:9443 -p 8000:8000 \ --name portainer --restart always \ -v /var/run/docker.sock:/var/run/docker.sock \ -v portainer_data:/data \ -v /path/to/your/certs:/certs \ portainer/portainer-ee:lts \ --tlscert /certs/portainer.crt \ --tlskey /certs/portainer.key Copy docker run -d -p 9443:9443 -p 8000:8000 \ --name portainer --restart always \ -v /var/run/docker.sock:/var/run/docker.sock \ -v portainer_data:/data \ -v /path/to/your/certs:/certs \ portainer/portainer-ce:lts \ --tlscert /certs/portainer.crt \ --tlskey /certs/portainer.key Alternatively, Certbot can be used to generate a certificate and a key. Because Docker has issues with symlinks, if you use Certbot you will need to pass both the 'live' and 'archive' directories as volumes, as well as use the full chain certificate. For example: Business Edition Community Edition Copy docker run -d -p 9443:9443 -p 8000:8000 \ --name portainer --restart always \ -v /var/run/docker.sock:/var/run/docker.sock \ -v portainer_data:/data \ -v /etc/letsencrypt/live/yourdomain:/certs/live/yourdomain:ro \ -v /etc/letsencrypt/archive/yourdomain:/certs/archive/yourdomain:ro \ portainer/portainer-ee:lts \ --tlscert /certs/live/yourdomain/fullchain.pem \ --tlskey /certs/live/yourdomain/privkey.pem Copy docker run -d -p 9443:9443 -p 8000:8000 \ --name portainer --restart always \ -v /var/run/docker.sock:/var/run/docker.sock \ -v portainer_data:/data \ -v /etc/letsencrypt/live/yourdomain:/certs/live/yourdomain:ro \ -v /etc/letsencrypt/archive/yourdomain:/certs/archive/yourdomain:ro \ portainer/portainer-ce:lts \ --tlscert /certs/live/yourdomain/fullchain.pem \ --tlskey /certs/live/yourdomain/privkey.pem When you're finished, you can navigate to `https://$ip-docker-host:9443`. [](https://docs.portainer.io/advanced/ssl#using-your-own-ssl-certificate-on-docker-swarm) Using your own SSL certificate on Docker Swarm --------------------------------------------------------------------------------------------------------------------------------------------- To provide your own SSL certificate for Docker Swarm, simply define the `portainer.sslcert` and `portainer.sslkey` secrets, and the installation manifest will automatically detect and use them: Copy docker secret create portainer.tlscert /path/to/your/certificate.crt docker secret create portainer.tlskey /path/to/your/certificate.key Next, retrieve the stack YML manifest: Linux and Windows with Docker Desktop Windows Container Services **Business Edition:** Copy curl -L https://downloads.portainer.io/ee-lts/portainer-agent-stack-ssl.yml -o portainer-agent-stack.yml **Community Edition:** Copy curl -L https://downloads.portainer.io/ce-lts/portainer-agent-stack-ssl.yml -o portainer-agent-stack.yml **Business Edition:** Copy curl https://downloads.portainer.io/ee-lts/portainer-windows-stack-ssl.yml -o portainer-agent-stack.yml **Community Edition:** Copy curl https://downloads.portainer.io/ce-lts/portainer-windows-stack-ssl.yml -o portainer-agent-stack.yml Finally, use the downloaded YML manifest to deploy your stack: Copy docker stack deploy -c portainer-agent-stack.yml portainer For more information about secrets, read [Docker's own documentation](https://docs.docker.com/compose/compose-file/#secrets) . [](https://docs.portainer.io/advanced/ssl#using-your-own-ssl-certificate-on-kubernetes-via-helm) Using your own SSL certificate on Kubernetes (via Helm) ------------------------------------------------------------------------------------------------------------------------------------------------------------- If it doesn't already exist, create the `portainer` namespace: Copy kubectl create namespace portainer Next, create a TLS secret containing the full certificate chain and matching private key: Copy kubectl create secret tls portainer-tls-secret -n portainer \ --cert=/path/to/cert/file \ --key=/path/to/key/file Install via helm with the `tls.existingSecret` parameter set to the name of the secret you just created: NodePort Load Balancer **Business Edition:** Copy helm install -n portainer portainer portainer/portainer \ --set tls.existingSecret=portainer-tls-secret \ --set enterpriseEdition.enabled=true **Community Edition:** Copy helm install -n portainer portainer portainer/portainer \ --set tls.existingSecret=portainer-tls-secret Business Edition: Copy helm install -n portainer portainer portainer/portainer \ --set tls.existingSecret=portainer-tls-secret \ --set service.type=LoadBalancer \ --set enterpriseEdition.enabled=true Community Edition: Copy helm install -n portainer portainer portainer/portainer \ --set tls.existingSecret=portainer-tls-secret \ --set service.type=LoadBalancer [PreviousEncrypting the Portainer database](https://docs.portainer.io/advanced/db-encryption) [NextUsing mTLS with Portainer](https://docs.portainer.io/advanced/mtls) Last updated 1 month ago Was this helpful? --- # API usage examples | 2.35 STS | Portainer Documentation Portainer exposes an HTTP API that you can use to automate everything you do via the Portainer UI. You can also use Portainer as a gateway (HTTP queries against the Portainer API) to the underlying Docker/Kubernetes API. The following examples use [httpie](https://httpie.org/) to execute API calls against Portainer. [](https://docs.portainer.io/sts/api/examples#initialize-the-admin-password) Initialize the admin password --------------------------------------------------------------------------------------------------------------- On a fresh install of Portainer, you need to create an admin account to initialize Portainer. You will be asked for this when you visit the Portainer URL for the first time. You can achieve the same outcome using this API call: Copy http POST /api/users/admin/init Username="" Password="" [](https://docs.portainer.io/sts/api/examples#authenticate-against-the-api-using-the-admin-account) Authenticate against the API using the admin account ------------------------------------------------------------------------------------------------------------------------------------------------------------- Copy http POST /api/auth Username="" Password="" The response is a JSON object containing the JWT token inside the `jwt` field. You will need to pass this token inside the authorization header when executing an authentication query against the API. Copy { "jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGUiOjEsImV4cCI6MTQ5OTM3NjE1NH0.NJ6vE8FY1WG6jsRQzfMqeatJ4vh2TWAeeYfDhP71YEE" } The value of the authorization header must be of the form `Bearer `: Copy Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwidXNlcm5hbWUiOiJhZG1pbiIsInJvbGUiOjEsImV4cCI6MTQ5OTM3NjE1NH0.NJ6vE8FY1WG6jsRQzfMqeatJ4vh2TWAeeYfDhP71YEE This token is valid for 8 hours. Once it expires, you will need to generate another token to execute authenticated queries. [](https://docs.portainer.io/sts/api/examples#adding-a-new-environment) Adding a new environment ----------------------------------------------------------------------------------------------------- On a fresh install, Portainer has no environments configured. You will first need to add an environment for Portainer to manage. You can add an environment to manage [via the Portainer API](https://docs.portainer.io/sts/admin/environments/add/api) , or via the web interface both during the initial setup and after setup is complete. [](https://docs.portainer.io/sts/api/examples#execute-docker-queries-against-a-specific-environment) Execute Docker queries against a specific environment --------------------------------------------------------------------------------------------------------------------------------------------------------------- The Portainer HTTP API endpoint acts as a reverse-proxy to the Docker HTTP API and can be used to execute any of the Docker HTTP API requests: `/api/endpoints//docker` Read [Docker's API documentation](https://docs.docker.com/engine/api/) to learn how to query the Docker Engine. ### [](https://docs.portainer.io/sts/api/examples#list-all-containers) **List all containers** This call lists all of the containers available in a specific environment: Copy http GET /api/endpoints/1/docker/containers/json \ X-API-Key:your_access-token \ all==true The response is identical to that returned by the `ContainerList` operation of the Docker API. See [Docker's documentation about this operation](https://docs.docker.com/engine/api/v1.41/#operation/ContainerList) . ### [](https://docs.portainer.io/sts/api/examples#create-a-container) **Create a container** You can create a container in a specific environment using the Portainer HTTP API as a gateway. The following query will create a new Docker container inside the environment using ID 1. The container will be named `web01` and will use the `nginx:latest` Docker image. It will publish container port `80` on port `8080` on the host. Copy http POST /api/endpoints/1/docker/containers/create \ X-API-Key:your_access-token \ name=="web01" Image="nginx:latest" \ ExposedPorts:='{ "80/tcp": {} }' \ HostConfig:='{ "PortBindings": { "80/tcp": [{ "HostPort": "8080" }] } }' The response is identical to that returned by the `ContainerCreate` operation of the Docker API. See [Docker's documentation about this operation](https://docs.docker.com/engine/api/v1.41/#operation/ContainerCreate) . Here is an example response: Copy { "Id": "5fc2a93d7a3d426a1c3937436697fc5e5343cc375226f6110283200bede3b107", "Warnings": null } You will need the container ID in order to execute actions against that container. ### [](https://docs.portainer.io/sts/api/examples#start-a-container) **Start a container** Using the ID you retrieved previously, you can start your new container using this endpoint: `/api/endpoints//docker/containers//start` Copy http POST /api/endpoints/1/docker/containers/5fc2a93d7a3d426a1c3937436697fc5e5343cc375226f6110283200bede3b107/start \ X-API-Key:your_access-token The response is identical to that returned by the `ContainerStart` operation of the Docker API. See [Docker's documentation about this operation](https://docs.docker.com/engine/api/v1.41/#operation/ContainerStart) . ### [](https://docs.portainer.io/sts/api/examples#delete-a-container) **Delete a container** You can create a container using the endpoint `/api/endpoints//docker/containers/`: Copy http DELETE /api/endpoints/1/docker/containers/5fc2a93d7a3d426a1c3937436697fc5e5343cc375226f6110283200bede3b107 \ X-API-Key:your_access-token \ force==true The response is identical to that returned by the `ContainerDelete` operation of the Docker API. See [Docker's documentation about this operation](https://docs.docker.com/engine/api/v1.41/#operation/ContainerDelete) . [PreviousAPI documentation](https://docs.portainer.io/sts/api/docs) [NextContribute](https://docs.portainer.io/sts/contribute/contribute) Was this helpful? --- # Build and host your own app templates | Portainer Documentation To provide your own template files, you will need to host your files somewhere accessible by the Portainer Server instance. This could be somewhere like GitHub, a web server, or perhaps a container running nginx. As an example, the Portainer templates repository includes a `Dockerfile` that lets you start it as a container to serve the JSON file. To set this up, first clone the [Portainer templates repository](https://github.com/portainer/templates) , edit the templates file, then build and run the container: Copy 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 Access your template 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: Copy docker run -d -p "8080:80" -v "${PWD}/templates.json:/usr/share/nginx/html/templates.json" portainer-templates For more information about the format of the app template, go [here](https://docs.portainer.io/advanced/app-templates/format) . [PreviousApp templates](https://docs.portainer.io/advanced/app-templates) [NextApp template JSON format](https://docs.portainer.io/advanced/app-templates/format) Was this helpful? --- # How Relative Path Support works in Portainer | Portainer Documentation The relative path volumes support in Portainer Business Edition is intended to provide you with a way to reference files and directories that are supplied within the Git repository alongside your compose file without needing to know the absolute path at which they will appear when they are deployed to your environment. Relative path support is only present in Portainer Business Edition, and needs to be [enabled when deploying your stack from Git](https://docs.portainer.io/user/docker/stacks/add#relative-path-volumes) for this article to apply. In the background the way this works is as follows: 1. In Portainer, a stack deployment is initiated where the stack is located in a Git repository, **Enable relative path volumes** is selected and a **Local (or Network) filesystem path** is specified. 2. Portainer creates a temporary unpacker container that bind mounts the path specified in the Local (or Network) filesystem path field. 3. The unpacker container clones the Git repository to a subdirectory under the bind mounted path. 4. Portainer creates the stack using the compose file provided, specifying the working directory as where the specified compose file is located within where the Git repo was cloned. 5. Now that the stack has been deployed, the temporary unpacker container is removed. To take advantage of this with your compose file, you can specify any references to files that are within your repository in a _relative_ manner to your compose file. For example, imagine this simple nginx deployment: Copy . ├── docker-compose.yml └── static └── index.html In this example, the `docker-compose.yml` file is at the base directory of the repository. Alongside it there is a directory named `static`, and within that directory is an `index.html` file. The `docker-compose.yml` file looks like this: Copy version: '3.1' services: webapp: image: nginx:latest restart: always ports: - "3002:80" volumes: - ./static:/usr/share/nginx/html The last line is the important one here - you'll note that we're referencing the static directory with a leading `.` and `/` - this tells compose that the path specified is _relative_ to the working directory, which Portainer specified during deployment. If we excluded the leading `.` this would be an _absolute_ path, and would refer to `/static` at the root of the host filesystem. Let's look at an example where you had your compose file in a subdirectory of your repository, and your content in a different subdirectory: Copy . ├── nginx │ └── docker-compose.yml └── static └── index.html In this scenario, you would specify the compose file when deploying as `nginx/docker-compose.yml`. Portainer will pull the contents of the repository to the specified location and set the working directory to the location of the compose file (ie, within the `nginx` subdirectory). As such, relative references within the compose need to be aware of this. To mount the contents of the `static` directory, your compose file would look like: Copy version: '3.1' services: webapp: image: nginx:latest restart: always ports: - "3002:80" volumes: - ../static:/usr/share/nginx/html The double dots (`..`) indicate that the files are at a directory level above the working directory. ### [](https://docs.portainer.io/advanced/relative-paths#a-note-about-the-local-or-network-filesystem-path) A note about the local (or network) filesystem path The path on the local (or network) filesystem that the Git repository is cloned to will be in: Copy portainer-compose-unpacker/stacks/yourstackname/ For example, if you deployed a stack named `nginx` and specified the local filesystem path as: Copy /mnt/stacks/ it would result in: Copy /mnt/stacks/portainer-compose-unpacker/stacks/nginx/ This is generally not relevant for relative path referencing as the definition of the working directory avoids needing to be aware of this full path, but it does mean the same local (or network) filesystem path can be used to deploy multiple stacks without worrying about collisions (as long as they don't share the same stack name). This path is where your stack's mounted files will be sourced from, so you will want to ensure this path remains intact and unchanged. When a stack deployed with this method is removed, the file and directory structure for that stack are removed as well. [PreviousDeploying Portainer behind nginx reverse proxy](https://docs.portainer.io/advanced/reverse-proxy/nginx) [NextHelm chart configuration options](https://docs.portainer.io/advanced/helm-chart-configuration-options) Was this helpful? --- # Set up a Linux build environment | 2.35 STS | Portainer Documentation As an open source product, we encourage users to edit our code and submit patches to it. This article explains how to set up a local environment on Linux so you can build your own copy of Portainer and test your changes. We tested these instructions on Ubuntu 18.04.2 LTS. For instructions that relate to other systems, see the linked documentation below. [](https://docs.portainer.io/sts/contribute/build/linux#dependencies) Dependencies --------------------------------------------------------------------------------------- * [Docker CE](https://docs.docker.com/install/) is the Docker application that runs on your machine to enable the use of Docker features. The latest version is not a requirement for this development stack, however we recommend staying up to date with the latest improvements and security fixes. * ​[Yarn](https://yarnpkg.com/en/docs/install#mac-stable) is a package manager for installing new software packages on your system, and is used to run the Portainer development environment. * [Node.JS](https://nodejs.org/en/download/) is a JavaScript package used when building applications that leverage networking, such as Portainer. Version 18 or later is required. * [Golang](https://golang.org/dl/) is the open source language that we use to build the majority of Portainer software. Version 1.18 of Golang is required. * Wget is a package used to retrieve files using common internet protocols such as HTTP and FTP. [](https://docs.portainer.io/sts/contribute/build/linux#part-1-installing-docker) Part 1: Installing Docker ---------------------------------------------------------------------------------------------------------------- The following instructions were run on Ubuntu, for up-to-date instructions on this and other Linux distributions read the [official Docker CE documentation](https://docs.docker.com/install/) . You must configure the Docker repository before you install Docker. ### [](https://docs.portainer.io/sts/contribute/build/linux#step-1-configure-the-docker-repository) Step 1: Configure the Docker repository First, update your system's packages using this command: Copy sudo apt-get update Next, install the required packages to use repos over HTTPS: Copy sudo apt-get install \ apt-transport-https \ ca-certificates \ curl \ gnupg-agent \ software-properties-common Now install the official GPG key for Docker: Copy curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - Use this fingerprint to confirm that you have the correct key: `9DC8 5822 9FC7 DD38 854A E2D8 8D81 803C 0EBF CD88` Copy sudo apt-key fingerprint 0EBFCD88 The correct output should be: Copy pub rsa4096 2017-02-22 [SCEA] 9DC8 5822 9FC7 DD38 854A E2D8 8D81 803C 0EBF CD88 uid [ unknown] Docker Release (CE deb) <[email protected]> sub rsa4096 2017-02-22 [S] And finally, use the following command to set up the stable repository: Copy sudo add-apt-repository \ "deb [arch=amd64] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) \ stable" ### [](https://docs.portainer.io/sts/contribute/build/linux#step-2-install-docker) Step 2: Install Docker We always recommend installing software using the most up-to-date instructions from the official vendor. This step is based on Docker's own [installation instructions for Docker on Linux](https://docs.docker.com/install/) . First, update your system's packages using this command: Copy sudo apt-get update Next, install Docker and its associated packages: Copy sudo apt-get install docker-ce docker-ce-cli containerd.io Finally, verify that Docker was correctly installed and is running on your system. This command should download a test image that you can run in a container, print an informational message for then exit out of. Copy sudo docker run hello-world [](https://docs.portainer.io/sts/contribute/build/linux#part-2-installing-yarn) Part 2: Installing Yarn ------------------------------------------------------------------------------------------------------------ If you are running a different Linux distribution than Ubuntu, read Yarn's own [installation instructions for Yarn on Linux](https://yarnpkg.com/en/docs/install) . If you have issues installing or using Yarn, read their [official documentation](https://yarnpkg.com/en/docs/install#mac-stable) . Run this command in the terminal to configure the Yarn repository on your system: Copy curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list Update your system's packages and install Yarn using this command: Copy sudo apt-get update && sudo apt-get install yarn Finally, run this command in the terminal to confirm that the Yarn installation was a success: Copy yarn --version The current version of Yarn should print out in your terminal, indicating that that it installed successfully and is running on your system. [](https://docs.portainer.io/sts/contribute/build/linux#part-3-installing-or-updating-node.js) Part 3: Installing or updating Node.JS ------------------------------------------------------------------------------------------------------------------------------------------ This procedure makes use of NVM to install Node.JS (Node.JS version 12 or later is required). NVM allows multiple different versions of Node.JS to be installed on a system and provides an easy way to switch between them. If you have issues installing or updating Node.JS, read NVM's [documentation](https://github.com/creationix/nvm) . First, install or update to the latest version of Node.JS by running this command in the terminal: Copy nvm install node Finally, check if Node is installed on your system: Copy node --version The latest version of Node.JS should now print out. [](https://docs.portainer.io/sts/contribute/build/linux#part-4-installing-golang-using-a-linux-tar-file) Part 4: Installing Golang using a Linux tar file -------------------------------------------------------------------------------------------------------------------------------------------------------------- Go version 1.17 must be installed. If you're upgrading from an older version, you must [remove the existing version](https://golang.org/doc/install#uninstall) first before installing version 1.17. For the most up-to-date installation instructions, read [Go's own documentation](https://golang.org/doc/install#install) . If you have issues installing or using Go, read the _Getting help_ section in their [official documentation](https://golang.org/doc/install#help) . First, [download](https://golang.org/dl/) the appropriate version of Go for your system. Navigate to where it was downloaded then extract it to the `/usr/local` directory using this command: Copy sudo tar -C /usr/local -xzf go1.17.6.linux-amd64.tar.gz Next, add `/usr/local/go/bin` to the PATH environment variable inside your shell profile. Here's an example using bash: Copy echo "export PATH=$PATH:$HOME/go/bin:/usr/local/go/bin" >> ~/.bashrc You may need to log out and log back in for this to take effect. And finally, follow the _Test your installation_ section in [Golang's official documentation](https://golang.org/doc/code.html#Testing) to ensure that Go installed correctly. [](https://docs.portainer.io/sts/contribute/build/linux#part-5-installing-wget) Part 5: Installing Wget ------------------------------------------------------------------------------------------------------------ If you have issues installing or using Wget, read their [documentation](https://www.gnu.org/software/wget/manual/) . To install Wget on Linux, simply run the `apt-get install wget` command in the terminal. [PreviousSet up a macOS build environment](https://docs.portainer.io/sts/contribute/build/mac) [NextPrivacy Policy](https://docs.portainer.io/sts/privacy) Was this helpful? --- # CLI configuration options | 2.35 STS | Portainer Documentation [](https://docs.portainer.io/sts/advanced/cli#configuration-flags-available-at-the-command-line) Configuration flags available at the command line ------------------------------------------------------------------------------------------------------------------------------------------------------- Flag Description `--admin-password` Specifies a bcrypt hashed password for the admin user. This can only be used when first creating the admin user (such as during installation) and not to change the admin user's password after installation. `--admin-password-file` Specifies the path to the file containing the plain text password for the admin user. This can only be used when first creating the admin user (such as during installation) and not to change the admin user's password after installation. `--base-url` Specifies the path that Portainer is running under if you are running Portainer within a subpath behind a reverse proxy (for example use `--base-url /portainer` if you are running Portainer at `https://yourdomain/portainer`). Defaults to `/`. **Note:** when using this option you will still need to ensure your reverse proxy configuration will strip the specified subpath. `--bind` `-p` Specifies the address and port from which to serve Portainer (default: `:9000`). `--bind-https` Specifies the address and port from which to serve Portainer via HTTPS (default: `:9443`). `--compact-db` Compacts the Portainer database on startup, which can reclaim disk space. `--data` `-d` Specifes the directory where Portainer data will be stored (default: `/data` on Linux, `C:\data` on Windows). `--edge-compute` Automatically enables Edge Compute features. `--hide-label` `-l` Hides containers with a specific label in the UI. `--http-disabled` Serve Portainer only on HTTPS. Overrides `--http-enabled`. Ensure your HTTPS configuration is fully working and any agents are configured for HTTPS before enabling this. `--http-enabled` Serve Portainer on HTTP. If used in combination with `--http-disabled`, this is ignored. `--host` `-H` Specifies the Docker daemon endpoint. `--license-key` Specifies the license key to use. Only applicable to Portainer Business Edition. `--log-level` Set the log level of the Portainer application, for example `--log-level DEBUG`. This is useful when troubleshooting. Debug logging can also be enabled through [Settings](https://docs.portainer.io/sts/admin/settings) . `--log-mode` Set the formatting for the Portainer log output, for example `--log-mode NOCOLOR`. Options are: `PRETTY` (default), `NOCOLOR` (disables color codes), `JSON` (JSON-formatted logs). `--logo` Specifies the URL to the image to be displayed as a logo in the UI. If not specified, the Portainer logo is used instead. `--mtlscacert` Specifies the path to the certificate authority (CA) certificate used for mTLS communication. (BE only) `--mtlscert` Specifies the path to the certificate used for mTLS communication. (BE only) `--mtlskey` Specifies the path to the certificate key used for mTLS communication. (BE only) `--no-csp` Disable the Content-Security-Policy header for the Portainer Server. We highly recommend against doing this unless you have a very specific need to do so. `--snapshot-interval` Specifies the time interval between two environment snapshot jobs expressed as a string. For example 30s, 5m, 1h… Supported by the `time.ParseDuration` method (default: 5m). `--sslcacert` Specifies the path to the certificate authority (CA) certificate used to validate the Edge Agent certificate. (BE only, **deprecated**, use [mTLS](https://docs.portainer.io/sts/advanced/mtls) instead) `--sslcert` Specifies the path to the SSL certificate used to secure the Portainer instance (default: `/certs/portainer.crt` on Linux, `C:\certs\portainer.crt` on Windows). `--sslkey` Specifies the path to the SSL key used to secure the Portainer instance (default: `/certs/portainer.key` on Linux, `C:\certs\portainer.key` on Windows). `--syslog-*` The `--syslog-*` options are used to configure auth and activity log streaming to an external Syslog-compatible provider. See the [SIEM documentation](https://docs.portainer.io/sts/advanced/siem) for more on this experimental feature. `--templates` `-t` Specifies the URL to the templates (apps) definitions. `--tlscacert` Specifies the path to the CA used for Docker daemon connections (default: `/certs/ca.pem` on Linux, `C:\certs\ca.pem` on Windows). `--tlscert` Specifies the path to the TLS certificate file used for Docker daemon connections (default: `/certs/cert.pem`, `C:\certs\cert.pem` on Windows). `--tlskey` Specifies the path to the TLS key used for Docker daemon connections (default: `/certs/key.pem`, `C:\certs\key.pem` on Windows). `--tlsverify` TLS support (default: `false`). `--tlsskipverify` Disable TLS server verification. `--trusted-origins` Specify (in a comma-separated list) the domain(s) used to access Portainer when it is behind a reverse proxy. Use this option if Portainer is behind a reverse proxy and you are getting "Origin invalid" errors. `--tunnel-addr` Specifies the tunnel address to listen on for use with the Edge Agent. Defaults to `0.0.0.0` (all interfaces). `--tunnel-port` Specifies 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`. `--version` Display the version of Portainer. [](https://docs.portainer.io/sts/advanced/cli#creating-an-admin-account-and-password) Creating an admin account and password --------------------------------------------------------------------------------------------------------------------------------- The commands in this section will automatically create an administrator account called `admin` with the password you specify. This can only be used when first creating the admin user (such as during installation) and not to change the admin user's password after installation. ### [](https://docs.portainer.io/sts/advanced/cli#method-1-creating-the-account-from-the-command-line) Method 1: Creating the account from the command line You can specify a bcrypt-encrypted password from the command line for the admin account. If you have installed the `apache2-utils` package, create the password using the following command: Copy htpasswd -nb -B admin "your-password" | cut -d ":" -f 2 If your system does not have that command, use a container to run the command instead: Copy docker run --rm httpd:2.4-alpine htpasswd -nbB admin "your-password" | cut -d ":" -f 2 Once the password has been created, specify the admin password from the command line by starting Portainer with the `--admin-password` flag: Business Edition Community Edition Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ee:sts --admin-password='$2y$05$8oz75U8m5tI/xT4P0NbSHeE7WyRzOWKRBprfGotwDkhBOGP/u802u' Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ce:sts --admin-password='$2y$05$8oz75U8m5tI/xT4P0NbSHeE7WyRzOWKRBprfGotwDkhBOGP/u802u' ### [](https://docs.portainer.io/sts/advanced/cli#method-2-creating-the-account-using-a-file) Method 2: Creating the account using a file You can also store a plain text password inside a file and use the `--admin-password-file` flag. First, add the password to a file using the following example command as a guide: Copy echo -n mypassword > /tmp/portainer_password Next, start the Portainer container: Business Edition Community Edition Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock -v /tmp/portainer_password:/tmp/portainer_password portainer/portainer-ee:sts --admin-password-file /tmp/portainer_password Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock -v /tmp/portainer_password:/tmp/portainer_password portainer/portainer-ce:sts --admin-password-file /tmp/portainer_password This also works well with Docker Swarm and Docker Secrets: Copy echo -n mypassword | docker secret create portainer-pass - Business Edition Community Edition Copy docker service create \ --name portainer \ --secret portainer-pass \ --publish 9443:9443 \ --publish 8000:8000 \ --replicas=1 \ --constraint 'node.role == manager' \ --mount type=bind,src=/var/run/docker.sock,dst=/var/run/docker.sock \ portainer/portainer-ee:sts \ --admin-password-file '/run/secrets/portainer-pass' \ -H unix:///var/run/docker.sock Copy docker service create \ --name portainer \ --secret portainer-pass \ --publish 9443:9443 \ --publish 8000:8000 \ --replicas=1 \ --constraint 'node.role == manager' \ --mount type=bind,src=/var/run/docker.sock,dst=/var/run/docker.sock \ portainer/portainer-ce:sts \ --admin-password-file '/run/secrets/portainer-pass' \ -H unix:///var/run/docker.sock [](https://docs.portainer.io/sts/advanced/cli#hiding-specific-containers) Hiding specific containers --------------------------------------------------------------------------------------------------------- Portainer lets you hide containers with a specific label by using the `-l` flag. Here's an example showing a container labeled `owner=acme`: Copy docker run -d --label owner=acme nginx To hide this container, when starting Portainer add the `-l owner=acme` option on the CLI: Business Edition Community Edition Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ee:sts -l owner=acme Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ce:sts -l owner=acme To hide multiple containers, repeat the `-l` flag: Business Edition Community Edition Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ee:sts -l owner=acme -l service=secret Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ce:sts -l owner=acme -l service=secret [](https://docs.portainer.io/sts/advanced/cli#using-your-own-logo) Using your own logo ------------------------------------------------------------------------------------------- Images must be exactly 155px by 55px in size. Replace our logo with your own using the `--logo` flag to specify the location of the image file: Business Edition Community Edition Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ee:sts --logo "https://www.docker.com/sites/all/themes/docker/assets/images/brand-full.svg" Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ce:sts --logo "https://www.docker.com/sites/all/themes/docker/assets/images/brand-full.svg" You can also update the logo in the Portainer UI (**Settings** menu). [](https://docs.portainer.io/sts/advanced/cli#defining-your-own-app-templates) Defining your own app templates ------------------------------------------------------------------------------------------------------------------- We suggest hosting template files on [GitHub](https://www.github.com/) so Portainer can access them without authentication. Portainer allows you to rapidly [deploy containers using app templates](https://docs.portainer.io/sts/user/docker/templates/deploy-container) . By default, Portainer templates will be used but you can also define your own. Templates are loaded once when Portainer is first started. If you already deployed a Portainer instance then decide to use your own templates, you’ll need to clear the default templates either in the user interface or through the HTTP API. Use the `--templates` flag to specify a URL where the template file can be accessed via HTTP. Business Edition Community Edition Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ee:sts --templates http://my-host.my-domain/templates.json Copy docker run -d -p 9443:9443 -p 8000:8000 -v /var/run/docker.sock:/var/run/docker.sock portainer/portainer-ce:sts --templates http://my-host.my-domain/templates.json [PreviousWhich versions of Portainer do you provide support for?](https://docs.portainer.io/sts/faqs/getting-support/which-versions-of-portainer-do-you-provide-support-for) [NextApp templates](https://docs.portainer.io/sts/advanced/app-templates) Last updated 1 month ago Was this helpful? --- # Encrypting the Portainer database | Portainer Documentation Portainer uses a BoltDB database to store the configuration, kept in the `portainer_data` volume created during installation. This database can be encrypted for additional security through the use of a secret provided when the Portainer Server is started. Encryption can be added during the initial installation or at a later date. At present, encryption of the database is not reversible. [](https://docs.portainer.io/advanced/db-encryption#docker-standalone) Docker Standalone --------------------------------------------------------------------------------------------- To enable encryption on Docker Standalone, you will first need to create a secret key, then modify your docker run command to mount the secret in the container. ### [](https://docs.portainer.io/advanced/db-encryption#create-a-secret) Create a secret Create a text file on the system running Docker Standalone that is accessible to the Docker executable, yet somewhere secure. For this example, we'll assume the file is called `/root/secrets/portainer`. In this file enter a secret. This will be the key used to encrypt the Portainer database. ### [](https://docs.portainer.io/advanced/db-encryption#mount-the-secret) Mount the secret If Portainer is already running, you will need to stop and remove the Portainer container before continuing: Copy docker stop portainer docker rm portainer To encrypt the database, add a bind mount to the `docker run` command that mounts your secret in `/run/secrets/portainer`: Copy -v /root/secrets/portainer:/run/secrets/portainer Your final `docker run` command may look like this: Copy docker run -d -p 8000:8000 -p 9443:9443 --name portainer \ --restart=always \ -v /var/run/docker.sock:/var/run/docker.sock \ -v portainer_data:/data \ -v /root/secrets/portainer:/run/secrets/portainer \ portainer/portainer-ee:lts When the Portainer container starts, it will encrypt any existing database, or for a fresh install will create a new encrypted database as part of the install process. [](https://docs.portainer.io/advanced/db-encryption#docker-swarm) Docker Swarm ----------------------------------------------------------------------------------- To enable encryption on Docker Swarm, you will first need to create a secret. You will then either update the service to incorporate the new secret (if you have an existing Portainer installation) or edit the compose file used to create the stack to include the secret (if this is a fresh installation of Portainer). ### [](https://docs.portainer.io/advanced/db-encryption#create-a-secret-1) Create a secret On a manager node, you can run the following command to create a secret: Copy echo "This is a secret" | docker secret create portainer - Replace `This is a secret` with your secret. This will create a secret named `portainer`, which will be the key used to encrypt the Portainer database. You can also create a secret in Portainer if you are adding encryption to an existing installation. ### [](https://docs.portainer.io/advanced/db-encryption#existing-installations-update-the-service) Existing installations: Update the service To add encryption to an existing Portainer deployment on Docker Swarm, you can use the following command on a manager node: Copy docker service update \ --secret-add src=portainer,target="/run/secrets/portainer" \ portainer The service will add the new secret and encrypt the database. ### [](https://docs.portainer.io/advanced/db-encryption#new-installations-edit-the-compose-file) New installations: Edit the compose file To install Portainer on Docker Swarm with encryption, you will need to edit the compose file you downloaded as part of the installation process. Add a secrets section to the `portainer` service definition: Copy secrets: - portainer This tells the service to use the `portainer` secret created earlier. In addition, because we created it separately earlier we will need to specify it as `external` so that Docker knows not to create it when creating the stack. To do this we add a `secrets:` definition outside of the `services:` definition for the `portainer` secret: Copy secrets: portainer: external: true With the secret added, your full Portainer stack file may look like this: Copy version: '3.2' services: agent: image: portainer/agent:lts volumes: - /var/run/docker.sock:/var/run/docker.sock - /var/lib/docker/volumes:/var/lib/docker/volumes networks: - agent_network deploy: mode: global placement: constraints: [node.platform.os == linux] portainer: image: portainer/portainer-ee:lts command: -H tcp://tasks.agent:9001 --tlsskipverify ports: - "9443:9443" - "9000:9000" - "8000:8000" volumes: - portainer_data:/data networks: - agent_network deploy: mode: replicated replicas: 1 placement: constraints: [node.role == manager] secrets: - portainer networks: agent_network: driver: overlay attachable: true volumes: portainer_data: secrets: portainer: external: true Save your changes, then use the compose file to deploy your Portainer installation as covered in the Swarm installation instructions. The database will be deployed encrypted as part of the installation process. [](https://docs.portainer.io/advanced/db-encryption#kubernetes) Kubernetes ------------------------------------------------------------------------------- To enable encryption on Kubernetes you will first need to create a secret. You will then mount this secret as a volume in Portainer. ### [](https://docs.portainer.io/advanced/db-encryption#create-a-secret-2) Create a secret From the command line on your Kubernetes cluster, you can run the following command to create your secret: Copy kubectl create secret generic portainer-key --from-literal=secret=IAmASecretKey --namespace portainer Replace `IAmASecretKey` with your secret. This will create a secret named `portainer-key`, which will be the key used to encrypt the Portainer database. ### [](https://docs.portainer.io/advanced/db-encryption#modify-the-yaml-file) Modify the YAML file Once the secret has been created, we need to modify the YAML file to mount the secret as a volume in Portainer. Download the YAML file for your particular deployment and locate the `container` definition for the `portainer` container. It should look something like this: Copy containers: - name: portainer image: "portainer/portainer-ee:sts" imagePullPolicy: Always args: volumeMounts: - name: data mountPath: /data In the `volumeMounts` section, add a definition for the secret created earlier: Copy volumeMounts: - name: data mountPath: /data - name: portainer-key mountPath: /run/secrets/portainer subPath: portainer We also need to add a definition to the `volumes` definition for the `spec`: Copy spec: containers: portainer: ... volumes: - name: portainer-key secret: secretName: portainer-key items: - key: secret path: portainer Save the file, then apply it to your running configuration: Copy kubectl apply -f portainer.yaml Replace `portainer.yaml` with the name of your modified YAML file. [PreviousSecurity and compliance](https://docs.portainer.io/advanced/security) [NextUsing your own SSL certificate with Portainer](https://docs.portainer.io/advanced/ssl) Last updated 3 months ago Was this helpful? --- # Using mTLS with Portainer | Portainer Documentation Mutual TLS (or **mTLS**) is a certificate-based system whereby the client and server (in this case, the Portainer Edge Agent and the Portainer Server) authenticate each other cryptographically via a trusted source (a certificate authority). This can be used as an extra layer of security to protect the communications between the Edge Agent and Portainer. Under this setup, if a third-party system attempts to communicate with the Portainer Server and is not using a certificate signed by the certificate authority it will be rejected. This article will walk you through the process of deploying the Portainer Server and the Edge Agents with mTLS support. mTLS support is only available in Portainer Business Edition. [](https://docs.portainer.io/advanced/mtls#requirements) Requirements -------------------------------------------------------------------------- In order to configure Portainer with mTLS support, you will need the following: * A Portainer Server and a Portainer Edge Agent. * A certificate authority (CA). You can use your own corporate CA or a CA for which you completely control the certificate issuance policy. * The CA certificate for your certificate authority, in PEM format (`mtlsca.crt`). * A domain (or subdomain) you can point to your Portainer Server instance to be specifically used for mTLS. This will be the domain the server certificate is issued for. * A server certificate (`mtlsserver.crt`) and corresponding key (`mtlsserver.key`) issued by your CA for the Portainer Server, in PEM format. Ensure these are issued with `serverAuth` selected for `extendedKeyUsage`. This certificate should have the domain (or subdomain) that will be used for mTLS as the Subject Alternative Name (SAN). * A client certificate (`client.crt`) and corresponding key (`client.key`) issued by your CA for the Edge Agent, in PEM format. Ensure these are issued with `clientAuth` selected for `extendedKeyUsage`. [](https://docs.portainer.io/advanced/mtls#configuring-the-portainer-server) Configuring the Portainer Server ------------------------------------------------------------------------------------------------------------------ To use mTLS with your Edge Agents, the Portainer Server instance must be configured with mTLS support. This can either be done during the initial installation of the Portainer Server instance, or after installation through the [Edge Compute settings](https://docs.portainer.io/admin/settings/edge#mtls-certificate) . ### [](https://docs.portainer.io/advanced/mtls#configure-mtls-during-installation) Configure mTLS during installation When deploying your Portainer Server, you will need to make the CA certificate, server certificate and server key available to Portainer. How you do this will depend on your deployment. #### [](https://docs.portainer.io/advanced/mtls#docker-standalone) Docker Standalone On your Docker host, upload your CA certificate (`mtlsca.crt`), server certificate (`mtlsserver.crt`) and server key (`mtlsserver.key`) into a directory that will be bind mounted into the Portainer container. In this example we assume your certificates are located at `/root/certs`. Modify your `docker run` command to mount the `/root/certs` directory to `/certs` and add the `--mtlscacert`, `--mtlscert`, and `--mtlskey` options: Copy docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always \ -v /var/run/docker.sock:/var/run/docker.sock \ -v portainer_data:/data \ -v /root/certs:/certs \ portainer/portainer-ee:lts \ --mtlscacert /certs/mtlsca.crt \ --mtlscert /certs/mtlsserver.crt \ --mtlskey /certs/mtlsserver.key This will start Portainer using your provided CA and certificates. #### [](https://docs.portainer.io/advanced/mtls#docker-swarm) Docker Swarm To add mTLS certificates to Portainer Server on Docker Swarm during installation, we recommend adding the necessary files as secrets and then referencing those secrets within the YAML used to deploy Portainer. First, upload your CA certificate (`mtlsca.crt`), server certificate (`mtlsserver.crt`) and server key (`mtlsserver.key`) into a directory that will be referenced by the secret creation. In this example we assume your certificates are located at `/root/certs`. Once you have uploaded the files, create your secrets as follows: Copy docker secret create portainer.mtlscacert /root/certs/mtlsca.crt docker secret create portainer.mtlscert /root/certs/mtlsserver.crt docker secret create portainer.mtlskey /root/certs/mtlsserver.key Modify your Portainer YAML file to attach the secrets and add the `--mtlscacert`, `--mtlscert` and `--mtlskey` options: Copy portainer: image: portainer/portainer-ee:lts command: -H tcp://tasks.agent:9001 --tlsskipverify --mtlscacert /run/secrets/portainer.mtlscacert --mtlscert /run/secrets/portainer.mtlscert --mtlskey /run/secrets/portainer.mtlskey ports: - "9443:9443" - "9000:9000" - "8000:8000" volumes: - portainer_data:/data networks: - agent_network deploy: mode: replicated replicas: 1 placement: constraints: [node.role == manager] secrets: - portainer.mtlscacert - portainer.mtlsscert - portainer.mtlskey and to add the `secrets` definitions to include the secrets we just created: Copy secrets: portainer.mtlscacert: external: true portainer.mtlscert: external: true portainer.mtlskey: external: true #### [](https://docs.portainer.io/advanced/mtls#kubernetes-via-helm) Kubernetes (via Helm) If it doesn't already exist, create the `portainer` namespace: Copy kubectl create namespace portainer Next, create a secret containing the CA, certificate and matching private key: Copy kubectl create secret generic portainer-mtls-certs-secret -n portainer \ --from-file=mtlsca.crt=ca.crt \ --from-file=mtlscert.crt=server.crt \ --from-file=mtlskey.key=server.key Replace `ca.crt`, `server.crt` and `server.key` in the above command with the paths to your CA certificate, certificate and matching key respectively. Install Portainer via Helm with the `mtls.existingSecret` parameter set to the name of the secret you just created: NodePort Load Balancer Copy helm install -n portainer portainer portainer/portainer \ --set mtls.existingSecret=portainer-mtls-certs-secret \ --set enterpriseEdition.enabled=true Copy helm install -n portainer portainer portainer/portainer \ --set mtls.existingSecret=portainer-mtls-secret \ --set service.type=LoadBalancer \ --set enterpriseEdition.enabled=true ### [](https://docs.portainer.io/advanced/mtls#configure-mtls-post-installation) Configure mTLS post installation If you already have Portainer Server deployed, you can configure mTLS support through the Portainer UI. As an admin user, from the left menu select **Settings** then **Edge Compute**. Toggle on **Enable Edge Compute features** if it isn't already on and click **Save Settings**. Then scroll down to the **mTLS Certificate** section. ![](https://docs.portainer.io/~gitbook/image?url=https%3A%2F%2Fcontent.gitbook.com%2Fcontent%2FXI7douejaBgpZ6CP2zJf%2Fblobs%2FR8liflDmdth3LUUBcJWR%2F2.18-settings-edge-mtls.png&width=768&dpr=4&quality=100&sign=27cec05e&sv=2) Here you can enable the use of mTLS with the **Use separate mTLS cert** toggle, and upload the CA certificate, server certificate and server key using the buttons for **TLS CA certificate**, **TLS certificate** and **TLS key** respectively. If you add or change the mTLS CA certificate through this method you will need to restart the Portainer Server in order for the change to apply. You should also ensure any Edge Agents that are using mTLS are also updated to use the new CA certificate. [](https://docs.portainer.io/advanced/mtls#deploying-the-edge-agents) Deploying the Edge Agents ---------------------------------------------------------------------------------------------------- Once you have the Portainer Server instance configured to use mTLS, you can then configure your Edge Agent deployments to use it as well. When deploying an Edge Agent you will be provided with a command to run by the Portainer UI. We will take that command and modify it for mTLS support. ### [](https://docs.portainer.io/advanced/mtls#docker-standalone-1) Docker Standalone On your Docker host, upload your CA certificate (`mtlsca.crt`), client certificate (`client.crt`) and client key (`client.key`) into a directory that will be bind mounted into the Edge Agent container. In this example we assume your certificates are located at `/root/certs`. Once the certificates are in place and the secrets created, you can begin to set up your Edge Agent within the Portainer UI. When doing so, remember to use the domain (or subdomain) you chose for mTLS usage (and that the server certificate was issued for) as the Portainer API server URL and tunnel address (if appropriate). When you have completed the Edge Agent setup in the Portainer UI and have your deployment command, modify the command to mount the `/root/certs` directory to `/certs`, change the `EDGE_INSECURE_POLL` option to `0`, and add the `--mtlscacert`, `--mtlscert`, and `--mtlskey` options: Copy docker run -d \ -v /var/run/docker.sock:/var/run/docker.sock \ -v /var/lib/docker/volumes:/var/lib/docker/volumes \ -v /:/host \ -v /root/certs:/certs \ -v portainer_agent_data:/data \ --restart always \ -e EDGE=1 \ -e EDGE_ID=your-edge-id \ -e EDGE_KEY=your-edge-key \ -e EDGE_INSECURE_POLL=0 \ --name portainer_edge_agent \ portainer/agent:lts \ --mtlscacert /certs/mtlsca.crt \ --mtlscert /certs/client.crt \ --mtlskey /certs/client.key Run the command to deploy your Edge Agent with mTLS support. ### [](https://docs.portainer.io/advanced/mtls#docker-swarm-1) Docker Swarm To add mTLS certificates to the Edge Agent, we recommend adding the necessary files as secrets and then referencing those secrets within the YAML used to deploy Portainer. First, upload your CA certificate (`mtlsca.crt`), client certificate (`client.crt`) and client key (`client.key`) into a directory that will be referenced by the secret creation. In this example we assume your certificates are located at `/root/certs`. Once you have uploaded the files, create your secrets as follows: Copy docker secret create portainer.mtlscacert /root/certs/mtlsca.crt docker secret create portainer.mtlscert /root/certs/client.crt docker secret create portainer.mtlskey /root/certs/client.key Once the certificates are in place and the secrets created, you can begin to set up your Edge Agent within the Portainer UI. When doing so, remember to use the domain (or subdomain) you chose for mTLS usage (and that the server certificate was issued for) as the Portainer API server URL and tunnel address (if appropriate). When you have completed the Edge Agent setup in the Portainer UI and have your deployment command, modify the command to change the `EDGE_INSECURE_POLL` option to `0` and add the `--mtlscacert`, `--mtlscert` and `--mtlskey` options, using the secrets we defined above: Copy docker network create \ --driver overlay \ portainer_agent_network; docker service create \ --name portainer_edge_agent \ --network portainer_agent_network \ -e EDGE=1 \ -e EDGE_ID=your-edge-id \ -e EDGE_KEY=your-edge-key \ -e EDGE_INSECURE_POLL=0 \ -e AGENT_CLUSTER_ADDR=tasks.portainer_edge_agent \ --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 \ --mount type=bind,src=//,dst=/host \ --mount type=volume,src=portainer_agent_data,dst=/data \ portainer/agent:lts \ --mtlscacert /run/secrets/portainer.mtlscacert \ --mtlscert /run/secrets/portainer.mtlscert \ --mtlskey /run/secrets/portainer.mtlskey Run the commands to deploy your Edge Agent with mTLS support. ### [](https://docs.portainer.io/advanced/mtls#kubernetes) Kubernetes At present, mTLS support for the Portainer Agent running on a Kubernetes environment is a work in progress. If you require instructions for deploying a Portainer Agent with mTLS on a Kubernetes environment, please [get in touch with our support team](https://docs.portainer.io/#getting-support) . [PreviousUsing your own SSL certificate with Portainer](https://docs.portainer.io/advanced/ssl) [NextStream auth and activity logs to an external provider](https://docs.portainer.io/advanced/siem) Last updated 3 months ago Was this helpful? --- # Privacy Policy | Portainer Documentation You can find our privacy policy [on our website](https://www.portainer.io/legal/privacy-policy) . [PreviousSet up a Linux build environment](https://docs.portainer.io/contribute/build/linux) Was this helpful? --- # Reset the admin user's password | Portainer Documentation If your Portainer admin forgets their password, follow these steps to reset it. There are three methods depending on your Portainer environment. [](https://docs.portainer.io/advanced/reset-admin#method-1-resetting-the-admin-password-if-portainer-runs-as-a-container) Method 1: Resetting the admin password if Portainer runs as a container ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ You would typically use this method if you run the Portainer Server on Docker Standalone. First, go to our [reset password container helper](https://github.com/portainer/helper-reset-password) in GitHub, then stop the Portainer container by running this command: Copy docker stop "id-portainer-container" Next, run the helper using the following command (you'll need to mount the Portainer data volume): If your Portainer data volume has a different name than `portainer_data` or you are using a bind mount for your data volume, you will need to adjust the mount in the below `docker run` command to suit your path. Copy docker pull portainer/helper-reset-password docker run --rm -v portainer_data:/data portainer/helper-reset-password If successful, the output should look like this: Copy 2020/06/04 00:13:58 Password successfully updated for user: admin 2020/06/04 00:13:58 Use the following password to login: &_4#\3^5V8vLTd)E"NWiJBs26G*9HPl1 If the helper is unable to find an admin user to update, it will create a new one for you. If the username `admin` is already used, it will create a user named `admin-[randomstring]`: Copy 2022/08/10 07:36:33 [WARN] Unable to retrieve user with ID 1, will try to create, err: object not found inside the database 2022/08/10 07:36:33 Admin user admin-u0512b3f0v4dqk7o successfully created 2022/08/10 07:36:33 Use the following password to login: Sr#]YL_6D0k8Pd{pA9^|}F32j5J4I=av Finally, use this command to start the Portainer container then try logging in with the new password: Copy docker start "id-portainer-container" [](https://docs.portainer.io/advanced/reset-admin#method-2-resetting-the-admin-password-if-portainer-runs-as-a-stack-service) Method 2: Resetting the admin password if Portainer runs as a stack/service -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You would typically use this method if you run the Portainer Server on Docker Swarm. First, scale the Portainer service to zero using this command: Copy docker service scale portainer_portainer=0 Next, run the [reset password container helper](https://github.com/portainer/helper-reset-password) using the same bind-mount/volume as the data volume: If your Portainer data volume has a different name than `portainer_data` or you are using a bind mount for your data volume, you will need to adjust the mount in the below `docker run` command to suit your path. Copy docker pull portainer/helper-reset-password docker run --rm -v portainer_portainer_data:/data portainer/helper-reset-password If successful, the output should look like this: Copy 2020/06/04 00:13:58 Password successfully updated for user: admin 2020/06/04 00:13:58 Use the following password to login: &_4#\3^5V8vLTd)E"NWiJBs26G*9HPl1 If the helper is unable to find an admin user to update, it will create a new one for you. If the username `admin` is already used, it will create a user named `admin-[randomstring]`: Copy 2022/08/10 07:36:33 [WARN] Unable to retrieve user with ID 1, will try to create, err: object not found inside the database 2022/08/10 07:36:33 Admin user admin-u0512b3f0v4dqk7o successfully created 2022/08/10 07:36:33 Use the following password to login: Sr#]YL_6D0k8Pd{pA9^|}F32j5J4I=av Finally, start up the Portainer service scaling using this command then try logging in with the new password: Copy docker service scale portainer_portainer=1 [](https://docs.portainer.io/advanced/reset-admin#method-3-resetting-the-admin-password-if-portainer-is-deployed-in-a-kubernetes-cluster) Method 3: Resetting the admin password if Portainer is deployed in a Kubernetes cluster -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- You would typically use this method if you run the Portainer Server on a Kubernetes cluster. First, scale the Portainer deployment to zero using this command: Copy kubectl scale deploy portainer --replicas=0 -n portainer Next, create a pod using the [reset password container helper](https://github.com/portainer/helper-reset-password) image and mount the Portainer data volume. Create a pod YAML file using the command below: You may need to change the YAML below to match your Portainer deployment (for example if using a different `claimName`). Copy cat > passreset.yml<< EOF apiVersion: v1 kind: Pod metadata: name: passreset spec: volumes: - name: data persistentVolumeClaim: claimName: portainer containers: - name: passreset image: portainer/helper-reset-password volumeMounts: - mountPath: "/data" name: data restartPolicy: Never EOF Create the password reset pod using the command below: Copy kubectl apply -f passreset.yml -n portainer Once the new pod is created and transitions into a completed state, you can see the new password in the pod logs: Copy kubectl logs passreset -n portainer If successful, the output should look something like this: Copy 2020/06/04 00:13:58 Password successfully updated for user: admin 2020/06/04 00:13:58 Use the following password to login: &_4#\3^5V8vLTd)E"NWiJBs26G*9HPl1 Finally, scale up the Portainer deployment using this command then try logging in with the new password: Copy kubectl scale deploy portainer --replicas=1 -n portainer You can delete the password reset pod using the below command: Copy kubectl delete pod passreset -n portainer [PreviousAccess control](https://docs.portainer.io/advanced/access-control) [NextSecurity and compliance](https://docs.portainer.io/advanced/security) Was this helpful? --- # App templates | Portainer Documentation You can deploy containers and services using Portainer's set of built-in app templates, or replace them with your own set of templates. [Build and host your own app templates](https://docs.portainer.io/advanced/app-templates/build) [App template JSON format](https://docs.portainer.io/advanced/app-templates/format) [PreviousCLI configuration options](https://docs.portainer.io/advanced/cli) [NextBuild and host your own app templates](https://docs.portainer.io/advanced/app-templates/build) Was this helpful? --- # Build instructions | Portainer Documentation This article explains how to set up your local development environment so you can contribute to the Portainer codebase. Make sure you have installed the dependencies for this project on your [Mac](https://docs.portainer.io/contribute/build/mac) or [Linux](https://docs.portainer.io/contribute/build/linux) machine before continuing. Windows is currently not supported by the Portainer development environment. [](https://docs.portainer.io/contribute/build#instructions) Instructions ----------------------------------------------------------------------------- Navigate to the folder where you will store Portainer project code. This can be anywhere such as on your desktop or in your downloads folder. Now, download the Portainer project: Copy git clone https://github.com/portainer/portainer.git Next, navigate into the Portainer project you downloaded: Copy cd portainer Install the development dependencies: Copy make deps And finally, build and run the project: Copy make dev You should now be able to access Portainer at `https://localhost:9443` and UI dev server runs on `http://localhost:8999`. For additional commands, run `make help`. The frontend application will update and refresh when you save your changes to any of the sources. [](https://docs.portainer.io/contribute/build#contribution-guidelines) Contribution Guidelines --------------------------------------------------------------------------------------------------- When contributing to the Portainer codebase, please follow [our contribution guidelines](https://github.com/portainer/portainer/blob/develop/CONTRIBUTING.md) . [PreviousContribute](https://docs.portainer.io/contribute/contribute) [NextSet up a macOS build environment](https://docs.portainer.io/contribute/build/mac) Was this helpful? --- # Contribute | Portainer Documentation We value contributions from the Portainer community and encourage developers to propose fixes, improvements, and new ideas. The following guidelines outline our engineering workflows, please review these before making a contribution to ensure any changes can be integrated smoothly. [](https://docs.portainer.io/contribute/contribute#contributing-to-the-portainer-ce-codebase) Contributing to the Portainer CE codebase -------------------------------------------------------------------------------------------------------------------------------------------- The Portainer CE codebase is available in [GitHub](https://github.com/portainer/portainer) . Please follow our [build instructions](https://docs.portainer.io/contribute/build) and the following guidelines when making a contribution. ### [](https://docs.portainer.io/contribute/contribute#repository-structure) Repository structure * Our main development occurs in private repositories, which are mirrored to public GitHub repos (e.g. [portainer/portainer](https://github.com/portainer/portainer/) ). * The `develop` and `release/*` branches in public repositories are **read-only**: merges into these branches are blocked to preserve synchronisation with our internal repositories. * We maintain a separate `community` branch in each public repository to accept and review external contributions. ### [](https://docs.portainer.io/contribute/contribute#contribution-process) Contribution process 1. **Fork the repository** * Create your own fork of the relevant Portainer public repository. 2. **Create a feature branch** * Base your changes on the current `develop` branch (not `main`, `release/*`, or `community`). This ensures you are working off the latest version of the codebase. 3. **Submit a Pull Request (PR)** * Open your PR against the `develop` branch. * Portainer engineers will update the target branch to `community` when the contribution is ready to be merged. 4. **Review and feedback** * Contributions will be reviewed by Portainer engineers. * We may request changes to align with coding standards, tests, or design decisions. * In some cases, we may adapt or refactor a contribution before merging. 5. **Integration** * Once approved and merged into `community`, Portainer engineers will cherry-pick contributions into the upstream private repository. * These changes will then flow into `develop` and subsequent releases through our normal sync process. * Not all contributions will be integrated upstream. Decisions will be based on roadmap alignment, technical fit, and quality. ### [](https://docs.portainer.io/contribute/contribute#contribution-expectations) Contribution expectations * **Coding standards**: Please follow existing project style and conventions. * **Tests**: Include tests where applicable. Contributions without tests may be delayed. * **Documentation**: Update relevant docs (e.g. README, usage notes) when changing functionality. * **Scope**: Focus on well-defined features, fixes, or improvements. Large architectural changes should be discussed in an issue first. ### [](https://docs.portainer.io/contribute/contribute#communication) Communication * For significant changes or new features, use [GitHub Discussions](https://github.com/orgs/portainer/discussions/categories/ideas) to start a discussion before starting the change. * PR discussions are the best place for clarifications on specific contributions. [](https://docs.portainer.io/contribute/contribute#reporting-bugs) Reporting bugs -------------------------------------------------------------------------------------- If you find a bug, [please tell us](https://github.com/portainer/portainer/issues/new?assignees=&labels=bug%2Fneed-confirmation%2C+kind%2Fbug&template=Bug_report.md&title=) so we can triage it. All bugs are managed in the [GitHub issues repo](https://github.com/portainer/portainer/issues) . When you click through, our template makes it easy to record all of the details. Check the list of [open bugs](https://github.com/portainer/portainer/labels/kind%2Fbug) before reporting to avoid duplicates. [This article](https://docs.portainer.io/faqs/contributing/how-do-you-decide-which-bugs-and-features-to-work-on-first) covers how we prioritize bug fixes. [](https://docs.portainer.io/contribute/contribute#feature-requests) Feature requests ------------------------------------------------------------------------------------------ You can request new features by posting an Idea in our [GitHub Discussions](https://github.com/orgs/portainer/discussions/categories/ideas) forum. Please check to see if someone has already requested the feature you want, and give it an upvote if so. Learn how we prioritize feature development [in this article](https://docs.portainer.io/faqs/contributing/how-do-you-decide-which-bugs-and-features-to-work-on-first) . [PreviousAPI usage examples](https://docs.portainer.io/api/examples) [NextBuild instructions](https://docs.portainer.io/contribute/build) Last updated 1 month ago Was this helpful? --- # Stream auth and activity logs to an external provider | Portainer Documentation This is an experimental feature. With Portainer 2.20 and later, you can configure the streaming of Portainer's authentication and activity logs to an external Security Information and Event Management (SIEM) system in Syslog format. This is done via CLI flags when starting the Portainer container. [](https://docs.portainer.io/advanced/siem#available-cli-flags) Available CLI flags ---------------------------------------------------------------------------------------- Flag Description `--syslog-address` Syslog Address to stream authentication and activity logs. FQDN or IP Address only. `--syslog-port` Syslog Port for the address above. Defaults to `514`. `--syslog-protocol` Syslog Protocol to send logs to the Syslog Server. Supported values are `udp`, `tcp`, or `tcp+tls`. Defaults to `udp`. `--syslog-format` Syslog Format to be used. Supported values are `rfc3164` or `rfc5424`. Defaults to `rfc5424.` `--syslog-source-hostname` The hostname value that will be shown in the Syslog server in the messages. Defaults to `portainer`. `--syslog-insecure-skip-verify` Disable TLS server verification when using `tcp+tls` protocol. Should only be enabled for testing. Defaults to `false`. `--syslog-ca-cert` The path to the trusted CA used by the Syslog server. Defaults to `/syslog/certs/ca.pem`. `--syslog-cert` The path to the client certificate that is used to authenticate to the Syslog server via mTLS. Defaults to `/syslog/certs/cert.pem`. `--syslog-key` The path to the client key that is used to authenticate to the Syslog server via mTLS. Defaults to `/syslog/certs/key.pem`. [](https://docs.portainer.io/advanced/siem#example-usage) Example usage ---------------------------------------------------------------------------- The following is an example `docker run` command to start Portainer using the above options to stream logs to a SIEM provider at `syslog.mydomain.com` on UDP port `514`. As the flags are Portainer options, they must be specified after the image specification. Copy docker run -d -p 8000:8000 -p 9443:9443 \ --name portainer \ --restart=always \ -v /var/run/docker.sock:/var/run/docker.sock \ -v portainer_data:/data \ portainer/portainer-ee:lts \ --syslog-addr=syslog.mydomain.com \ --syslog-port=514 \ --syslog-source-hostname="my-portainer-instance" [PreviousUsing mTLS with Portainer](https://docs.portainer.io/advanced/mtls) [NextUsing Portainer with reverse proxies](https://docs.portainer.io/advanced/reverse-proxy) Last updated 3 months ago Was this helpful? ---