How to Use Portainer to Manage Docker Containers (Step-by-Step)

Ferramentas & Produtividade · By · Published on · Updated on · 8 min read

Monitor with terminal in focus and a blurred list of services
Screen showing a terminal and service list, illustrating container management Photo: Brett Sayles / Pexels

This guide shows, in practice, how to use Portainer to manage Docker containers: from installation to deploying stacks, controlling volumes and networks, viewing logs, and securing access. In a few steps you'll have a web UI to operate local or remote hosts with fewer commands and better security.

What Portainer is and when it helps

Portainer is a web UI that simplifies administration of Docker environments. It reduces errors in operational tasks and standardizes deployments via the UI or stacks (Compose).

It's useful when your team needs:

- View containers, volumes, and networks centrally.

- Standardize deployments with Compose without relying only on the CLI.

- Manage multiple local and remote hosts.

If you're still deciding whether to use containers instead of VMs, see the practical comparison Docker vs virtual machines for HA.

Prerequisites and test environment

Before you start, make sure you have:

- A host with Docker Engine installed and sudo access.

- Network ports open: 9443/TCP for the UI; 9001/TCP for the remote Agent.

- An up-to-date browser to access the web UI.

- Optional: a second Docker host to test the remote Agent.

Note: mapping /var/run/docker.sock into containers gives administrative access to Docker. Use this only on trusted hosts and apply access controls at the network and system level.

1) Install Portainer CE on the Docker host

The minimal install uses a persistent volume for Portainer data and exposes the secure interface on port 9443. Requires root or sudo access.

Run the commands below on a host with Docker installed. Wait for the container to start and verify that port 9443 is reachable on your local network.

# 1) Criar volume persistente para dados do Portainer
sudo docker volume create portainer_data

# 2) Subir o Portainer CE com HTTPS (9443)
sudo docker run -d \
  -p 9443:9443 \
  --name portainer \
  --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

# 3) Verificar status
sudo docker ps --filter name=portainer
# Acesse https://SEU_HOST:9443 no navegador (certificado pode ser autoassinado).

2) First access and creating the admin user

Open https://YOUR_HOST:9443 in your browser. On the first screen, set the administrator username and password.

Then choose the type of environment to manage. To start, select the local Docker (Local). You will see the dashboard with containers, images, volumes, and networks.

Initial best practices:

- Create a strong password and store it in a password manager.

- Disable public ports you don't need. Prefer exposing the UI via VPN or a secure tunnel.

- Create tags and environment groups to organize hosts.

3) Connecting remote hosts with the Portainer Agent

To manage remote Docker servers, install the Portainer Agent on each host and connect them from the UI. Open port 9001/TCP in the firewall and ensure only Portainer can access it.

On the remote host, run the Agent. Then in Portainer, add a new environment of type Agent and provide the remote host address:9001.

# No host REMOTO (com Docker instalado)
sudo 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:latest

# Após subir, no Portainer UI: Environments > Add environment > Agent
# Informe: tcp://IP_DO_HOST_REMOTO:9001

4) Deploying containers and stacks (Compose)

You can deploy individual containers or stacks using Compose files. Stacks make it easier to version and replicate configurations across environments.

Common flow:

- Create a stack, paste the Compose YAML, adjust variables, and deploy.

- Parameterize variables with a .env and use Secrets for credentials.

- Validate logs and service health after deploy.

The table below helps locate typical UI actions and their CLI equivalents.

Task Where in the UI CLI equivalent
Run single container Containers > Add container docker run
Deploy Compose stack Stacks > Add stack docker compose up -d
Map port/volume Container/stack form -p / -v
View logs Container > Logs docker logs -f
Restart/scale Container/Stack > Actions docker restart / compose scale 
# Exemplo de stack (Compose v3+): Web + Redis
a version: "3.8"
services:
  web:
    image: nginx:alpine
    ports:
      - "8080:80"
    volumes:
      - web_content:/usr/share/nginx/html:ro
    depends_on:
      - cache
  cache:
    image: redis:7-alpine
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - redis_data:/data
volumes:
  web_content: {}
  redis_data: {}

