Add Docker Compose quick reference guide

- Document common docker-compose commands
- Provide configuration examples
- Include troubleshooting section
- Add environment variables reference table
- Include production tips and best practices

.dockerignore

@@ -0,0 +1,39 @@
+# Git
+.git
+.gitignore
+.gitattributes
+
+# Development
+.vscode
+.idea
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Build artifacts
+bin/
+dist/
+*.o
+*.a
+*.so
+
+# Dependencies
+vendor/
+
+# Documentation
+*.md
+RELEASE.md
+README.md
+QUICKSTART.md
+AGENTS.md
+
+# Other
+docker-compose.yml
+Dockerfile
+Dockerfile.server
+Dockerfile.agent
+.dockerignore
+.github
+.gitea
+scripts/

DOCKER_COMPOSE.md

@@ -0,0 +1,158 @@
+# Docker Compose Quick Reference
+
+## Quick Start
+
+### Full Stack (Server + Agent)
+```bash
+docker-compose up
+```
+Access dashboard: http://localhost:8080
+Login: admin / admin
+
+### Server Only
+```bash
+docker-compose up server
+```
+
+### Agent Only
+```bash
+SERVER=your-server:8080 docker-compose up agent
+```
+
+## Common Commands
+
+```bash
+# Start services in background
+docker-compose up -d
+
+# Stop all services
+docker-compose down
+
+# View logs
+docker-compose logs -f
+
+# View logs for specific service
+docker-compose logs -f server
+docker-compose logs -f agent
+
+# Restart services
+docker-compose restart
+
+# Remove volumes/data
+docker-compose down -v
+
+# Rebuild images
+docker-compose build --no-cache
+```
+
+## Configuration
+
+### Change Server Credentials
+Edit `docker-compose.yml`:
+```yaml
+environment:
+  USERNAME: "myuser"
+  PASSWORD: "mysecurepassword"
+```
+
+### Change Agent Reporting Interval
+```yaml
+environment:
+  INTERVAL: "30s"  # Report every 30 seconds instead of 15
+```
+
+### Set Custom Agent ID
+```yaml
+environment:
+  AGENT_ID: "my-machine"
+```
+
+### Run Multiple Agents
+```bash
+# Terminal 1: Start server
+docker-compose up server
+
+# Terminal 2: Run agent 1
+docker-compose run --name agent1 -e AGENT_ID=machine1 agent
+
+# Terminal 3: Run agent 2
+docker-compose run --name agent2 -e AGENT_ID=machine2 agent
+```
+
+## Docker Commands
+
+### View Running Containers
+```bash
+docker-compose ps
+```
+
+### Execute Commands in Container
+```bash
+# Connect to server
+docker-compose exec server sh
+
+# View server config
+docker-compose exec server ps aux
+```
+
+### View Resource Usage
+```bash
+docker stats
+```
+
+## Troubleshooting
+
+### Agent can't connect to server
+```bash
+# Check if server is running and healthy
+docker-compose ps
+
+# Check server logs
+docker-compose logs server
+
+# Check if containers are on same network
+docker network inspect nerd-monitor
+```
+
+### Clear Everything and Start Fresh
+```bash
+docker-compose down -v
+docker-compose build --no-cache
+docker-compose up
+```
+
+### Port Already in Use
+If port 8080 is already in use, edit `docker-compose.yml`:
+```yaml
+ports:
+  - "8090:8080"  # Maps host port 8090 to container port 8080
+```
+
+## Environment Variables Reference
+
+### Server
+| Variable | Default | Description |
+|----------|---------|-------------|
+| ADDR | 0.0.0.0 | Bind address |
+| PORT | 8080 | Server port |
+| USERNAME | admin | Admin username |
+| PASSWORD | admin | Admin password |
+
+### Agent
+| Variable | Default | Description |
+| SERVER | server:8080 | Server address |
+| INTERVAL | 15s | Reporting interval |
+| AGENT_ID | (auto) | Agent identifier |
+
+## Production Tips
+
+1. **Change credentials**: Update USERNAME and PASSWORD in docker-compose.yml
+2. **Use external volumes**: Add volume mounts for data persistence
+3. **Set resource limits**: Uncomment resource limits in docker-compose.yml
+4. **Enable restart policies**: Already set to `unless-stopped`
+5. **Use environment files**: Create `.env` file for sensitive data:
+   ```bash
+   USERNAME=myuser
+   PASSWORD=mysecurepass
+   ```
+   Then in docker-compose.yml: `env_file: .env`

