On-Premise Pollers

Overview

AlertKick On-Premise Pollers let you monitor internal services that aren’t accessible from the public internet. A poller is a lightweight Docker container you deploy inside your network. It connects outbound-only to the AlertKick API over HTTPS, fetches its assigned monitors, executes checks, and reports results back.

Use on-premise pollers when you need to monitor:

• Internal staging/development environments
• Private APIs behind a firewall
• Database health endpoints on private networks
• Intranet applications and internal tools
• Services in air-gapped or restricted environments

Quick Start

1. Create a Poller Location

1. Navigate to Admin > On-Prem Pollers
2. Click Add Location
3. Enter a Display Name (e.g., “HQ Datacenter”) and a Location Key (e.g., hq-datacenter)
4. Click Create Location

2. Generate an Authentication Token

1. On the location detail page, find the Token Management section
2. Click Generate next to the Primary Token slot
3. Copy the generated token immediately - it will only be shown once

3. Deploy the Poller

Run this command on a machine inside your network:

docker run -d \
  --name ap-poller \
  --restart unless-stopped \
  -e AP_POLLER_TOKEN="<your-token>" \
  -e AP_API_URL="https://app.alertkick.com" \
  -p 8089:8089 \
  ghcr.io/alertkick/alertkick-poller:latest

The poller will register with AlertKick and begin executing checks within 60 seconds.

4. Create a Monitor

1. Navigate to Monitors > Add Monitor
2. Configure your monitor as usual (URL, check type, interval, etc.)
3. In the Location Selection dropdown, choose your on-premises location under Your On-Premises Locations
4. Save the monitor

The poller will pick up the monitor on its next poll cycle and begin running checks.

Configuration

The poller is configured entirely through environment variables:

Variable	Required	Default	Description
AP_POLLER_TOKEN	Yes	-	Authentication token from the location detail page
AP_API_URL	Yes	-	AlertKick API URL (e.g., https://app.alertkick.com)
AP_POLL_INTERVAL	No	60	How often (in seconds) to fetch the monitor list
AP_MAX_CONCURRENCY	No	50	Maximum number of concurrent checks
AP_BATCH_SIZE	No	100	Maximum results per batch submission
AP_BATCH_INTERVAL	No	10	How often (in seconds) to submit result batches
AP_HEALTH_PORT	No	8089	Port for the health/metrics HTTP server
AP_LOG_LEVEL	No	info	Log level: debug, info, warn, error
AP_TLS_INSECURE	No	false	Skip TLS verification for internal HTTPS targets

Token Rotation

Each poller location supports dual active tokens (primary and secondary) for zero-downtime rotation:

1. Generate a secondary token while the primary is still active
2. Update your poller containers to use the new secondary token
3. Rotate tokens - this moves secondary to primary and generates a new secondary
4. Revoke the old primary token if no longer needed

This ensures pollers are never disconnected during token changes.

Rotation Workflow

1. Go to your location’s detail page
2. If both primary and secondary tokens are active, click Rotate Tokens
3. This moves the current secondary token to the primary slot and generates a fresh secondary token
4. Copy the new secondary token and update your poller deployment
5. Once all pollers are using the new token, revoke the old one if desired

Scaling and Redundancy

You can deploy multiple pollers at the same location for redundancy and load distribution:

# Deploy a second poller on another machine
docker run -d \
  --name ap-poller-2 \
  --restart unless-stopped \
  -e AP_POLLER_TOKEN="<same-token>" \
  -e AP_API_URL="https://app.alertkick.com" \
  -p 8089:8089 \
  ghcr.io/alertkick/alertkick-poller:latest

Multiple pollers at the same location share the workload automatically. Each poller independently fetches the monitor list and self-schedules checks, ensuring even distribution across pollers.

Benefits of Multiple Pollers

• Redundancy: If one poller goes down, others continue monitoring
• Load distribution: Checks are spread across available pollers
• Zero-downtime updates: Roll pollers one at a time during upgrades

Health Monitoring

Each poller exposes two HTTP endpoints on the health port (default 8089):

/ready

Returns 200 OK when the poller is registered and ready to execute checks. Use this for Docker health checks or Kubernetes readiness probes:

docker run -d \
  --name ap-poller \
  --restart unless-stopped \
  --health-cmd="curl -f http://localhost:8089/ready || exit 1" \
  --health-interval=30s \
  -e AP_POLLER_TOKEN="<your-token>" \
  -e AP_API_URL="https://app.alertkick.com" \
  -p 8089:8089 \
  ghcr.io/alertkick/alertkick-poller:latest

/metrics

Returns Prometheus-compatible metrics including:

• checks_executed - total number of checks run
• checks_failed - total number of failed checks
• results_submitted - total number of results sent to the API

Troubleshooting

Poller shows “offline” in the dashboard

• Verify the poller container is running: docker ps | grep ap-poller
• Check container logs: docker logs ap-poller
• Confirm outbound HTTPS access to the API URL
• Verify the token hasn’t been revoked

Poller registers but no checks execute

• Ensure monitors are assigned to this poller’s location
• Check that the monitor’s location matches the poller’s location key
• View the poller logs for errors: docker logs -f ap-poller

Token authentication fails

• Verify the full token was copied (tokens start with pt_)
• Check that the token hasn’t been revoked in the location detail page
• Ensure the token matches the correct location
• Generate a new token if the current one may be compromised

High memory or CPU usage

• Reduce AP_MAX_CONCURRENCY to lower parallel check count
• Increase AP_POLL_INTERVAL to fetch monitors less frequently
• Deploy additional pollers to distribute the workload

Network connectivity issues

The poller only requires outbound HTTPS (port 443) to the AlertKick API. It does not require any inbound connections from AlertKick. Ensure your firewall rules allow outbound HTTPS to app.alertkick.com.