Install Portainer on Docker: Step by Step Setup Guide

How do you install Portainer and what does it do?

Portainer is a web interface for Docker. To install Portainer, you run it as a container on your own server and open it in a browser. From there you manage containers, images, volumes, networks and Compose stacks without typing every command by hand.

We are a digital marketing and web team, not a hosting company. So our walkthrough follows the official Portainer and Docker documentation. So we give the commands exactly as the docs show them. We say "current stable release" instead of a version number, because versions change often.

First you will install Portainer, then we will talk about the security risk, and at the end we explain when to hand this job to your hosting provider. Also, we do not teach Docker itself here. For the basics, read our what is Docker guide.

This guide suits site owners who run their own VPS, developers with a few containers, and teams that want visibility for people who do not know Docker well. If you have never used a command line, start small. The interface does not replace the commands, so you still need to understand them.

What is the difference between Portainer Community and Business?

Portainer comes in two editions: the free Community Edition (CE) and the paid Business Edition (BE). If you manage one server on a small VPS, CE is often enough. Still, you should know the gap, because some features exist only in BE.

We could confirm the differences below in the official docs. That said, we limit the comparison to what the docs say. For pricing and license terms, check Portainer's own site.

The table comes from the backup and stack pages of the Portainer docs. For any feature not on the list, we make no claim.

What should you check before you install Portainer?

To install Portainer you need a working Docker engine and admin rights on the server. First run docker version and confirm that Docker answers. If Docker is missing, install it from the official docs before you install Portainer. However, this article does not cover that step.

Also prepare the following:

• Know your server's IP address and how you log in (an SSH key).
• Check which ports your firewall leaves open.
• Make sure your server backup works, so you do not lose Portainer data.
• Decide how you will reach the panel: direct IP, SSH tunnel or a domain name.

If you plan to use a domain, our DNS lookup tool shows whether the record points to the right IP. You can confirm the public address of your server with our IP lookup tool.

How do you install Portainer step by step?

The Linux install in the official docs has two commands. The first one creates a persistent Docker volume for Portainer data. Next, the second one starts the Portainer container with that volume and the Docker socket. Here are the example commands:

docker volume create portainer_data

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

When the command finishes, run docker ps to see the container. Then open an address like https://203.0.113.10:9443 in your browser. The IP is only an example, so type your own server's address.

Your browser will show a certificate warning on first visit. According to the docs, Portainer protects port 9443 with a self-signed certificate it generates by default. We explain that warning in a later section, because it confuses many people.

To see which ports the server listens on, run ss -tlnp. Then you will find port 9443 in the output. If you spot a port you did not expect, find out why. Also, every open port needs a firewall decision.

What does each parameter in the install command mean?

Copying a command is easy. However, knowing each part makes debugging faster. The list below explains only the parameters in the official command.

• -d: runs the container in the background.
• -p 9443:9443: publishes the port that serves the interface over HTTPS.
• -p 8000:8000: per the docs, this is for the Edge Agent tunnel server and it is optional.
• --name portainer: gives the container a familiar name.
• --restart=always: starts the container again when Docker or the server restarts.
• -v portainer_data:/data: keeps Portainer's users, settings and environments on a persistent volume.
• -v /var/run/docker.sock:/var/run/docker.sock: gives Portainer access to manage the local Docker.
• portainer/portainer-ce:lts: the CE image and tag the official docs use.

If you will not use the Edge Agent, you do not have to publish port 8000. An unneeded open port is an unneeded attack surface.

Why does docker.sock matter so much for security?

The docker.sock file is a Unix socket that opens the Docker engine API. In other words, any program that reaches this socket can do everything Docker can do. When you give Portainer the socket, you give it the power to manage every container on the server.

Docker's security documentation is direct about this. It says that running Docker means running a daemon that needs root privileges, unless you opt in to rootless mode. The same page also says only trusted users should control the daemon. The reason is that Docker can share host directories with a container without restriction.

In practice, someone who gets into the Portainer panel can effectively take over the server. For example, they can start a new container and mount the server's file system inside it. So treat the Portainer admin account like the server's root password. We suggest reading the official Docker security page before you start.

How do you create the first admin account in Portainer?