Dockerfile.agent

@@ -29,6 +29,17 @@ COPY --from=builder /app/nerd-monitor-agent .
 RUN addgroup -D appgroup && adduser -D appuser -G appgroup
 USER appuser
 
+# Create entrypoint script to handle environment variables
+RUN echo '#!/bin/sh\n\
+SERVER=${SERVER:-localhost:8080}\n\
+INTERVAL=${INTERVAL:-15s}\n\
+AGENT_ID=${AGENT_ID:-}\n\
+if [ -z "$AGENT_ID" ]; then\n\
+  exec ./nerd-monitor-agent --server "$SERVER" --interval "$INTERVAL"\n\
+else\n\
+  exec ./nerd-monitor-agent --server "$SERVER" --interval "$INTERVAL" --id "$AGENT_ID"\n\
+fi\n\
+' > /app/entrypoint.sh && chmod +x /app/entrypoint.sh
+
 # Run the agent
-ENTRYPOINT ["./nerd-monitor-agent"]
+ENTRYPOINT ["/app/entrypoint.sh"]
-CMD ["--server", "localhost:8080"]

Dockerfile.server

@@ -43,6 +43,14 @@ EXPOSE 8080
 HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
     CMD wget --quiet --tries=1 --spider http://localhost:8080/login || exit 1
 
+# Create entrypoint script to handle environment variables
+RUN echo '#!/bin/sh\n\
+ADDR=${ADDR:-0.0.0.0}\n\
+PORT=${PORT:-8080}\n\
+USERNAME=${USERNAME:-admin}\n\
+PASSWORD=${PASSWORD:-admin}\n\
+exec ./nerd-monitor-server -addr "$ADDR" -port "$PORT" -username "$USERNAME" -password "$PASSWORD"\n\
+' > /app/entrypoint.sh && chmod +x /app/entrypoint.sh
+
 # Run the server
-ENTRYPOINT ["./nerd-monitor-server"]
+ENTRYPOINT ["/app/entrypoint.sh"]
-CMD ["-addr", "0.0.0.0", "-port", "8080"]

QUICKSTART.md

@@ -1,6 +1,45 @@
 # Nerd Monitor - Quick Start Guide
 
-## Building
+## Docker Compose (Easiest)
+
+The easiest way to get started is using Docker Compose:
+
+### Run Full Stack (Server + Agent)
+```bash
+docker-compose up
+```
+
+Access the dashboard at: **http://localhost:8080**
+
+### Run Server Only
+```bash
+docker-compose up server
+```
+
+### Run Agent Only (with external server)
+```bash
+SERVER=your-server:8080 docker-compose up agent
+```
+
+### Run Multiple Agents
+```bash
+# Start the server
+docker-compose up -d server
+
+# Run agents with custom IDs
+docker-compose run --name agent1 -e AGENT_ID=machine1 agent
+docker-compose run --name agent2 -e AGENT_ID=machine2 agent
+```
+
+### Docker Compose Configuration
+Edit `docker-compose.yml` to customize:
+- Server credentials: `USERNAME` and `PASSWORD`
+- Agent reporting interval: `INTERVAL`
+- Agent custom ID: `AGENT_ID`
+
+## Native Binaries
+
+### Building
 
 ```bash
 # Build for current OS
@@ -111,6 +150,8 @@ Change these when starting the server:
 ./bin/nerd-monitor-server -username myuser -password mysecurepass
 ```
 
+Or with Docker Compose, edit the `USERNAME` and `PASSWORD` environment variables in `docker-compose.yml`.
+
 ## Architecture
 
 - **Server**: Web UI, API endpoint for agent stats, in-memory storage