Volumes, networks, variables and security in practice

Volumes: prefer named volumes for persistence. For backups, copy data off-host or periodically archive the volume.

Networks: use project-specific bridge networks to isolate traffic between services. Avoid sharing networks unless necessary.

Variables and secrets: store credentials as Secrets and use environment variables for parameters. Do not bake passwords into images.

Security:

- Restrict access to the UI (9443) using VPN, IP allowlist, or a reverse proxy.

- Enable HTTPS and avoid exposing port 9001 publicly.

- Review who can access the Docker socket and the host.

Automation: once you master the basics, connect your deploys to CI/CD pipelines. See the referenced CI/CD guide for examples.

Structured logs help a lot with diagnostics. If you don't yet standardize logs, consult the guide on structured logs (JSON) and request correlation.

# Exemplos úteis (executar no host conforme seu ambiente)

# Backup simples do volume do Portainer (gera arquivo no diretório atual)
sudo docker run --rm \
  -v portainer_data:/data \
  -v "$(pwd)":/backup \
  alpine sh -c "tar czf /backup/portainer_data.tgz -C / data"

# Atualizar o Portainer mantendo os dados
sudo docker pull portainer/portainer-ce:latest
sudo docker stop portainer && sudo docker rm portainer
sudo docker run -d -p 9443:9443 \
  --name portainer --restart=always \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  portainer/portainer-ce:latest

Environment checks and common troubleshooting

After installing and configuring, validate that everything is healthy:

- The UI opens at https://YOUR_HOST:9443 without critical errors.

- You see the host's containers, volumes, and networks in Local.

- The remote Agent appears in Environments with status up.

- Test container logs do not show recurring failures.

Common issues and fixes:

- Port 9443/9001 blocked: open it in the firewall and cloud provider.

- Permissions on the Docker socket: the process needs access to /var/run/docker.sock.

- DNS and image pulls: verify the host's external network.

- Self-signed certificate: add a temporary exception or use a TLS-terminating proxy with a valid cert.

- On WSL2/desktop, confirm the correct host IP.

For operational maturity and audit of deploy changes, study deployment process checklists and runbooks as part of your operations practice.

# Verificações rápidas
sudo docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" | sed -n '1,10p'

# Logs do Portainer (últimas 100 linhas)
sudo docker logs --tail=100 portainer

# Testar conectividade com Agent remoto (da máquina do Portainer)
# Substitua IP_PEER pelo endereço do host remoto
nc -vz IP_PEER 9001 || telnet IP_PEER 9001 || echo "Falha na conexão"

Frequently asked questions

Can I use Portainer in production?

Yes—many teams use it to operate and standardize environments. The decision depends on your security, governance, and automation requirements. Restrict UI access, enable HTTPS and network limits, and test in a staging environment before broad adoption.

Does Portainer replace docker-compose?

No. Portainer manages stacks based on Compose and makes deploying via the UI easier. You still use the same YAML files. The benefit is better visibility, parameterization, and versioning with less friction in daily operations.

How do I protect access to the Docker socket?

Avoid exposing the socket over the network. Mount it only locally for Portainer and restrict who can access the host. Apply least-privilege principles, keep the system updated, and regularly audit accounts and keys.

Do I need Kubernetes to use Portainer?

No. Portainer works well with plain Docker. If you later migrate to Kubernetes, Portainer also supports it, but you can start and operate with Docker alone without issues.

How do I back up Portainer data?

Data is stored in the mapped volume at /data. Back up that volume regularly by copying it to external storage. You can use a temporary container to compress it or any backup tool suitable for your environment.

Can I integrate Portainer with CI/CD?

Yes. You can trigger stack deploys via automation or scripts that update images and restart services. Plan variables, secrets, and environment promotion. Use your CI/CD patterns to coordinate deploys.

Ready to manage your containers with less friction?

Follow the step-by-step guide, test in an isolated environment, and evolve with structured logs, backups, and automated deploys. Start locally and connect your remote hosts with the Agent.

Review commands and start now

See also