Pulse/docs/DOCKER.md

🐳 Docker Guide

Pulse is distributed as a lightweight, Alpine-based Docker image.

🚀 Quick Start

docker run -d \
  --name pulse \
  -p 7655:7655 \
  -v pulse_data:/data \
  --restart unless-stopped \
  rcourtman/pulse:latest

Access at http://<your-ip>:7655.

---

📦 Docker Compose

Create a docker-compose.yml file:

services:
  pulse:
    image: rcourtman/pulse:latest
    container_name: pulse
    restart: unless-stopped
    ports:
      - "7655:7655"
    volumes:
      - pulse_data:/data
    environment:
      - TZ=Europe/London
      # Optional: Pre-configure auth (skips setup wizard)
      # - PULSE_AUTH_USER=admin
      # - PULSE_AUTH_PASS=secret123

volumes:
  pulse_data:

Run with: docker compose up -d

---

⚙️ Configuration

Pulse is configured via environment variables.

Variable	Description	Default
TZ	Timezone	UTC
PULSE_AUTH_USER	Admin Username	(unset)
PULSE_AUTH_PASS	Admin Password	(unset)
API_TOKENS	Comma-separated API tokens	(unset)
DISCOVERY_SUBNET	Custom CIDR to scan	(auto)
ALLOWED_ORIGINS	CORS allowed domains	(none)
LOG_LEVEL	Log verbosity (debug, info, warn, error)	info
PULSE_DISABLE_DOCKER_UPDATE_ACTIONS	Hide Docker update buttons (read-only mode)	false
PULSE_DISABLE_DOCKER_UPDATE_CHECKS	Disable Docker update detection entirely	false

Tip

: Set LOG_LEVEL=warn to reduce log volume while still capturing important events.

Advanced: Resource Limits & Healthcheck

services:
  pulse:
    deploy:
      resources:
        limits:
          cpus: '0.5'
          memory: 256M
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:7655/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3

---

🔄 Updates

To update Pulse to the latest version:

docker pull rcourtman/pulse:latest
docker stop pulse
docker rm pulse
# Re-run your docker run command

If using Compose:

docker compose pull
docker compose up -d

---

🔄 Container Updates

Pulse can detect and apply updates to your Docker containers directly from the UI.

How It Works

1. Update Detection: Pulse compares the local image digest with the latest digest from the container registry
2. Visual Indicator: Containers with available updates show a blue upward arrow icon
3. One-Click Update: Click the update button, confirm, and Pulse handles the rest
4. Batch Updates: Use the "Update All" button in the filter bar to update multiple containers safely in sequence

Updating a Container

1. Navigate to the Docker tab
2. Look for containers with a blue update arrow (⬆️)
3. Click the update button → Click Confirm
4. Pulse will:
   • Pull the latest image
   • Stop the current container
   • Create a backup (renamed with _pulse_backup_ suffix)
   • Start a new container with the same configuration
   • Clean up the backup after 5 minutes

Batch Updates

When multiple containers have updates available, an "Update All" button appears in the filter bar.

1. Click "Update All"
2. Confirm the action in the toast notification
3. Pulse queues the updates and processes them in parallel batches (default 5 concurrent updates)
4. A progress indicator shows the status of the batch operation
5. Failed updates are pushed to the end of the queue and reported in the final summary

Safety Features

• Automatic Backup: The old container is renamed, not deleted, until the update succeeds
• Rollback on Failure: If the new container fails to start, the old one is restored
• Configuration Preserved: Networks, volumes, ports, environment variables are all preserved

Requirements

• Unified Agent v5.0.6+ running on the Docker host
• Agent must have Docker socket access (/var/run/docker.sock)
• Registry must be accessible for update detection (public registries work automatically)

Private Registries

For private registries, ensure your Docker daemon has credentials configured:

docker login registry.example.com

The agent uses the Docker daemon's credentials for both pulling images and checking for updates.

Disabling Update Features

Pulse provides granular control over update features via environment variables on the Pulse server:

Variable	Description
PULSE_DISABLE_DOCKER_UPDATE_ACTIONS	Hides update buttons from the UI while still detecting updates. Use this for "read-only" monitoring.
PULSE_DISABLE_DOCKER_UPDATE_CHECKS	Disables update detection entirely. No registry checks are performed.

Example - Read-Only Mode (detect updates but prevent actions):

services:
  pulse:
    image: rcourtman/pulse:latest
    environment:
      - PULSE_DISABLE_DOCKER_UPDATE_ACTIONS=true

Example - Fully Disable Update Detection:

services:
  pulse:
    image: rcourtman/pulse:latest
    environment:
      - PULSE_DISABLE_DOCKER_UPDATE_CHECKS=true

You can also toggle "Hide Docker Update Buttons" from the UI: Settings → Agents → Docker Settings.

---

🛠️ Troubleshooting

• Forgot Password?

  docker exec pulse rm /data/.env
  docker restart pulse
  # Access UI again. Pulse will require a bootstrap token for setup.
  # Get it with:
  docker exec pulse /app/pulse bootstrap-token
  

• Logs

  docker logs -f pulse
  

• Shell Access

  docker exec -it pulse /bin/sh