System Requirements

Minimum Requirements

ComponentSpecificationNotes
CPU
2 cores (4 recommended)For handling concurrent health checks
RAM
4 GB (8 GB recommended)Supports up to 200 endpoints
Storage
20 GB SSDFor database and logs
Network
Stable internet connectionFor pulling images and monitoring

Recommended Production Requirements

CPU4-8 coresFor 500+ endpoints with optimal performance
RAM16 GBSupports up to 1000 endpoints comfortably
Storage100 GB SSDRecommended for production with extended retention
OSUbuntu 22.04 LTS or RHEL 8+Long-term support versions

Supported Platforms

Linux Distributions

  • • Ubuntu 20.04 LTS, 22.04 LTS
  • • Debian 11, 12
  • • CentOS 8, 9
  • • RHEL 8, 9
  • • Fedora 37+
  • • Amazon Linux 2

Cloud Providers

  • • AWS EC2
  • • Google Cloud Compute Engine
  • • Microsoft Azure VMs
  • • DigitalOcean Droplets
  • • Linode
  • • Any VPS with Docker support

Windows & macOS: Supported for development only. Production deployment on Linux is strongly recommended.

Software Prerequisites

Before installing Pulsimo, ensure you have:

  1. Docker Engine - Version 20.10.0 or higher
  2. Docker Compose - Version 2.0.0 or higher
  3. Git - For cloning the repository
  4. Available Ports - 80, 443, 3000, 5432, 6379, 8080

Installing Docker

(Suggested to use official installation method)

Ubuntu/Debian

If you don't have Docker installed, follow these steps:

1. Update Package Index

sudo apt-get update

2. Install Required Packages

sudo apt-get install -y \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

3. Add Docker's Official GPG Key

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

4. Install Docker Engine

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

5. Verify Installation

sudo docker --version
sudo docker compose version

Quick Installation with Docker Compose

The fastest way to get Pulsimo running:

# Clone the repository
git clone https://github.com/Cloud-Council/pulsimo.git
cd pulsimo
# Copy environment template
cp .env.example .env
# Edit environment variables (optional)
nano .env
# Start all services
docker compose up -d --remove-orphans
# View logs
docker compose logs -f
# Access Pulsimo
open http://localhost:3000

Success! Pulsimo should now be running on http://localhost:3000. Default credentials will be created on first run.

Environment Configuration

Configure Pulsimo by editing the .env file. Here are the essential variables you need to set:

⚡ Quick Start - Minimum Configuration

# Generate secure passwords
HOST_IP=192.168.1.100                        # Your server IP
POSTGRES_PASSWORD=$(openssl rand -base64 24) # Secure password
JWT_SECRET=$(openssl rand -base64 32)        # Secure secret

# Frontend configuration
NEXT_PUBLIC_API_URL=http://monitoring.company.com:8080
NEXT_PUBLIC_WS_URL=ws://monitoring.company.com:8080

Essential Variables

VariableDescriptionExample
HOST_IPServer IP or domain where Pulsimo is accessible192.168.1.100
POSTGRES_PASSWORDDatabase password (must be secure!)K7mP9x2vL4nQ...
JWT_SECRETSecret for signing authentication tokensXkJ7vM2pL9...
NEXT_PUBLIC_API_URLBackend API endpoint URLhttp://monitoring.company.com:8080
NEXT_PUBLIC_WS_URLWebSocket endpoint for real-time updatesws://monitoring.company.com:8080

Optional: SMTP Configuration (Email Alerts)

Configure SMTP to enable email notifications for alerts and incidents:

Gmail

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your@gmail.com
SMTP_PASSWORD=app-password
FROM_EMAIL=your@gmail.com

AWS SES

SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_USERNAME=<smtp-user>
SMTP_PASSWORD=<smtp-pass>
FROM_EMAIL=alerts@domain.com

📚 For complete environment variable documentation including checker intervals, timeouts, and advanced settings, see the Environment Variables Guide.

Post-Installation Steps

1. First Login with Default Credentials

Pulsimo comes with a default system administrator account for on-premise deployments. Use these credentials to login at http://localhost:3000:

Default Login Credentials

Email:
superadmin@pulsimo.io
Password:
admin

⚠️ IMPORTANT: Change this password immediately after your first login for security reasons. The superadmin account is immutable and cannot be deleted.

2. Verify Services

Check that all containers are running:

docker compose ps

3. Access the Dashboard

  • Frontend: http://localhost:3000
  • API: http://localhost:8080

4. Change Default Password (Critical)

For security, immediately change the default password after logging in:

  1. Login with the default credentials shown above
  2. Navigate to Users page from the dashboard
  3. Find the superadmin@pulsimo.io user (marked with a "System" badge)
  4. Click the key icon (🔑) to change the password
  5. Set a strong password and save

Security Note

The superadmin account is immutable and cannot be deleted. It's protected at the database level to ensure you always have administrative access. While you can change the password, the email and role cannot be modified.

Troubleshooting

Port Conflicts

If you get port conflict errors, you can change ports in docker-compose.yml:

# Change from 3000:3000 to 8000:3000
ports:
  - "8000:3000"

Container Won't Start

View logs for specific services:

docker compose logs api
docker compose logs frontend
docker compose logs checker

Next Steps

After successful installation:

Quick Start Guide

Set up your first monitoring endpoints and alerts

Environment Variables

Configure advanced settings and integrations

Production Deployment

Best practices for production infrastructure

Alert Notifications

Set up Slack, Discord, Email, and webhook alerts

Need Help?

If you encounter issues during installation, check our troubleshooting guide or visit our GitHub repository.

View on GitHub