Peekaping on Ubuntu 24.04 on Azure User Guide

Overview

Peekaping is an open-source, self-hosted uptime monitoring system built with a Go API and a React web interface. It checks websites, APIs, TCP ports, DNS records, containers and databases on a schedule, records a heartbeat history for every check, calculates uptime statistics, publishes status pages, and raises alerts through notification channels. The cloudimg image runs Peekaping 0.0.46 with a bundled PostgreSQL and Redis under Docker Compose on a single VM, generates a unique administrator password and unique database and cache passwords on the first boot of every VM, and closes self-registration so nobody can claim the administrator account on your instance. Backed by 24/7 cloudimg support.

What is included:

• Peekaping 0.0.46 (API, web interface, producer, worker and ingester) with every container pinned by image digest rather than a floating tag
• A bundled PostgreSQL 17 and Redis 7, reachable only inside a private container network and never published to a host port
• nginx on port 80 as the single public entry point, serving the web interface and proxying the API and the live heartbeat stream
• A unique administrator password, PostgreSQL password and Redis password generated on first boot, plus fresh session signing keys minted into a brand-new database
• Self-registration closed on first boot, verified by the image itself
• docker.service, peekaping.service and nginx.service as systemd units, enabled and active
• 24/7 cloudimg support

Note on upstream status. The Peekaping project describes itself as beta software under active development. The cloudimg image ships the official upstream 0.0.46 release unmodified and pinned by digest.

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is the recommended starting size. NSG inbound: allow 22/tcp from your management network and 80/tcp for the web interface. No other port needs to be open.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for Peekaping by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). Then Review + create -> Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name peekaping \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values ~/.ssh/id_ed25519.pub \
  --vnet-name <your-vnet> --subnet <your-subnet> \
  --public-ip-sku Standard

az vm open-port --resource-group <your-rg> --name peekaping --port 80 --priority 1010

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

Step 4 - Confirm the stack is running

On first boot the image generates a unique administrator password and unique PostgreSQL and Redis passwords, starts the container stack, registers the administrator account over the loopback interface before the public port is reachable, and then verifies that no further registration is accepted.

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

Expected output:

active
active
active
active

Check what is actually listening. Only SSH and the web interface face the network; the API and the web container are bound to the loopback interface, and PostgreSQL and Redis are not published to a host port at all.

ss -tlnH | awk '{print $1, $4}' | sort -u

Expected output:

LISTEN 0.0.0.0:22
LISTEN 0.0.0.0:80
LISTEN 127.0.0.1:8034
LISTEN 127.0.0.1:8081
LISTEN 127.0.0.53%lo:53
LISTEN 127.0.0.54:53
LISTEN [::]:22
LISTEN [::]:80

Confirm the health endpoint answers, and that an unauthenticated API call is refused:

curl -s -o /dev/null -w 'health: %{http_code}\n' http://127.0.0.1/api/v1/health
curl -s -o /dev/null -w 'unauthenticated /monitors: %{http_code}\n' http://127.0.0.1/api/v1/monitors

Expected output:

health: 200
unauthenticated /monitors: 401

Step 5 - Retrieve your administrator password

Every VM gets its own administrator password. It is written to a root-only file on first boot.

sudo cat /root/peekaping-credentials.txt

The file records the access URL, the administrator email and the per-VM password:

PEEKAPING_URL=http://<vm-public-ip>
PEEKAPING_ADMIN_EMAIL=admin@peekaping.local
PEEKAPING_ADMIN_PASSWORD=<generated-for-your-vm>

Confirm the file is readable only by root:

stat -c '%A %U:%G %n' /root/peekaping-credentials.txt

Expected output:

-rw------- root:root /root/peekaping-credentials.txt

Step 6 - Review the container stack

The eight containers are pinned by image digest, so a rebuild can never silently pull a different version.

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

The migrate container is a one-shot job that applies the database schema and exits 0; the rest stay running. PostgreSQL and Redis have no host port, so they are reachable only by the other containers over the private Compose network.

Step 7 - Sign in to the web interface

