Skip to main content

Portainer Edge Agent Setup

Install Portainer Edge Agent to connect your server to vendor's Portainer Server.

Overview​

The Edge Agent:

  • Runs on your server
  • Connects to vendor's Portainer Server
  • Enables vendor to deploy Chatty AI stack
  • Uses outbound connections only (ports 443 + 8000)

Prerequisites​

Before starting, ensure you have:

  • Completed Infrastructure Checklist
  • Docker installed and running
  • SSL certificates prepared
  • DNS records configured
  • Received Edge Agent Key from vendor
  • Received .env file from vendor

Step 1: Receive Edge Agent Key​

Vendor will provide an Edge Agent key that looks like:

aHR0cHM6Ly9wb3J0YWluZXIuY2hhdHR5LWFpLmFpOjkwMDB8cG9ydGFpbmVyLmNoYXR0eS1haS5haToxMjM0NXxhYmMxMjM0NXw0

Keep this key secure - it allows connection to vendor's Portainer Server.

Step 2: Create Deployment Directory​

Create directory for Chatty AI deployment:

# Create directory
sudo mkdir -p /opt/chatty-app
cd /opt/chatty-app

# Create subdirectories
sudo mkdir -p certs/chattyai certs/n8n certs/databases
sudo mkdir -p data

Step 3: Place SSL Certificates​

Copy your SSL certificates to the correct locations:

# Chatty AI certificates
sudo cp /path/to/chattyai-fullchain.pem /opt/chatty-app/certs/chattyai/fullchain.pem
sudo cp /path/to/chattyai-privkey.pem /opt/chatty-app/certs/chattyai/privkey.pem

# n8n certificates
sudo cp /path/to/n8n-fullchain.pem /opt/chatty-app/certs/n8n/fullchain.pem
sudo cp /path/to/n8n-privkey.pem /opt/chatty-app/certs/n8n/privkey.pem

# Databases certificates
sudo cp /path/to/databases-fullchain.pem /opt/chatty-app/certs/databases/fullchain.pem
sudo cp /path/to/databases-privkey.pem /opt/chatty-app/certs/databases/privkey.pem

# Set permissions
sudo chmod 600 /opt/chatty-app/certs/*/privkey.pem
sudo chmod 644 /opt/chatty-app/certs/*/fullchain.pem

Step 4: Place Environment File​

Save the .env file provided by vendor:

# Create .env file (vendor will provide content)
sudo nano /opt/chatty-app/.env

Paste the content provided by vendor, then save and exit.

Verify the file:

cat /opt/chatty-app/.env | grep CHATTYAI_DOMAIN

Step 5: Install Edge Agent​

Run the Edge Agent installation command:

docker run -d \
  --name portainer_edge_agent \
  --restart=always \
  -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 \
  -e EDGE=1 \
  -e EDGE_ID=$(uuidgen) \
  -e EDGE_KEY=YOUR_EDGE_KEY_HERE \
  -e EDGE_INSECURE_POLL=0 \
  portainer/agent:latest

Replace YOUR_EDGE_KEY_HERE with the key provided by vendor.

Step 6: Verify Edge Agent​

Check Edge Agent is running:

# Check container status
docker ps | grep portainer_edge_agent

# Check logs
docker logs portainer_edge_agent

Expected output:

[INFO] Edge agent started
[INFO] Connecting to Portainer server...
[INFO] Successfully connected to Portainer

Step 7: Notify Vendor​

Once Edge Agent is running, notify vendor:

Email to: support@chatty-ai.ai

Subject: Edge Agent Installed - [Your Company Name]

Body:

Edge Agent has been installed successfully.

Server Details:
- Hostname: server.example.com
- IP Address: 192.168.1.100
- Edge Agent Status: Running
- Domains:
  - Chatty AI: chat.example.com
  - n8n: n8n.example.com
  - Databases: databases.example.com

Ready for stack deployment.

Troubleshooting​

Edge Agent Won't Start​

Check Docker is running:

sudo systemctl status docker

Check for port conflicts:

netstat -tulpn | grep LISTEN

Cannot Connect to Portainer Server​

Verify outbound access:

# Test HTTPS
curl -I https://portainer.chatty-ai.ai

# Test WebSocket port
nc -zv portainer.chatty-ai.ai 8000

Check firewall:

sudo ufw status
sudo iptables -L OUTPUT

Edge Key Invalid​

Verify you copied the complete key:

  • No line breaks
  • No extra spaces
  • Complete string from vendor

Request new key from vendor if needed.

Edge Agent Management​

View Logs​

docker logs -f portainer_edge_agent

Restart Edge Agent​

docker restart portainer_edge_agent

Stop Edge Agent​

docker stop portainer_edge_agent

Remove Edge Agent​

⚠️ Only if reinstalling:

docker stop portainer_edge_agent
docker rm portainer_edge_agent
docker volume rm portainer_agent_data

Security Notes​

Edge Agent Permissions​

Edge Agent has access to:

  • Docker socket (to manage containers)
  • Docker volumes (to access data)
  • Host filesystem (read-only for monitoring)

This is required for vendor to deploy and manage Chatty AI.

Network Security​

Edge Agent:

  • ✅ Only makes outbound connections
  • ✅ No inbound ports opened
  • ✅ Uses TLS encryption (ports 443 + 8000)
  • ✅ Authenticates with Edge Key

Access Control​

  • Vendor can deploy/manage via Portainer
  • Customer can view containers via docker ps
  • Customer can view logs via docker logs
  • Customer cannot access Portainer UI

Next Steps​

After Edge Agent is installed and vendor notified:

  1. Vendor will deploy Chatty AI stack via Portainer
  2. See Stack Deployment for what happens next
  3. Then complete Post-Installation Validation

Support​

For Edge Agent installation issues:

  • Email: support@chatty-ai.ai
  • Include:
    • Edge Agent logs (docker logs portainer_edge_agent)
    • Server IP and hostname
    • Firewall configuration