# 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)