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

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

This will install Docker, ClickHouse, and Purl Server with auto-generated 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

Configure License Key (Optional)

Pro and Enterprise users: set your license key to unlock advanced features. Free tier works without a key.

bash

# Set your license key as environment variable
export PURL_LICENSE_KEY="your-license-key-here"

# Or add to your Purl server config
echo 'PURL_LICENSE_KEY=your-license-key-here' >> /etc/purl/purl.env

# Restart Purl to apply
sudo systemctl restart purl

Where do I get my license key?

After purchasing a Pro or Enterprise plan, your license key is automatically emailed to you. No license key is needed for the free tier — just install and start using Purl.

For Docker installs:

yaml

# Add to your docker-compose.yml under purl service:
environment:
  PURL_LICENSE_KEY: "your-license-key-here"

# Restart
docker compose up -d

For Kubernetes:

bash

kubectl create secret generic purl-license \
  --from-literal=PURL_LICENSE_KEY="your-license-key-here" \
  -n purl

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

Verify Installation

Check that everything is running correctly.

bash

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

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

bash

# Search logs
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.

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

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