Installation Guide

Get Purl running in minutes

Follow these steps to install the Purl server and start collecting logs from your infrastructure.

Prerequisites

Linux server (Ubuntu 20.04+, Debian 11+, CentOS 8+)
Minimum 512MB RAM, 1 CPU core
Docker & Docker Compose (for Docker install) or Perl 5.38+ (for systemd install)
Pro or Enterprise license key (optional, for paid features)

Install Purl Server

Choose your preferred installation method and run the installer.

bash

# Free plan — no license key required
curl -fsSL https://purlogs.com/install.sh | sudo bash -s -- -i

# Pro / Enterprise — supply your key in the same command
curl -fsSL https://purlogs.com/install.sh \
  | sudo PURL_LICENSE_KEY=<your-key-from-purlogs.com/license-keys> bash -s -- -i

Installs Purl Server and ClickHouse via Docker Compose with auto-generated credentials. Requires Docker with the Compose plugin to be installed first. The installer writes PURL_LICENSE_KEY into /opt/purl/.env and prints your admin password and API key at the end (also saved to /opt/purl/.credentials).

Install Purl Agent on Remote Servers

Install the Vector-based log agent on each server you want to collect logs from.

bash

curl -fsSL https://purlogs.com/install.sh | sudo bash -s -- --agent -i

The agent uses Vector to collect logs from /var/log/, systemd journal, and Docker containers, then ships them to your Purl server.

During installation, you'll be prompted for:

Purl Server URL — e.g. http://your-server:3000
API Key — shown after Purl Server install

Add Your License Key — not needed on Free, required for Pro/Enterprise

Purl runs on the Free plan with no key and no quotas: unlimited servers, agents, users, alert rules and saved searches, plus KQL search, live tail, pattern analysis and Telegram/Slack alerts. A license key is what unlocks the paid feature gates.

Without PURL_LICENSE_KEY, the server serves the Free plan and every Pro/Enterprise endpoint returns a feature-gate error.

Pro ($39/mo) — custom dashboards, AI query & log analysis, ingest pipelines, backup & restore, Elasticsearch-compatible API, Kubernetes monitoring, webhook alerts
Enterprise ($199/mo) — everything in Pro plus SSO/SAML, LDAP and audit logs

Compare Free, Pro and Enterprise

Already installed without a key? Add it and restart:

bash

# Docker install — the installer wrote /opt/purl/.env
echo 'PURL_LICENSE_KEY=<your-key-from-purlogs.com/license-keys>' >> /opt/purl/.env

# Restart to apply
cd /opt/purl && docker compose up -d

bash

# Systemd install — the installer wrote /etc/purl/purl.env
echo 'PURL_LICENSE_KEY=<your-key-from-purlogs.com/license-keys>' >> /etc/purl/purl.env

# Restart to apply
sudo systemctl restart purl

bash

# Kubernetes — the purl pod loads purl-secrets via envFrom
kubectl patch secret purl-secrets -n purl --type merge \
  -p '{"stringData":{"PURL_LICENSE_KEY":"<your-key-from-purlogs.com/license-keys>"}}'

# Restart purl deployment
kubectl rollout restart deployment/purl -n purl

Where do I get my license key?

After subscribing to Pro or Enterprise, your key is emailed to you and is always available at purlogs.com/license-keys. Confirm which plan the server is actually running with curl http://localhost:3000/api/license.

Verify Installation

Check that the server is up and talking to ClickHouse.

bash

# Check health
curl http://localhost:3000/api/health

# Expected response:
# {"status":"ok","clickhouse":"connected"}

Send Your First Log

A fresh install has an empty database. Ship one log line yourself so the next step has something to find.

bash

# POST /api/logs accepts a single JSON object, an array, or NDJSON.
# YOUR_API_KEY is printed at the end of the server install
# (Docker: also saved as API_KEY in /opt/purl/.credentials).
curl -X POST http://localhost:3000/api/logs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "level": "info",
      "message": "Hello from Purl",
      "service": "hello-purl",
      "host": "localhost"
    }
  ]'

# Expected response:
# {"status":"ok","inserted":1}

Only the payload shape matters — timestamp defaults to the time the server received the log, level defaults to INFO, and service / host default to unknown. Add an optional meta object for structured fields. Ingested logs are buffered and flushed to ClickHouse every ~2 seconds, so give it a moment before searching.

Find It in Purl

Search for the log you just sent, then open the dashboard.

bash

# Search for the log from Step 5
curl -H "X-API-Key: YOUR_API_KEY" \
  "http://localhost:3000/api/logs?service=hello-purl&range=1h&limit=10"

# Expected response — your log is in "hits", "total" is 1:
# {"hits":[{"level":"info","message":"Hello from Purl",...}],"total":1,"query":""}

If total is 0, wait a couple of seconds for the ingest buffer to flush and retry. Then open http://localhost:3000 — log in as admin with the password printed by the installer and you will see hello-purl in the log list. Once your agents from Step 2 are running, their logs land here too.

bash

# KQL search — same endpoint, filter by level
curl -H "X-API-Key: YOUR_API_KEY" \
  "http://localhost:3000/api/logs?q=level:ERROR&range=1h&limit=10"

Configuration

Customize Purl with environment variables.

Environment Variables

Variable	Default	Description
`PURL_PORT`	3000	Server port
`PURL_CLICKHOUSE_PASSWORD`	—	ClickHouse password
`PURL_API_KEYS`	—	Comma-separated API keys
`PURL_LICENSE_KEY`	—	License key (Pro/Enterprise)
`PURL_RETENTION_DAYS`	30	Log retention days
`PURL_TELEGRAM_BOT_TOKEN`	—	Telegram bot token for alerts
`PURL_TELEGRAM_CHAT_ID`	—	Telegram chat ID
`PURL_SLACK_WEBHOOK_URL`	—	Slack webhook URL for alerts

Architecture

Purl Architecture

Server 1

Purl Agent (Vector)

Server 2

Purl Agent (Vector)

Server N

Purl Agent (Vector)

HTTP + API Key

Purl Server

Purl API

:3000

ClickHouse

:8123

API Key Authentication

Rate Limiting (1000/min)

WebSocket Live Tail

Configurable Retention

Explore Features

KQL search, live tail, alerts, dashboards

View Plans

Compare Free, Pro, and Enterprise