Skip to content

Getting started

This page covers the requirements, the Docker Compose quick start, the first-run setup wizard, and reaching your public page.

Requirements

  • Docker with the Compose plugin.
  • A persistent volume for the SQLite database.

Pulse runs as a single container. The image is a static binary on Alpine with ca-certificates. No external database server is required.

To serve a public page over HTTPS, you also need a reverse proxy in front of Pulse that holds TLS certificates and forwards to port 8080. See Status pages for examples.

Quick start with the installer

Pulse is a single static binary with the admin UI embedded. It needs no Docker, Node.js or database server. The installer detects your OS and CPU architecture (Linux and macOS, amd64 and arm64), downloads the matching binary, verifies its checksum, and installs it to /usr/local/bin. It asks a few questions (port, data directory, HTTPS, whether monitors may target LAN addresses). On Linux with systemd it also installs an auto-starting pulse service. On macOS it prints the command to run.

curl -fsSL https://raw.githubusercontent.com/memetics19/pulse/main/deploy/install.sh | sh

Manage the Linux service with systemctl status pulse, journalctl -u pulse -f, and systemctl restart pulse.

Install with apt (Debian and Ubuntu)

The signed apt repository has every release for amd64 and arm64:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://apt.shreeda.xyz/key.gpg | sudo tee /etc/apt/keyrings/memetics19.gpg >/dev/null
echo "deb [signed-by=/etc/apt/keyrings/memetics19.gpg] https://apt.shreeda.xyz stable main" |
  sudo tee /etc/apt/sources.list.d/memetics19.list
sudo apt update && sudo apt install pulse

The pulse package runs Pulse as a systemd service under the pulse user. It starts right away on port 8080, so open http://<host>:8080/setup to finish. The wizard asks for the setup token that Pulse printed in its log. Get it with sudo journalctl -u pulse | grep "setup token" | tail -n 1. Its settings are in /etc/pulse/pulse.env (the same variables as Configuration), and an upgrade keeps your changes:

sudo nano /etc/pulse/pulse.env
sudo systemctl restart pulse

The data is in /var/lib/pulse. Removing the package stops the service and keeps the data.

pulse-agent sends a host's metrics to Pulse. After sudo apt install pulse-agent, set PULSE_SERVER in /etc/pulse-agent/agent.env, put the agent token in /etc/pulse-agent/token, then sudo systemctl enable --now pulse-agent. pulse-cli is the command line client.

On Fedora or RHEL, download the .rpm from the Releases page and install it with sudo dnf install ./pulse-<version>-1.x86_64.rpm.

Quick start with Docker Compose

Alternatively, run it as a container. Clone the repository and start it:

git clone https://github.com/memetics19/pulse.git
cd pulse
docker compose up -d

The provided docker-compose.yml defines a single service and a named volume:

services:
  pulse:
    image: pulse:latest
    ports:
      - "8080:8080"
    environment:
      PULSE_DB: /data/pulse.db
      RESEND_API_KEY: ${RESEND_API_KEY:-}
      PULSE_EMAIL_FROM: ${PULSE_EMAIL_FROM:-}
      SLACK_WEBHOOK_URL: ${SLACK_WEBHOOK_URL:-}
      PULSE_SECURE_COOKIES: ${PULSE_SECURE_COOKIES:-false}
      PULSE_ALLOW_PRIVATE_MONITORS: ${PULSE_ALLOW_PRIVATE_MONITORS:-false}
    volumes:
      - pulse_data:/data
    restart: unless-stopped

volumes:
  pulse_data:

The wizard asks for the setup token that Pulse printed in its log. Get it with:

docker compose logs pulse | grep "setup token" | tail -n 1

Data persists on the pulse_data volume. The SQLite file lives at the path set by PULSE_DB, which defaults to /data/pulse.db. See Configuration for the full list of environment variables.

First-run setup wizard

On first start, every route redirects to a setup wizard. Until setup is done, Pulse prints a one-time setup token in its log at startup:

setup token: open /setup and enter this token: ...

