LILLYDOO Pulse - Setup Guide

1 Quick Start

What is LILLYDOO Pulse?

LILLYDOO Pulse is a self-hosted uptime monitoring platform that tracks the availability and performance of your servers, websites, SSL certificates, and network services. It supports ping, HTTP, SSL, and port monitoring with real-time dashboards, alerting, and maintenance windows.

System Requirements

Python 3.8 or higher
pip (Python package manager)
Linux, macOS, or Windows host
Minimum 512 MB RAM, 1 CPU core
Network access to monitored targets

Starting the Server

bash

# Clone the repository
git clone https://github.com/your-org/lillydoo-pulse.git
cd lillydoo-pulse

# Install dependencies
pip install -r requirements.txt

# Start the server
python backend/app.py

Tip Use a virtual environment to keep dependencies isolated: python -m venv venv && source venv/bin/activate

2 Initial Setup

First Admin Token

On the first run, LILLYDOO Pulse auto-generates an admin token and prints it to the console output. Look for a line like:

output

[LILLYDOO Pulse] Admin token generated: sw_admin_a1b2c3d4e5f6...
[LILLYDOO Pulse] Save this token - it will not be shown again.

Important Save this admin token immediately. It is displayed only once at first startup and cannot be recovered.

Accessing the Dashboard

Open your browser and navigate to:

url

http://your-server:5000

Replace your-server with the hostname or IP address of the machine running LILLYDOO Pulse.

Creating Your First Monitor

From the sidebar, select the monitor type (Ping, HTTP, SSL, or Port).
Click Add Monitor and fill in the target address.
Set the check interval and save.
The monitor will begin checking within 60 seconds.

3 Installing the Agent

The LILLYDOO Pulse agent runs on your servers and reports system metrics (CPU, memory, disk) back to the central server. Follow these steps to install it on any Linux host.

Step 1: Generate an Agent Token

From the admin panel or via the API, create a new agent token:

bash

curl -X POST http://YOUR_SERVER:5000/api/tokens/ \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Server Frankfurt", "type": "agent"}'

Step 2: Install the Agent on Your Linux Server

bash

curl -s http://YOUR_SERVER:5000/agent/install.sh | sudo bash -s -- \
  --token AGENT_TOKEN_FROM_STEP_1 \
  --server http://YOUR_SERVER:5000

Note The install script creates a systemd service called lillydoo-pulse-agent, configures the token, and starts the service automatically.

Step 3: Verify the Agent Is Running

bash

# Check service status
systemctl status lillydoo-pulse-agent

# Follow live logs
journalctl -u lillydoo-pulse-agent -f

4 Installing the Network Poller

Network pollers run checks (ping, HTTP, port) from remote locations, giving you multi-location monitoring coverage. Install pollers in different data centers or offices to detect regional outages.

Step 1: Generate a Poller Token

bash

curl -X POST http://YOUR_SERVER:5000/api/tokens/ \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Poller Frankfurt", "type": "poller"}'

Step 2: Install the Poller

bash

curl -s http://YOUR_SERVER:5000/poller/install.sh | sudo bash -s -- \
  --token POLLER_TOKEN \
  --server http://YOUR_SERVER:5000 \
  --name "Frankfurt Office" \
  --location "FFM"

Step 3: Assign Monitors to the Poller

After installation, assign which monitors the poller should check:

bash

curl -X PUT http://YOUR_SERVER:5000/api/poller/1/assign \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"monitor_ids": [1, 2, 3]}'

Tip Deploy pollers in multiple geographic locations (e.g., US-East, EU-West, APAC) to detect regional outages that a single location might miss.

5 Multi-Source Monitoring

Multi-Source Monitoring lets a single Ping, SSL, HTTP, or Port monitor be checked from multiple network locations at the same time. Every monitor always includes the Public source — the LILLYDOO Pulse server itself, running on the public Upsun instance — and can additionally be checked from any registered Network Poller.

Why use it

The Public source cannot reach private hosts (e.g. intern.lillydoo.local, 10.0.0.0/8). A poller inside that network can.
You want to verify reachability from multiple independent network locations (e.g. Frankfurt office and Ludwigsburg office) to detect regional or link-specific outages.
You want a single logical monitor rather than duplicating the same target per location.

How to configure it

In the Add Monitor / Edit Monitor modal (for Ping, SSL, HTTP, or Port) there is a Sources field shown as a multi-select. Public is always selected and cannot be removed. The remaining options are every currently active, registered Network Poller. Pick as many as you need and save.

Selectable sources: Public (always) + every active registered Poller.
Each source produces its own check result on the monitor's configured interval.
Aggregated status: all sources up = up; any source down = down; mix of up and down = warning.
Supported for all monitor types — Ping, SSL, HTTP, and Port monitors all support multi-source checks.