@@ -134,3 +175,8 @@ Change these when starting the server:
 - Verify server is running: `http://localhost:8080`
 - Check firewall rules allow the agent port
 - Ensure correct server address and port are specified
+
+### Docker Compose agents can't reach server
+- Verify server is healthy: `docker ps` (server should show healthy status)
+- Check both containers are on the same network: `docker network inspect nerd-monitor`
+- Ensure `SERVER` environment variable is set to `server:8080` (the service name)

docker-compose.yml

@@ -0,0 +1,107 @@
+version: '3.8'
+
+# ============================================================================
+# Nerd Monitor Docker Compose Configuration
+# ============================================================================
+# 
+# This file provides multiple ways to run Nerd Monitor:
+#
+# 1. Full Stack (Server + Agent):
+#    docker-compose up
+#
+# 2. Server Only:
+#    docker-compose up server
+#
+# 3. Agent Only (requires external server):
+#    docker-compose up agent
+#    (Set SERVER env var: SERVER=your-server:8080 docker-compose up agent)
+#
+# 4. Multiple Agents:
+#    docker-compose up -d server
+#    docker-compose run --name agent1 -e AGENT_ID=machine1 agent
+#    docker-compose run --name agent2 -e AGENT_ID=machine2 agent
+#
+# ============================================================================
+
+services:
+  # =========================================================================
+  # Nerd Monitor Server
+  # =========================================================================
+  # Web UI and API endpoint for collecting agent statistics
+  #
+  # Environment Variables:
+  #   ADDR: Server bind address (default: 0.0.0.0)
+  #   PORT: Server port (default: 8080)
+  #   USERNAME: Admin username (default: admin)
+  #   PASSWORD: Admin password (default: admin) - CHANGE IN PRODUCTION
+  #
+  server:
+    build:
+      context: .
+      dockerfile: Dockerfile.server
+    container_name: nerd-monitor-server
+    image: nerd-monitor-server:latest
+    ports:
+      - "8080:8080"
+    environment:
+      # Server configuration
+      ADDR: "0.0.0.0"
+      PORT: "8080"
+      # IMPORTANT: Change these credentials in production!
+      USERNAME: "admin"
+      PASSWORD: "admin"
+    healthcheck:
+      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8080/login"]
+      interval: 30s
+      timeout: 3s
+      retries: 3
+      start_period: 5s
+    restart: unless-stopped
+    networks:
+      - nerd-monitor
+    # Resource limits (optional, uncomment to enable)
+    # deploy:
+    #   resources:
+    #     limits:
+    #       cpus: '0.5'
+    #       memory: 512M
+
+  # =========================================================================
+  # Nerd Monitor Agent
+  # =========================================================================
+  # Lightweight monitoring agent that reports system stats to the server
+  #
+  # Environment Variables:
+  #   SERVER: Server address (default: server:8080 when using docker-compose)
+  #   INTERVAL: Reporting interval (default: 15s)
+  #   AGENT_ID: Optional agent identifier (auto-generated from hostname if empty)
+  #
+  # Note: This agent depends on the server being healthy before starting
+  #
+  agent:
+    build:
+      context: .
+      dockerfile: Dockerfile.agent
+    image: nerd-monitor-agent:latest
+    environment:
+      # Agent configuration
+      SERVER: "server:8080"        # Connect to the server service
+      INTERVAL: "15s"              # Report stats every 15 seconds
+      # AGENT_ID: "my-machine"     # Optional: set a custom agent ID
+    depends_on:
+      server:
+        condition: service_healthy  # Wait for server to be healthy
+    restart: unless-stopped
+    networks:
+      - nerd-monitor
+    # Resource limits (optional, uncomment to enable)
+    # deploy:
+    #   resources:
+    #     limits:
+    #       cpus: '0.25'
+    #       memory: 128M
+
+networks:
+  # Shared network for server and agent communication
+  nerd-monitor:
+    driver: bridge