Peekaping Uptime Monitor on AWS User Guide

Overview

Peekaping is an open source, self-hosted uptime and status monitoring system and a modern alternative to Uptime Kuma. It watches your websites, APIs, TCP services and DNS records, records a heartbeat history for each check, calculates uptime statistics over time, publishes status pages, and sends alerts through notification channels, all from a clean web interface running inside your own AWS account. The cloudimg image runs the official upstream container stack behind nginx on port 80, with a bundled PostgreSQL and Redis and all stateful data on a dedicated EBS data volume. A unique administrator password and every secret are generated on the first boot of each instance, and self registration is closed, so no shared or default credential ever ships in the image. Built from Peekaping 0.0.46 (MIT), backed by 24/7 cloudimg support.

What is included:

• Peekaping 0.0.46 as the official upstream stack: the Go API and socket.io server, a monitor scheduler, a check worker, a heartbeat ingester, the React web interface and a one-shot database migrator, plus a bundled PostgreSQL and Redis, every image pinned by digest
• The whole stack managed by a single peekaping.service systemd unit, enabled and active on every boot, fronted by nginx on port 80
• The bundled PostgreSQL and Redis reachable only inside a private container network, and the API and web interface bound to loopback behind nginx
• Stateful Docker data (database, cache and images) relocated onto a dedicated EBS data volume mounted at /var/lib/peekaping
• A first-boot service that generates a per-instance administrator password, database password and cache password, mints fresh session signing keys into an empty database, closes self registration, and records the administrator credentials in a root-only file
• An unauthenticated health endpoint for load balancer and uptime checks
• 24/7 cloudimg support

Prerequisites

An AWS account, an EC2 key pair in the target region, and a VPC with a public subnet. m5.large (2 vCPU / 8 GiB RAM) is the recommended instance type; Peekaping runs several containers, so 8 GiB RAM or more is advised. Security group inbound: allow 22/tcp from your management network and 80/tcp (and 443/tcp if you terminate TLS) for the web interface. Peekaping serves plain HTTP on port 80; for production, terminate TLS in front of it with your own domain so the interface runs over HTTPS.

Step 1 - Launch the AMI

Subscribe to the listing in AWS Marketplace, choose Continue to Launch, and launch through the EC2 console or the AWS CLI. Select the m5.large instance type, your key pair, and a security group that opens ports 22 and 80 (and 443 for TLS).

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <your-key-pair> \
  --security-group-ids <security-group-id> \
  --subnet-id <subnet-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=peekaping}]'

Step 2 - Connect to your instance

Connect over SSH as the default login user for your OS variant. Use the public IP or DNS name of your instance and the private key for your key pair.

ssh -i <your-key.pem> ubuntu@<instance-public-ip>

Step 3 - Confirm the services are running

Peekaping is orchestrated by four systemd units: the Docker engine, the one-shot first-boot initializer, the peekaping compose service and nginx. All four are active on a healthy instance.

for s in docker peekaping-firstboot peekaping nginx; do
  printf "%-28s %s\n" "$s.service" "$(systemctl is-active $s.service)"
done

docker.service               active
peekaping-firstboot.service  active
peekaping.service            active
nginx.service                active

Step 4 - Inspect the container stack

The peekaping.service unit brings up the full Compose topology. The one-shot migrate container applies the schema and exits, and the api, web, postgres and redis containers report healthy.

sudo docker compose -f /etc/peekaping/compose.yaml ps --format "table {{.Service}}\t{{.Status}}"

SERVICE    STATUS
api        Up (healthy)
ingester   Up
postgres   Up (healthy)
producer   Up
redis      Up (healthy)
web        Up (healthy)
worker     Up

Step 5 - Confirm the listener set and health

Only SSH and the web interface listen on the network. The API is on 127.0.0.1:8034 and the web container on 127.0.0.1:8081, both fronted by nginx on port 80; the bundled PostgreSQL and Redis are never published to a host port. The health endpoint answers 200 without authentication, and an unauthenticated API call is correctly refused with 401.

sudo ss -tlnp | awk 'NR==1 || /:22 |:80 |8034|8081/'
curl -s -o /dev/null -w "health %{http_code}\n" http://127.0.0.1/api/v1/health
curl -s -o /dev/null -w "unauth /monitors %{http_code}\n" http://127.0.0.1/api/v1/monitors

State  Recv-Q Send-Q Local Address:Port  Peer Address:Port Process
LISTEN 0      4096         0.0.0.0:22         0.0.0.0:*     users:(("sshd",...))
LISTEN 0      511          0.0.0.0:80         0.0.0.0:*     users:(("nginx",...))
LISTEN 0      4096       127.0.0.1:8034       0.0.0.0:*     users:(("docker-proxy",...))
LISTEN 0      4096       127.0.0.1:8081       0.0.0.0:*     users:(("docker-proxy",...))
health 200
unauth /monitors 401

Step 6 - The data volume

Peekaping's stateful Docker data - the PostgreSQL database, the Redis queue and the pinned container images - lives on a dedicated EBS volume mounted at /var/lib/peekaping, separate from the OS root disk and independently resizable.

df -h /var/lib/peekaping | tail -1

/dev/nvme1n1     30G   49M   28G   1% /var/lib/peekaping

Step 7 - Retrieve the per-instance administrator credentials

On the first boot of your instance a unique administrator was created with a per-instance password, before the web port became reachable. The credentials are stored in a root-only file.

sudo cat /root/peekaping-credentials.txt

The file contains the sign-in email and password for this instance:

PEEKAPING_URL=http://<instance-public-ip>
PEEKAPING_ADMIN_EMAIL=<PEEKAPING_ADMIN_EMAIL>
PEEKAPING_ADMIN_PASSWORD=<PEEKAPING_ADMIN_PASSWORD>

Step 8 - Sign in to the web interface

Open http://<instance-public-ip>/ in a browser and sign in with the administrator email and password from Step 7. Self registration is closed on this instance, so the sign-up path is disabled and nobody can claim the administrator account.

Step 9 - Create your first monitor

Select Create, choose the HTTP(S) Monitor type, give it a name and the URL to watch (for example your website or API endpoint), and select Create. Peekaping begins checking immediately at the configured interval and records a heartbeat for each check.

Step 10 - Watch uptime and status

The monitors dashboard lists every monitor with its current status, check interval and heartbeat history. A green Up badge and heartbeat bar confirm the target is reachable; Peekaping tracks uptime percentages over 24 hours, 7 days, 30 days and a year, and you can add notification channels and publish status pages from the interface.

Maintenance

• Service control: the stack runs under systemd. Use sudo systemctl status peekaping.service to check it and sudo systemctl restart peekaping.service to restart the whole Compose topology.
• Logs: sudo docker compose -f /etc/peekaping/compose.yaml logs --tail 100 api shows the API logs; swap api for any service name.
• Change the administrator password: sign in and open Settings, where you can change the password and enable two-factor authentication.
• TLS: Peekaping serves plain HTTP on port 80. For production, put your own domain and a TLS certificate in front of it (for example an AWS load balancer with AWS Certificate Manager, or nginx with Let's Encrypt) and restrict the security group.
• Backups: snapshot the /var/lib/peekaping EBS volume to back up the database and configuration.

Support

24/7 technical support is included with this image. Contact support@cloudimg.co.uk for help with deployment, reverse proxy and TLS termination, notification integrations, backup and storage planning, and scaling. Peekaping is open source under the MIT License; upstream describes it as beta software under active development. This image is produced by cloudimg and is not affiliated with, endorsed by, or sponsored by Peekaping.