Illustration

                      ┌──────────────┐
                      │  intern.app  │   (private host)
                      └──────┬───────┘
                             │
       ┌─────────────────────┼─────────────────────┐
       │                     │                     │
   ┌───┴───┐            ┌────┴────┐           ┌────┴────┐
   │ Public│            │ Poller  │           │ Poller  │
   │(Upsun)│            │  FFM    │           │  LuWi   │
   └───┬───┘            └────┬────┘           └────┬────┘
       │                     │                     │
       ▼ (cannot reach)      ▼ (up, 8ms)          ▼ (up, 12ms)
   ┌───────────┐         ┌───────────┐        ┌───────────┐
   │   DOWN    │         │    UP     │        │    UP     │
   └───────────┘         └───────────┘        └───────────┘

   Aggregated status:  WARNING  (mix of up and down)

6 Security Best Practices

Token Management

Never share admin tokens. Admin tokens have full access to create, delete, and modify all resources.
Use scoped tokens (agent or poller type) for automated systems.
Rotate tokens on a regular schedule (every 90 days recommended).
Revoke tokens immediately if a server is compromised.

Use HTTPS in Production

Always run LILLYDOO Pulse behind a reverse proxy with TLS in production. Example nginx configuration:

nginx

server {
    listen 443 ssl http2;
    server_name monitor.example.com;

    ssl_certificate     /etc/letsencrypt/live/monitor.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/monitor.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Firewall Rules

Agents and pollers only need outbound port 443 (HTTPS) to reach the LILLYDOO Pulse server.
Block all inbound connections to agent/poller hosts from the internet.
Restrict access to the LILLYDOO Pulse admin interface by IP if possible.

File Permissions

bash

# Restrict config files to root only
sudo chmod 600 /etc/lillydoo-pulse/agent.conf
sudo chmod 600 /etc/lillydoo-pulse/poller.conf
sudo chown root:root /etc/lillydoo-pulse/*.conf

Warning Configuration files contain authentication tokens. Ensure they are not readable by unprivileged users (mode 600, owned by root).

7 Architecture Overview

LILLYDOO Pulse uses a hub-and-spoke architecture. The central server orchestrates monitoring while agents and pollers report data from distributed locations.

                        +-------------------------------+
                        |    LILLYDOO Pulse Server          |
                        |    (Dashboard + API + DB)       |
                        +------+----------------+------+
                               |                |
                    outbound   |                |   outbound
                    connect    |                |   connect
                               |                |
              +----------------+--+          +--+----------------+
              |   Agent            |          |   Network Poller   |
              |   (Server Metrics)  |          |   (Remote Checks)  |
              +-------------------+          +-------------------+
              | CPU, Memory, Disk |          | Ping, HTTP, Port  |
              +-------------------+          +-------------------+

         Agents and pollers initiate outbound connections to the server.
         No inbound ports need to be opened on agent/poller hosts.

Key Concepts

Outbound-only connections: Agents and pollers connect to the server, not the other way around. This simplifies firewall configuration and works behind NAT.
Agents collect system-level metrics (CPU, memory, disk usage) from the host they are installed on.
Pollers execute network checks (ping, HTTP, SSL, port) against external targets from their location.
Multiple pollers can be deployed in different geographic locations to provide multi-region monitoring and detect localized outages.

8 Troubleshooting

Problem	Possible Cause	Solution
Agent won't connect	Invalid token, wrong server URL, or firewall blocking outbound traffic	Verify the token is correct, check the server URL in `/etc/lillydoo-pulse/agent.conf`, ensure outbound port 443 (or 5000) is open
Poller shows no tasks	No monitors assigned to this poller	Use the assign API endpoint to link monitor IDs to the poller (see Section 4, Step 3)
Token expired or invalid	Token was revoked or has exceeded its lifetime	Generate a new token via the API and update the configuration file, then restart the service
Dashboard not loading	Server process not running or port conflict	Check if the process is running with `ps aux \| grep app.py`, verify port 5000 is not in use
SSL check shows wrong expiry	Server clock is out of sync	Synchronize the system clock with NTP: `sudo timedatectl set-ntp true`

Still stuck? Check the server logs with journalctl -u lillydoo-pulse -f or look at the application output in the terminal where you started the server.

LILLYDOO Pulse Setup Guide

1 Quick Start

What is LILLYDOO Pulse?

System Requirements

Starting the Server

2 Initial Setup

First Admin Token

Accessing the Dashboard

Creating Your First Monitor

3 Installing the Agent

Step 1: Generate an Agent Token

Step 2: Install the Agent on Your Linux Server

Step 3: Verify the Agent Is Running

4 Installing the Network Poller

Step 1: Generate a Poller Token

Step 2: Install the Poller

Step 3: Assign Monitors to the Poller

5 Multi-Source Monitoring

Why use it

How to configure it

Illustration

6 Security Best Practices

Token Management

Use HTTPS in Production

Firewall Rules

File Permissions

7 Architecture Overview

Key Concepts

8 Troubleshooting