When the container runs, open the address on port 9443 and the first setup screen appears. Per the docs, the first user is called admin by default, and you can change the name. The password must have at least 12 characters and meet the listed requirements.

Setup also asks for a setup token. According to the official docs, you find the token in the Portainer server logs, on the line that contains setup_token=. This command shows the log:

docker logs portainer

After you create the account, a wizard starts. The docs say the installation detects your local environment automatically and sets it up for you. Later you can also add more environments if you wish.

So keep the password in a password manager. Do not choose a guessable one, because this account is the key to your whole Docker setup.

Is it safe to expose port 9443 to the internet?

We advise against leaving port 9443 open to everyone. For example, any service with a login page becomes a target for password guessing. Behind Portainer sits an account that controls the whole server, so the cost of a mistake is high.

For a safer setup, consider these options in order:

1. Bind Portainer to the local interface only and log in through an SSH tunnel.
2. Open the port only to known, fixed IP addresses.
3. Put it behind a VPN.
4. If you truly must expose it, use a valid certificate and a strong password.

For the first option, replace -p 9443:9443 in the run command with -p 127.0.0.1:9443:9443. Then open this tunnel from your own computer:

ssh -L 9443:127.0.0.1:9443 user@203.0.113.10

Now browse to https://localhost:9443. Docker adds its own network rules for published ports. So test from outside that your firewall rule really works. For the firewall, see our CSF firewall guide. For brute force attempts, see our Fail2ban guide.

What does the Portainer certificate warning mean and how do you fix it?

The browser warning says that no known authority signed the certificate. Portainer generates a self-signed certificate on first start. In short, the traffic is still encrypted. However, your browser cannot prove that the server on the other end is really yours.

To remove the warning for good, the docs say you can set a custom certificate during or after installation. Also, if you use a domain name, a valid certificate is the cleanest fix. We explained the concept in our SSL certificate guide.

After you install the certificate, use our SSL checker to confirm that the chain and the expiry date look right. If you log in through an SSH tunnel, you can accept the warning on purpose, because the traffic already runs inside the tunnel.

How do you manage containers with Portainer?

The container list is one of Portainer's main screens. For each container you see the name, state, image and published ports. Then you can select a row and start, stop, restart or remove it.

The container detail page offers more:

• Logs: you read the container output in the browser.
• Stats: you watch CPU, memory and network use.
• Console: you open a shell inside the container.
• Inspect: you see environment variables, mounted volumes and networks.

These screens are the visual twin of docker ps, docker logs and docker stats. So anyone who knows the commands learns Portainer fast.

Note that the console feature lets a user step inside a container. Grant that right only to people you trust.

You also see the restart policy on the detail screen. For example, unless-stopped or always may be selected. That tells you which services come back on their own after a server restart.

How do you manage images, volumes and networks in Portainer?

On the images screen you list the images on the server, pull new ones and clean up unused ones. Unused images fill the disk, so regular cleanup pays off. Before you delete, check which container uses which image.

The volumes screen is the most critical one, because persistent data such as databases lives in volumes. If you delete a volume, its data does not come back. For example, do not delete a volume just because its database container is stopped. Take a backup first.

Volumes come in two kinds. Docker manages a named volume. A bind mount links a specific folder on the server to the container. In the Portainer install we use a named volume, because you do not have to track its path by hand. Still, plan the backup of each kind separately.

On the networks screen you see Docker networks and which container joins which one. Putting containers that must talk to each other on the same network is usually better than publishing extra ports. In other words, keep the app and its database on one network instead of opening the database port to the internet.

To set up database containers, read our PostgreSQL and MySQL in Docker guide.

How do you create a Compose stack in Portainer?

A stack lets you define several services in one Compose file and manage them together. In Portainer you add a new stack from the Stacks menu. The official docs list four deployment methods for Docker Standalone.

• Web editor: you type the Compose content straight into the interface.
• Upload: you upload a stack.yml file from your computer.
• Git repository: you keep the Compose file in Git and deploy from there.
• Custom template: you use a stack template you saved earlier.

The docs also say you can define environment variables with every method. You enter them one by one or load them from an .env file. In the Compose file you use them as ${VARIABLE_NAME}. So the Compose file stays the same and you do not have to write passwords into it.

A small example stack looks like this. The address and values are examples:

services:
  web:
    image: nginx:stable
    ports:
      - "127.0.0.1:8080:80"
    restart: unless-stopped

We do not teach Compose syntax here. Our database guide above is a good place to start.

Can Portainer also manage Docker Swarm and Kubernetes?

Portainer is not limited to a single Docker host. It also offers install guides for Swarm and Kubernetes environments. This article focuses on single server Docker. Swarm and Kubernetes need their own, broader planning.

On architecture, we could confirm this from the docs: Portainer has two parts, the Portainer Server and the Portainer Agent. Both run as lightweight containers on your existing container infrastructure. The Server needs persistent data, while the Agent is stateless.

There are two options for remote environments. With the classic Agent, the Server connects to the Agent. With the Edge Agent, only the remote environment needs to reach the Server. The docs describe the Edge Agent as the recommended choice for most internet connected setups.

If you manage a single VPS, you do not need any of this. Also, if you move toward a multi server cluster, expert help is often cheaper in the end.

For the Edge Agent, you should understand the role of port 8000. The docs tie this port to the Edge Agent tunnel server. So if you run one server without an Edge Agent, you do not need to open it.

How do you update and back up Portainer?

An update means stopping and removing the old container, pulling the new image and starting the container again with the same volume. Your settings stay in place, because the data lives in the portainer_data volume. The docs also strongly advise a backup first.

The official update steps look like this:

docker stop portainer
docker rm portainer
docker pull portainer/portainer-ce:lts
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

If you published the port on 127.0.0.1 during install, use the same form in the update. Otherwise the port opens to the internet again. According to the docs, if you use agents, the Agent version must match the Server version.

For a backup, open the Settings menu and find the "Back up Portainer" section. In CE you download the backup file in the browser, and you can encrypt it with a password. One key limit: this backup covers only the Portainer configuration. It does not cover your containers, stacks or volume contents. For your data, see our website backup strategy guide.

To restore, the docs ask for a fresh Portainer instance with an empty data volume. On the first setup screen you choose to restore from backup. If the backup has a password, you must enter it. So keep that password somewhere safe.

Pick a quiet hour on a weekday for the update. While the container is stopped, the panel is unreachable. Your app containers keep running, but a maintenance window is still a good habit.

Portainer or the command line: which should you choose?

They are not rivals, because both manage the same Docker engine. Portainer gives you visibility and ease. The command line gives you speed, automation and repeatability. Your choice depends on who does the work and how often.

In short, if your team has people new to Docker, Portainer adds value. In a one person setup that runs on scripts, an extra panel may be needless weight.

In practice, many teams use both. They watch daily status in Portainer and run repeated jobs from the command line. So the real question is not Portainer or the command line. It is which tool fits which job.

What problems do people hit when they install Portainer?

Most problems come from ports, networking or persistence. The list below gathers common symptoms and the first place to look. All of it rests on general Docker logic, so the exact fix may differ on your server.

• The page does not open: run docker ps to check that the container runs and the port mapping is right.
• The port is already in use: another service may hold it, so change the mapping.
• No access from outside: check your provider's firewall and the rules on the server.
• A setup token prompt appears: look for the setup_token= line in the docker logs portainer output.
• Settings disappeared: you may have started the container without the volume.

If you cannot find the cause, reading the container log is the first step. When you study the server network, our VPS vs cloud server guide also reminds you which layer does what.

How do you try Portainer in a test environment first?

Trying it on your own computer or on an empty test server is the safest way before you touch a live one. That way you see what the commands do, and a mistake harms nothing. You do not need to rent a separate VPS. A computer that runs Docker is enough.

Follow this order when you install Portainer for a test:

1. Confirm that Docker runs.
2. Start Portainer bound to the local interface only.
3. Create the admin account and look around the interface.
4. Start and stop a harmless container and read its logs.
5. Remove Portainer and delete its volume for a clean start.

This trial gives you two things when you install Portainer for the first time. First, you do not learn which button deletes what on live data. Second, you have run the install command yourself once, so you hesitate less on the live server.

How do you deploy a sample app with Portainer?

A sample scenario makes the logic clear. The flow below shows how to deploy a simple web service as a stack. Names and values are examples, so change them for your own app.