The wizard collects:

  1. Setup token. The token from the log. It proves that you are the one setting up this instance. Each start prints a new token, so use the most recent one.
  2. Admin account. Name, email, username, and password. The password is hashed with Argon2id.
  3. Branding. Logo and site name.

The last step shows the database file the server will create. The server decides it from PULSE_DB or PULSE_DATA_DIR, and the wizard cannot change it. To use another file, change those settings and restart Pulse first. See Configuration.

After you complete the wizard, the app runs normally and the setup routes no longer redirect.

If you start Pulse on a database that already has an admin, the wizard does not run. Pulse adopts the database and you log in with an existing account. See When pulse.json is missing.

For an automated install that runs setup itself, you can set your own token with PULSE_SETUP_TOKEN, or turn the check off with PULSE_SETUP_TOKEN=off. See Setup token.

Open http://localhost:8080 to begin. If you are running behind a reverse proxy, open the host you configured.

Reaching your public page

After setup, the default status page is available on the host that serves Pulse. To reach a public page such as status.shreeda.xyz, point a DNS record at your reverse proxy and configure the proxy to forward that host to Pulse on port 8080. Pulse resolves which page to show from the request Host header. See Status pages for the full setup, including Caddy and nginx examples.

Importing from Uptime Kuma

If you already track services in Uptime Kuma, the CLI imports your monitors and groups from an Uptime Kuma backup file. This is a one-time migration convenience.

Export the backup file from Uptime Kuma

The import reads a backup file, not a live connection. Uptime Kuma does not provide a REST API for reading monitor configuration, and its API keys only grant access to the Prometheus metrics endpoint, which exposes monitor names and up or down state but not the URL, type, interval, or thresholds. The backup file is the only export that contains the full monitor configuration.

To produce it in Uptime Kuma:

  1. Open Uptime Kuma and go to Settings.
  2. Open the Backup section.
  3. Choose Export and save the JSON file (for example backup.json).

Install pulse-cli

pulse-cli is published with each release and is not installed by deploy/install.sh, which sets up the server only. Download it for your platform:

VERSION=$(curl -fsSL https://api.github.com/repos/memetics19/pulse/releases/latest | grep -o '"tag_name": *"[^"]*"' | cut -d'"' -f4)
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
ARCH=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')
BASE="https://github.com/memetics19/pulse/releases/download/${VERSION}"

curl -fsSLo pulse-cli "${BASE}/pulse-cli_${OS}_${ARCH}"
curl -fsSLo SHA256SUMS "${BASE}/SHA256SUMS"
grep " pulse-cli_${OS}_${ARCH}\$" SHA256SUMS | sed "s|pulse-cli_${OS}_${ARCH}|pulse-cli|" | shasum -a 256 -c -
chmod +x pulse-cli && sudo mv pulse-cli /usr/local/bin/

The checksum step is the same one install.sh performs for the server binary. Skip it only if you have another way to verify the download, for example the apt package.

Run the import

pulse-cli import uptime-kuma \
  --file backup.json \
  --server https://status.example.com \
  --token pulse_live_xxxxxxxx

The command reads the backup file and creates the monitors in Pulse under a single "Imported" group, through the REST API. --server is your Pulse base URL and --token is an API key with the monitors:write scope (create one under Admin → API keys). Historical check data is not imported, because Uptime Kuma backups do not include it.

For HTTP and keyword monitors, the import also carries over the HTTP options Pulse supports:

Uptime Kuma Pulse
method method, when it is GET, HEAD or POST
body body, for POST only
headers headers. An Authorization: Bearer header becomes bearer auth.
basic_auth_user, basic_auth_pass basic auth
ignoreTls tls_verify set to false
maxredirects of 0 follow_redirects set to false
accepted_statuscodes accepted_statuses
invertKeyword keyword_mode set to not_contains

A monitor that needs something Pulse does not have is skipped and listed at the end. That covers other HTTP methods, NTLM, mTLS or OAuth auth, and an Authorization header that is not a bearer token.

Next steps