Skip to content

Modern Docker Management, Designed for Everyone

docs: add agent config docs

Kyle Mendell417a8b09e2f9
diff --git a/docs/docs/features/agents/setup-agent.md b/docs/docs/features/agents/setup-agent.md
index 51482cff1..4420d8d39 100644
--- a/docs/docs/features/agents/setup-agent.md
+++ b/docs/docs/features/agents/setup-agent.md
@@ -10,8 +10,8 @@ Arcane agents are lightweight Go applications that run on remote servers to mana
## Architecture
```
-┌─────────────────┐ HTTP API ┌─────────────────┐
-│ Arcane Server │ ◄─────────────► │ Go Agent │
+┌─────────────────┐ HTTP API ┌─────────────────┐
+│ Arcane Server │ ◄────────────── │ Go Agent │
│ (Management) │ │ (Remote Host) │
└─────────────────┘ └─────────────────┘
```
@@ -22,6 +22,33 @@ Arcane agents are lightweight Go applications that run on remote servers to mana
- Network access to Arcane server
- User with Docker socket permissions
+## Configuration
+
+The agent supports the following environment variables:
+
+| Environment Variable | Default Value | Description |
+| -------------------- | ----------------------------- | ----------------------------------------- |
+| `ARCANE_HOST` | `localhost` | Hostname of the Arcane server |
+| `ARCANE_PORT` | `3000` | Port of the Arcane server |
+| `TLS_ENABLED` | `false` | Enable TLS/HTTPS for server communication |
+| `RECONNECT_DELAY` | `5s` | Delay between reconnection attempts |
+| `HEARTBEAT_RATE` | `30s` | Interval for sending heartbeat to server |
+| `COMPOSE_BASE_PATH` | `data/agent/compose-projects` | Base directory for compose projects |
+
+### Configuration File
+
+Create a `.env` file for the agent:
+
+```bash
+# .env file example
+ARCANE_HOST=your-server.com
+ARCANE_PORT=3000
+TLS_ENABLED=false
+RECONNECT_DELAY=5s
+HEARTBEAT_RATE=30s
+COMPOSE_BASE_PATH=/opt/agent/compose-projects
+```
+
## Quick Start with Docker
```bash
@@ -29,11 +56,58 @@ Arcane agents are lightweight Go applications that run on remote servers to mana
docker run -d --name arcane-agent \
-e ARCANE_HOST=your-server.com \
-e ARCANE_PORT=3000 \
- -e AGENT_ID=my-agent \
+ -e TLS_ENABLED=false \
+ -e HEARTBEAT_RATE=30s \
+ -e COMPOSE_BASE_PATH=/data/compose-projects \
-v /var/run/docker.sock:/var/run/docker.sock \
+ -v $(pwd)/compose-projects:/data/compose-projects \
ghcr.io/ofkm/arcane-agent:latest
```
+## Installation Options
+
+### Docker Compose
+
+```yaml
+services:
+ arcane-agent:
+ image: ghcr.io/ofkm/arcane-agent:latest
+ container_name: arcane-agent
+ restart: unless-stopped
+ environment:
+ - ARCANE_HOST=your-server.com
+ - ARCANE_PORT=3000
+ - TLS_ENABLED=false
+ - HEARTBEAT_RATE=30s
+ - RECONNECT_DELAY=5s
+ - COMPOSE_BASE_PATH=/data/compose-projects
+ volumes:
+ - /var/run/docker.sock:/var/run/docker.sock
+ - ./compose-projects:/data/compose-projects
+```
+
+### Binary Installation
+
+```bash
+# Download the binary
+wget https://github.com/ofkm/arcane-agent/releases/latest/download/arcane-agent-linux-amd64
+
+# Make executable
+chmod +x arcane-agent-linux-amd64
+
+# Create configuration
+cat > .env << EOF
+ARCANE_HOST=your-server.com
+ARCANE_PORT=3000
+TLS_ENABLED=false
+HEARTBEAT_RATE=30s
+COMPOSE_BASE_PATH=/opt/agent/compose-projects
+EOF
+
+# Run the agent
+./arcane-agent-linux-amd64
+```
+
## Troubleshooting
### Common Issues
@@ -51,6 +125,13 @@ sudo usermod -aG docker arcane-agent
sudo systemctl restart arcane-agent
```
+**TLS Certificate Issues**: When using `TLS_ENABLED=true`, ensure valid certificates
+
+```bash
+# Test TLS connection
+curl -I https://your-arcane-server:3000/api/agents/register
+```
+
## Updates
### Docker Updates
@@ -63,12 +144,11 @@ docker pull ghcr.io/ofkm/arcane-agent:latest
docker stop arcane-agent
docker rm arcane-agent
-# Start with new image
+# Start with new image (using same configuration)
docker run -d --name arcane-agent \
- -e ARCANE_HOST=your-server.com \
- -e ARCANE_PORT=3000 \
- -e AGENT_ID=my-agent \
+ --env-file .env \
-v /var/run/docker.sock:/var/run/docker.sock \
+ -v $(pwd)/compose-projects:/data/compose-projects \
ghcr.io/ofkm/arcane-agent:latest
```