Mastering Portainer Endpoints: Add, Secure, and Manage Multiple Docker Hosts

Why Endpoints Matter

Portainer’s Endpoint feature lets one Portainer instance talk to many Docker daemons, Swarm clusters, or Kubernetes APIs. Instead of running a separate Portainer for each host, you can:

• Centralise monitoring and deployment across environments
• Apply role‑based access control (RBAC) per host
• Switch between local and remote Docker sockets without re‑installing Portainer

Below you’ll find a practical walk‑through of adding a TLS‑secured remote Docker endpoint, a quick‑start command, and common mistakes to watch out for.

Adding an Endpoint via the UI

From the Portainer dashboard go to Endpoints → Add endpoint. Pick Docker as the type. The UI will prompt for:

• Endpoint name – a friendly label like prod‑web‑node
• URL – the full address, e.g., https://10.0.1.15:2376
• Authentication – TLS client cert, basic auth, or no auth for local sockets
• Expose REST API – optional, for external tooling

After clicking Save, the new endpoint appears in the list and you can immediately view containers, images, or services on that host.

Adding an Endpoint with TLS (Command‑Line Example)

For automation or when you prefer scripting, you can start Portainer with the TLS certificates pre‑mounted and a pre‑configured endpoint. Here’s a one‑liner that demonstrates the full flow:

docker run -d \
  -p 9443:9443 \
  --name portainer \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer_data:/data \
  -v /home/user/certs:/certs:ro \
  -e "PORTAINER_ENDPOINTS=[{\"name\":\"remote‑host\",\"url\":\"https://10.0.1.15:2376\",\"tls\":true,\"cert\":\"/certs/client.crt\",\"key\":\"/certs/client.key\",\"ca\":\"/certs/ca.crt\"}]" \
  portainer/portainer-ce:latest

Explanation of key items:

• -v /home/user/certs:/certs:ro mounts your client cert, key, and CA into the container. Use ro to keep them read‑only.
• The PORTAINER_ENDPOINTS environment variable accepts a JSON array. Each object defines an endpoint. For TLS you must set tls:true and provide the paths to cert, key, and optionally ca.
• Port 9443 is the default HTTPS port for Portainer. Adjust if you need a different host port.

After the container starts, log in to Portainer (default credentials: admin / admin for a fresh install). You should see the remote host already listed under Endpoints.

Scope and RBAC

Portainer’s RBAC lets you restrict which users can see or manage specific endpoints. To create a role that only sees the remote host:

1. Navigate to Settings → Roles → Add role.
2. Give the role a name, e.g., remote‑viewer.
3. Under Endpoint permissions, select the endpoint you just added and set the desired privileges (Read/Write).
4. Save the role and assign it to a user via Users → Edit user → Roles.

When the user logs in, only the allowed endpoint appears in the UI. This is vital for multi‑tenant environments.

Common Pitfalls

• Certificate CN/SAN Mismatch – The client cert’s Common Name or Subject Alternative Name must match the remote host’s hostname or IP. Otherwise Portainer will refuse the TLS handshake.
• Firewall Blocking 2376 – Ensure the remote host’s firewall allows inbound traffic on the Docker API port (default 2376 for TLS). A mis‑configured firewall results in a “Could not reach the Docker endpoint” error.
• Using Plain HTTP on a TLS Endpoint – If you point the URL to http:// but enable TLS in the UI, Portainer will fail to connect. The scheme must match the protocol.
• Manually Editing portainer.db – The SQLite database holds endpoint metadata. Manual edits can break if the schema changes in a new release. Prefer the UI or the PORTAINER_ENDPOINTS env var.
• Missing Permissions on Mounted Certs – Set file permissions to 600 so only the container user can read them. Publicly readable certs expose secrets.
• Exposing the REST API Unrestricted – The “Expose REST API” option opens the Docker API to any network that can reach Portainer. Use it only when you have additional network isolation.

Verifying Connectivity

After adding an endpoint, confirm it works by:

1. Clicking the endpoint name in the list.
2. Viewing the containers page; you should see the remote host’s containers.
3. Running a quick CLI test from the host where Portainer is installed:

docker -H tcp://10.0.1.15:2376 ps

If the command returns a container list, the Docker daemon is reachable. If it times out, double‑check the host’s Docker daemon configuration and firewall rules.

Limitations and When to Use the UI

While the PORTAINER_ENDPOINTS env var is handy for CI/CD pipelines, the UI remains the safest way to add or modify endpoints in production. The UI validates the connection before persisting the record, reducing the risk of orphaned or unreachable endpoints. Additionally, the UI automatically updates the portainer.db schema when new features are added, avoiding incompatibilities that can arise from manual edits.

Conclusion

Portainer’s Endpoint feature is a powerful way to centralise Docker management across multiple hosts. By following the steps above—adding endpoints with TLS, scoping them via RBAC, and validating connectivity—you can safely extend Portainer’s reach while maintaining tight security controls.