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:
- 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.
- Admin account. Name, email, username, and password. The password is hashed with Argon2id.
- 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:
- Open Uptime Kuma and go to Settings.
- Open the Backup section.
- 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
- Add monitors for the services you want to track.
- Configure notifications for email and Slack.
- Create additional status pages for different audiences.
- Connect an AI assistant with the MCP server in
pulse-cli. - Generate API keys for automation.