Portainer is an excellent tool for managing Docker, Kubernetes, and other containerized environments through an easy-to-use web UI.
If you already have a Portainer server running, you can expand its capabilities by installing the Portainer Agent on remote machines.
This allows your central Portainer server to manage containers on multiple nodes securely and efficiently.
In this guide, we'll walk through installing the Portainer Agent and connecting it to your existing Portainer instance.
Prerequisites
Before you start, make sure you have:
- An existing Portainer Server up and running.
- Access to the remote machine (the machine where you want to install the agent).
- Docker installed on the remote machine.
- Proper network connectivity between your server and the agent (ports 9001 TCP/UDP must be open).
Step 1: Deploy the Portainer Agent
On the remote machine where you want to install the agent, run the following Docker command:
docker volume create portainer_agent_data
docker run -d \
--name portainer_agent \
--restart=always \
-p 9001:9001 \
-v /var/run/docker.sock:/var/run/docker.sock \
-v /var/lib/docker/volumes:/var/lib/docker/volumes \
portainer/agent:latest
Explanation of the flags:
--restart=always: Ensures the agent restarts automatically if the machine reboots.-p 9001:9001: Exposes the agent port.-v /var/run/docker.sock:/var/run/docker.sock: Provides access to Docker on the host.-v /var/lib/docker/volumes:/var/lib/docker/volumes: Allows management of volumes.
Tip: If your node is behind a firewall, make sure port 9001 is open and accessible by your Portainer server.
Step 2: Connect the Agent to Portainer
- Open your Portainer web UI.
- Go to Environments > Add Environment.
- Choose Agent as the environment type.
- Fill in the following:
- Name: Give your environment a recognizable name.
- Environment address: Enter the IP address of the remote machine and port 9001.
Example: 192.168.1.100:9001
- Configure any additional settings (tags, group, etc.), if needed.
- Click Add Environment.
Portainer will now connect to the remote machine via the Agent!
Troubleshooting
Cannot connect to Agent:
Ensure that the agent machine's firewall allows incoming connections on port 9001.
Agent keeps restarting:
Check the logs with docker logs portainer_agent for error messages.
Wrong Docker socket permissions:
Make sure the user running Docker has access to /var/run/docker.sock.
Conclusion
Installing the Portainer Agent is a straightforward way to extend your Portainer Server to manage multiple nodes easily.
By following these steps, you can seamlessly monitor and control remote Docker environments — all from one central dashboard.
Happy container managing! 🚀
