124 lines
3.0 KiB
Markdown
124 lines
3.0 KiB
Markdown
# Portainer Edge Agent Setup Guide
|
|
|
|
## Overview
|
|
Edge Agent allows you to connect Docker environments to Portainer over the network instead of using local socket connection. This is useful when having socket connection issues.
|
|
|
|
Reference: https://downloads.portainer.io/edge_agent_guide.pdf
|
|
|
|
## Step 1: Access Portainer UI
|
|
|
|
Access your Portainer instance:
|
|
- HTTP: http://localhost:9000
|
|
- HTTPS: https://localhost:9443
|
|
|
|
Complete the initial setup if you haven't already (create admin user).
|
|
|
|
## Step 2: Add Edge Environment in Portainer UI
|
|
|
|
1. **Log into Portainer**
|
|
|
|
2. **Go to Environments** (left sidebar)
|
|
|
|
3. **Click "Add environment"**
|
|
|
|
4. **Select "Edge Agent Standard"**
|
|
- Choose "Docker Standalone"
|
|
- Name: `nuc-edge` (or your preferred name)
|
|
|
|
5. **Copy the deployment command** shown in the UI
|
|
- It will include your `EDGE_ID` and `EDGE_KEY`
|
|
- The command looks like:
|
|
```bash
|
|
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=xxx \
|
|
-e EDGE_KEY=xxx \
|
|
-e CAP_HOST_MANAGEMENT=1 \
|
|
-e EDGE_INSECURE_POLL=1 \
|
|
--name portainer_edge_agent \
|
|
portainer/agent:latest
|
|
```
|
|
|
|
6. **Extract EDGE_ID and EDGE_KEY** from the command
|
|
|
|
## Step 3: Configure Edge Agent
|
|
|
|
### Option A: Using docker-compose (Recommended)
|
|
|
|
1. **Copy the example env file:**
|
|
```bash
|
|
cd /mnt/shared/DEV/repos/d-popov.com/scripts/portainer-compose-stacks
|
|
cp .env.edge-agent.example .env
|
|
```
|
|
|
|
2. **Edit .env file** with your EDGE_ID and EDGE_KEY:
|
|
```bash
|
|
nano .env
|
|
```
|
|
|
|
3. **Start the Edge Agent:**
|
|
```bash
|
|
docker-compose -f portainer-edge-agent.yml up -d
|
|
```
|
|
|
|
### Option B: Using the Docker command directly
|
|
|
|
Just run the command copied from Portainer UI in Step 2.
|
|
|
|
## Step 4: Verify Connection
|
|
|
|
1. Go back to Portainer UI → **Environments**
|
|
|
|
2. Your edge environment should show as **"Connected"** (green)
|
|
|
|
3. Click on the environment to manage your Docker containers
|
|
|
|
## Troubleshooting
|
|
|
|
### Edge Agent not connecting:
|
|
|
|
1. **Check logs:**
|
|
```bash
|
|
docker logs portainer-edge-agent
|
|
```
|
|
|
|
2. **Verify Portainer tunnel is accessible:**
|
|
```bash
|
|
curl http://localhost:8000
|
|
```
|
|
|
|
3. **Check if agent container is running:**
|
|
```bash
|
|
docker ps | grep edge-agent
|
|
```
|
|
|
|
4. **Ensure firewall allows port 8000** (for Edge polling)
|
|
|
|
### Environment shows as "Down":
|
|
|
|
- Wait 30-60 seconds for initial connection
|
|
- Check that EDGE_ID and EDGE_KEY are correct
|
|
- Restart the agent: `docker restart portainer-edge-agent`
|
|
|
|
## Cleanup
|
|
|
|
To remove Edge Agent:
|
|
```bash
|
|
docker-compose -f portainer-edge-agent.yml down -v
|
|
# or
|
|
docker stop portainer-edge-agent && docker rm portainer-edge-agent
|
|
```
|
|
|
|
## Notes
|
|
|
|
- Edge Agent polls Portainer server every 5 seconds by default
|
|
- `EDGE_INSECURE_POLL=1` allows connection without TLS (for local testing)
|
|
- Port 8000 is used for the Edge tunnel communication
|
|
- Port 9001 is the agent API port (optional, for direct access)
|
|
|