Browse to http://<vm-public-ip>/ and sign in with the email and password from Step 5.

Self-registration is closed on this instance. Peekaping only accepts a registration while no administrator exists, and the image creates one on first boot before the port is reachable, so the account cannot be claimed by anyone else. You can confirm that from the VM:

curl -s -o /dev/null -w 'register: %{http_code}\n' -X POST http://127.0.0.1/api/v1/auth/register -H 'Content-Type: application/json' -d '{"email":"someone@example.com","password":"Example123!x"}'

Expected output:

register: 400

Step 8 - Create your first monitor

Choose Monitors then Create. Give the monitor a name, pick a type, and enter the target. An HTTP(S) monitor needs only a URL.

Peekaping supports many monitor types beyond plain HTTP, including keyword and JSON-query HTTP checks, TCP port, ICMP ping, DNS, push, Docker container, gRPC, SNMP, and direct database checks for MySQL/MariaDB, PostgreSQL, Microsoft SQL Server, MongoDB and Redis, plus MQTT, RabbitMQ and Kafka.

Save the monitor and Peekaping begins checking on the interval you set. The monitor page shows the current status, a live heartbeat bar, uptime over 24 hours, 7 days, 30 days and a year, and a response-time chart.

You can also confirm the API is serving authenticated requests from the VM. This signs in with the per-VM credentials and lists your monitors:

TOKEN=$(curl -s -X POST http://127.0.0.1/api/v1/auth/login -H 'Content-Type: application/json' -d "{\"email\":\"<PEEKAPING_ADMIN_EMAIL>\",\"password\":\"<PEEKAPING_ADMIN_PASSWORD>\"}" | jq -r '.data.accessToken // .accessToken'); curl -s -o /dev/null -w 'authenticated /monitors: %{http_code}\n' http://127.0.0.1/api/v1/monitors -H "Authorization: Bearer $TOKEN"

Expected output:

authenticated /monitors: 200

Step 9 - Publish a status page

Choose Status Pages then Create to publish a public page showing the monitors you select, so your users can check service health without access to the dashboard. Add notification channels under Notification Channels to receive alerts when a monitor goes down.

The image ships a complete security round-trip check you can run at any time. It proves the health endpoint is public, that unauthenticated and wrong-password requests are refused, that registration is closed, and that your per-VM credentials authenticate and can perform a real write:

sudo /usr/local/sbin/peekaping-roundtrip.sh

Step 10 - Secure the deployment

Peekaping is served over plain HTTP on port 80 in this image. Before putting it in front of users:

• Restrict the network security group so only the addresses that need the dashboard can reach port 80, and keep port 22 limited to your management network.
• Put your own domain and a TLS certificate in front of the VM, for example with an Azure Application Gateway, Azure Front Door, or by adding a certificate to the nginx configuration at /etc/nginx/sites-available/peekaping.
• Change the administrator password in the web interface under the account menu, and enable two-factor authentication there.

Maintenance

Restart or stop the whole stack through its systemd unit:

sudo systemctl restart peekaping.service

Check the application logs:

sudo docker compose --env-file /etc/peekaping/peekaping.env -f /etc/peekaping/compose.yaml logs --tail 20 api

Operating system security updates are applied automatically by unattended-upgrades, which is enabled in the image.

systemctl is-enabled unattended-upgrades.service

Expected output:

enabled

The PostgreSQL and Redis data live in the Docker named volumes peekaping_pgdata and peekaping_redis. Back them up with your usual Azure disk snapshot policy, or dump the database directly:

sudo docker compose --env-file /etc/peekaping/peekaping.env -f /etc/peekaping/compose.yaml exec -T postgres pg_dump -U peekaping peekaping > /tmp/peekaping-backup.sql

Support

Email support@cloudimg.co.uk for help with this image. Peekaping itself is developed by the upstream project and documented at docs.peekaping.com. cloudimg is not affiliated with, endorsed by, or sponsored by Peekaping; the Peekaping name is used to identify the open-source software shipped in this image.