1. Open the Stacks section in the left menu and add a new stack.
2. Give the stack a name such as sample-web.
3. Paste the Compose content into the web editor.
4. Add environment variables if needed. Put passwords here, not in the file.
5. Press the deploy button and watch the state in the container list.

When the deployment ends, you see the new service in the container list. If the service does not start, the log screen is your first stop. You can also stop or delete the stack from the same screen.

In other words, it is the visual twin of the docker compose up job you do on the command line. However, do not move a live store this way on the first try. Rehearse in a test environment first.

Do you need a domain name and a reverse proxy for Portainer?

It is not required, but some teams prefer to reach the panel through a domain. In that case you put a reverse proxy in front of Portainer. A reverse proxy takes the incoming request and passes it to the service behind it.

The benefit is that you manage one valid certificate in one place. The drawback is an extra component and an extra point of failure. So the panel is easier to open, but the attack surface grows too.

Also, you should set up the reverse proxy by the guidance in Portainer's own docs. A wrong setting either never opens the panel or opens it more than you intend. We give no proxy configuration here, because details change between versions and we do not want to print a setup we cannot confirm.

To understand the certificate side, read the SSL guide above. When you check your domain record, our WHOIS lookup tool helps.

Which security mistakes do people make when they install Portainer?

Most mistakes come from haste, not from lack of knowledge. For example, you see the panel running and call the job finished. Yet the real work starts with limiting access.

• Leaving port 9443 open to the whole internet.
• Choosing an easy to guess admin password.
• Publishing port 8000 even though you do not use it.
• Never downloading the configuration backup.
• Postponing updates for months.
• Mounting the Docker socket into other containers without need.

None of these is hard to avoid. However, each one alone puts your server at risk. So we suggest you review the list again after the install.

How do you remove Portainer when you no longer need it?

Removing Portainer means stopping and deleting the container. Your other containers are not affected, because they run on their own in the Docker engine. We again suggest a backup first.

docker stop portainer
docker rm portainer

After these two commands the panel is gone. The configuration data stays in the portainer_data volume. If you no longer need it, delete the volume separately. But check the contents first, because there is no way back.

Then close the port rules you opened for Portainer in the firewall. That way no needless open door stays on the server.

When should you not install Portainer yourself?

Installing Portainer brings root level access and security responsibility on the server. In the cases below, it is wiser to leave the job to your hosting provider or an experienced system administrator.

• A live store runs on the server and you have no backup.
• You use shared hosting, where Docker and socket access are usually not available.
• Firewalls, SSH and certificates are new to you.
• Your provider offers a managed service, so you can share the responsibility.
• The panel must be reachable from the internet and you cannot configure that safely.

This limit is not a weakness. A badly set up admin panel is riskier than none at all. If you want to choose hosting from scratch, take a look at our how to choose web hosting guide.

What should you do after you install Portainer?

When the install ends, half the work is done. The checklist below gathers what you must do to keep the panel safe over time. Tick each item one by one.

1. Is the admin password strong and saved in a password manager?
2. Is port 9443 open only to the addresses that need it, or do you use an SSH tunnel?
3. Have you closed port 8000 if you do not use the Edge Agent?
4. Do you reach the panel with a valid certificate?
5. Did you download the Portainer configuration backup?
6. Is there a regular reminder in your calendar for updates?
7. Did you remove access for users who no longer need it?

For general web security, our OWASP Top 10 guide helps. To deploy an app to a VPS, see our Next.js VPS deployment guide. In the end, you can install Portainer quickly, but running it safely takes discipline.

Make it a habit to rerun the checklist every three months. Servers change over time: new users appear, firewall rules pile up and updates get skipped. A regular review catches small problems before they grow.

What steps should you follow to install Portainer in short?

In short, go in order: verify Docker, create the volume, start the Portainer container, open the admin account with the setup token and limit access. Then try container, volume and stack management.

Using the docs as your source protects you when versions change. We took the commands in this article from the official pages. We did not write any command or value we could not confirm. Before you start, read the Portainer Linux install page once more, and for updates the upgrade page.

One last reminder: we are not a hosting company, and this guide does not mean we run your server. The commands rest on official sources, but your server may differ. Whenever you doubt a step, ask your hosting provider's support and take a backup before you change anything.