Agent Deployment Guide

Deploy CuliUptime monitoring agents on hosting providers or VPS/servers for global monitoring coverage.

🌍 Overview

CuliUptime agents are lightweight PHP scripts that monitor your services from multiple locations worldwide. Unlike scheduled cron jobs, these agents need to be deployed as web-accessible endpoints on hosting providers or VPS/servers.

Key Requirements

Web hosting or VPS/Server with PHP support
SSL certificate (can be self-signed) for secure communication
Web-accessible deployment (not cron scheduling)
Internet connectivity for monitoring external services

🎯 Deployment Options

Choose your deployment method based on your infrastructure:

Option	Best For	Requirements
Shared Hosting	Cost-effective, simple setup	PHP 7.4+, HTTPS support
VPS/Dedicated Server	Full control, multiple agents	Root access, nginx/Apache
Cloud Hosting	Scalability, global reach	AWS/GCP/Azure, load balancer

📋 Prerequisites

Hosting Requirements

PHP 7.4 or higher
cURL extension enabled
JSON extension enabled
HTTPS/SSL certificate (mandatory)
Web server (Apache/nginx/LiteSpeed)

Before You Start

Purchase hosting or provision VPS from your preferred provider
Domain/subdomain pointing to your hosting (e.g., agent-us.yourdomain.com)
SSL certificate installed (Let's Encrypt or self-signed)
FTP/SSH access to upload agent files

🚀 Quick Deployment

Step 1: Download Agent Files

# Download agent files from CuliUptime repository
wget https://github.com/chiplonton/culiuptime/archive/main.zip
unzip main.zip
cd culiuptime-main/agents/

Or download directly from your CuliUptime installation:

# If you have CuliUptime installed locally
cd /path/to/culiuptime/agents/

Step 2: Configure Agent

Edit the configuration section at the top of web_agent.php (lines 17-19):

// AGENT CONFIGURATION - SET THESE VALUES DURING DEPLOYMENT
define('AGENT_ID', getenv('AGENT_ID') ?: 'your-agent-uuid-here');
define('AGENT_SECRET_KEY', getenv('AGENT_SECRET_KEY') ?: 'your-shared-secret-here');  
define('PLATFORM_API_KEY', getenv('PLATFORM_API_KEY') ?: 'platform-api-key-here');

Configuration Options:

Environment Variables (Recommended):

# Set environment variables in your hosting panel or .htaccess
export AGENT_ID="agent-us-east-001"
export AGENT_SECRET_KEY="your-agent-secret-from-culiuptime-env"
export PLATFORM_API_KEY="your-platform-api-key"

Direct File Editing:

define('AGENT_ID', 'agent-us-east-001');
define('AGENT_SECRET_KEY', 'your_agent_secret_from_culiuptime_env_here');
define('PLATFORM_API_KEY', 'your_platform_api_key_here');

Step 3: Upload to Hosting

Option 1: FTP/SFTP Upload

# Create agent directory on your server
mkdir -p /var/www/html/agent

# Upload web_agent.php via SCP
scp web_agent.php [email protected]:/var/www/html/agent/

# Or use SFTP
sftp [email protected]
put web_agent.php /var/www/html/agent/

Option 2: cPanel File Manager

Login to cPanel
- Access your hosting control panel
Navigate to File Manager
- Open File Manager from cPanel dashboard
- Go to public_html or your domain's document root
Create Agent Directory
- Right-click and select "Create Folder"
- Name it agent (or your preferred agent directory name)
Upload Agent File
- Enter the agent directory
- Click "Upload" button
- Select web_agent.php from your computer
- Wait for upload to complete

Option 3: FTP Client (FileZilla, WinSCP, etc.)

Connect to your hosting server using FTP credentials
Navigate to public_html or document root
Create agent directory if it doesn't exist
Upload web_agent.php to the agent directory

Step 4: Set Directory Permissions

# Set appropriate permissions
chmod 755 /var/www/html/agent/
chmod 644 /var/www/html/agent/web_agent.php

Step 5: Test Agent Deployment

Access your agent URL to verify it's working:

https://your-domain.com/agent/web_agent.php

Expected Response:

{
    "status": "ok",
    "agent_location": "US-East-1",
    "timestamp": "2024-01-15T10:30:00Z",
    "version": "1.0"
}

🔐 SSL Certificate Setup

Option 1: Let's Encrypt (Recommended)

For VPS/Dedicated Servers:

# Install certbot
sudo apt update
sudo apt install certbot python3-certbot-nginx

# Get SSL certificate
sudo certbot --nginx -d agent-us.yourdomain.com

# Verify auto-renewal
sudo certbot renew --dry-run

For Shared Hosting:

Most hosting providers offer free Let's Encrypt via cPanel
Enable SSL in hosting control panel
Ensure "Force HTTPS" is enabled

Option 2: Self-Signed Certificate

Generate self-signed certificate:

# Create self-signed certificate (valid for 1 year)
openssl req -x509 -newkey rsa:4096 -keyout private.key -out certificate.crt -days 365 -nodes

# When prompted, enter your agent domain name for "Common Name"
# Example: agent-eu.yourdomain.com

Install on nginx:

server {
    listen 443 ssl;
    server_name agent-eu.yourdomain.com;
    
    ssl_certificate /etc/ssl/certs/certificate.crt;
    ssl_certificate_key /etc/ssl/private/private.key;
    
    root /var/www/html/agent;
    index web_agent.php;
    
    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

Install on Apache:

<VirtualHost *:443>
    ServerName agent-eu.yourdomain.com
    DocumentRoot /var/www/html/agent
    
    SSLEngine on
    SSLCertificateFile /etc/ssl/certs/certificate.crt
    SSLCertificateKeyFile /etc/ssl/private/private.key
    
    <Directory /var/www/html/agent>
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

Important Notes for Self-Signed Certificates:

Self-signed certificates will show security warnings in browsers
Perfect for internal monitoring and testing
CuliUptime agents will accept self-signed certificates
Consider using Let's Encrypt for production deployments

🏢 Hosting Provider Specific Instructions

Shared Hosting (cPanel)

Upload Files
- Login to cPanel
- Open File Manager → public_html
- Create agent folder
- Upload web_agent.php (single file)
Enable SSL
- Go to SSL/TLS in cPanel
- Enable "Force HTTPS Redirect"
- Install Let's Encrypt if available
PHP Configuration
- Ensure PHP 7.4+ is selected
- Verify cURL and JSON extensions are enabled

VPS/Dedicated Server

Ubuntu/Debian:

# Install required packages
sudo apt update
sudo apt install nginx php-fpm php-curl php-json certbot

# Create agent directory
sudo mkdir -p /var/www/html/agent
sudo chown www-data:www-data /var/www/html/agent

# Upload and configure agent files
# (Follow steps above)

# Configure nginx virtual host
# (Use nginx config above)

# Get SSL certificate
sudo certbot --nginx -d agent.yourdomain.com

CentOS/RHEL:

# Install required packages
sudo yum update
sudo yum install nginx php-fpm php-curl php-json

# Follow similar steps as Ubuntu

Cloud Hosting (AWS/GCP/Azure)

AWS EC2 Example:

# Launch EC2 instance with Amazon Linux
# Install nginx and PHP
sudo yum update
sudo amazon-linux-extras install nginx1 php7.4

# Configure security groups to allow HTTPS (port 443)
# Follow VPS setup instructions above

# Use AWS Certificate Manager for SSL
# Or install Let's Encrypt

🔧 Advanced Configuration

Multiple Agents per Server

Deploy multiple agents on the same server for different monitoring locations:

# Directory structure
/var/www/html/
├── agent-us-east/
│   └── web_agent.php (configured for US-East-1)
├── agent-us-west/
│   └── web_agent.php (configured for US-West-1)
└── agent-eu/
    └── web_agent.php (configured for EU-Central-1)

nginx configuration:

# US East agent
server {
    listen 443 ssl;
    server_name agent-us-east.yourdomain.com;
    root /var/www/html/agent-us-east;
    # ... SSL config
}

# US West agent
server {
    listen 443 ssl;
    server_name agent-us-west.yourdomain.com;
    root /var/www/html/agent-us-west;
    # ... SSL config
}

Load Balancer Configuration

For high-availability agent deployment:

upstream culiuptime_agents {
    server agent1.yourdomain.com;
    server agent2.yourdomain.com;
    server agent3.yourdomain.com;
}

server {
    listen 443 ssl;
    server_name agents.yourdomain.com;
    
    location / {
        proxy_pass https://culiuptime_agents;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

🔍 Testing and Verification

Agent Health Check

Test agent functionality:

# Basic connectivity test
curl -k https://agent.yourdomain.com/web_agent.php

# Test with authentication
curl -k -H "X-Agent-Key: your_agent_secret_key" \
     https://agent.yourdomain.com/web_agent.php

Monitor Integration

Add Agent in CuliUptime Dashboard
- Go to Settings → Agents
- Click "Add Agent"
- Enter agent URL: https://agent.yourdomain.com/web_agent.php
- Enter agent location: US-East-1
- Test connection
Verify Agent Status
- Agent should appear as "Online" in dashboard
- Check last heartbeat timestamp
- Review agent logs for errors

Log Monitoring

Check web server logs:

# nginx access logs
sudo tail -f /var/log/nginx/access.log

# PHP error logs
sudo tail -f /var/log/php/error.log

# Agent specific logs (if configured)
tail -f /var/www/html/agent/logs/agent.log

🛡️ Security Best Practices

1. Secure Configuration

Use Environment Variables (Recommended):

# Set in hosting control panel or .htaccess
export AGENT_ID="production-agent-us-east-001"
export AGENT_SECRET_KEY="your-secure-agent-secret-from-culiuptime"
export PLATFORM_API_KEY="your-secure-platform-api-key"

Or edit web_agent.php with secure values:

// Production configuration in web_agent.php
define('AGENT_ID', 'production-agent-us-east-001');
define('AGENT_SECRET_KEY', 'your-secure-agent-secret-from-culiuptime');
define('PLATFORM_API_KEY', 'your-secure-platform-api-key');

2. File Permissions

# Secure file permissions
chmod 755 /var/www/html/agent/              # Directory
chmod 644 /var/www/html/agent/web_agent.php # Agent script (readable)
chown www-data:www-data /var/www/html/agent/ -R

3. Firewall Rules

# Allow only HTTPS traffic
sudo ufw allow 22    # SSH
sudo ufw allow 443   # HTTPS
sudo ufw deny 80     # Block HTTP
sudo ufw enable

4. Hide Directory Listings

nginx:

location /agent/ {
    autoindex off;  # Disable directory browsing
}

Apache (.htaccess):

Options -Indexes
DirectoryIndex web_agent.php

📊 Monitoring Agent Performance

Performance Metrics

Monitor your agents for optimal performance:

Response Time: Agent should respond within 5 seconds
Memory Usage: Typically under 32MB per request
CPU Usage: Minimal impact on server resources
Network Traffic: Low bandwidth usage

Health Monitoring

Set up monitoring for your agents:

# Create monitoring script
#!/bin/bash
# monitor-agents.sh

AGENTS=(
    "https://agent-us.yourdomain.com/web_agent.php"
    "https://agent-eu.yourdomain.com/web_agent.php"
    "https://agent-asia.yourdomain.com/web_agent.php"
)

for agent in "${AGENTS[@]}"; do
    status=$(curl -s -o /dev/null -w "%{http_code}" -k "$agent")
    if [ "$status" -eq 200 ]; then
        echo "✅ $agent - OK"
    else
        echo "❌ $agent - Failed ($status)"
    fi
done

🆘 Troubleshooting

Common Issues

1. SSL Certificate Errors

Error: SSL certificate problem: unable to get local issuer certificate

Solution:

Verify SSL certificate is properly installed
For self-signed certificates, ensure they're properly configured
Check certificate expiration date

2. Permission Denied

Error: Permission denied accessing web_agent.php

Solution:

# Fix file permissions
sudo chown www-data:www-data /var/www/html/agent/ -R
sudo chmod 644 /var/www/html/agent/web_agent.php

3. Agent Configuration Issues

Error: Agent authentication failed or invalid configuration

Solution:

Check that AGENT_ID, AGENT_SECRET_KEY, and PLATFORM_API_KEY are properly set in web_agent.php
Verify values match those in your CuliUptime main instance
Test with environment variables if using that approach

4. Agent Not Connecting

Verify AGENT_SECRET_KEY and PLATFORM_API_KEY values in web_agent.php are correct
Check that values match your CuliUptime main instance configuration
Ensure HTTPS is working on both agent and main CuliUptime instance
Test network connectivity between agent and main server

Debug Mode

The agent includes built-in error reporting. Check web server error logs for debugging:

# Check web server logs for agent errors
sudo tail -f /var/log/nginx/error.log
sudo tail -f /var/log/apache2/error.log
sudo tail -f /var/log/php/error.log

Support

Need help with agent deployment?

🎯 Next Steps

Deploy Multiple Agents globally for comprehensive monitoring
Set Up Load Balancing for high-availability agent clusters
Configure Monitoring for your agent infrastructure
Integrate with Main Instance and verify global monitoring coverage

Happy monitoring from anywhere! 🌍

🌍 Overview​

Key Requirements​

🎯 Deployment Options​

📋 Prerequisites​

Hosting Requirements​

Before You Start​

🚀 Quick Deployment​

Step 1: Download Agent Files​

Step 2: Configure Agent​

Step 3: Upload to Hosting​

Step 4: Set Directory Permissions​

Step 5: Test Agent Deployment​

🔐 SSL Certificate Setup​

Option 1: Let's Encrypt (Recommended)​

Option 2: Self-Signed Certificate​

🏢 Hosting Provider Specific Instructions​

Shared Hosting (cPanel)​

VPS/Dedicated Server​

Cloud Hosting (AWS/GCP/Azure)​

🔧 Advanced Configuration​

Multiple Agents per Server​

Load Balancer Configuration​

🔍 Testing and Verification​

Agent Health Check​

Monitor Integration​

Log Monitoring​

🛡️ Security Best Practices​

1. Secure Configuration​

2. File Permissions​

3. Firewall Rules​

4. Hide Directory Listings​

📊 Monitoring Agent Performance​

Performance Metrics​

Health Monitoring​

🆘 Troubleshooting​

Common Issues​

Debug Mode​

Support​

🎯 Next Steps​

🌍 Overview

Key Requirements

🎯 Deployment Options

📋 Prerequisites

Hosting Requirements

Before You Start

🚀 Quick Deployment

Step 1: Download Agent Files

Step 2: Configure Agent

Step 3: Upload to Hosting

Step 4: Set Directory Permissions

Step 5: Test Agent Deployment

🔐 SSL Certificate Setup

Option 1: Let's Encrypt (Recommended)

Option 2: Self-Signed Certificate

🏢 Hosting Provider Specific Instructions

Shared Hosting (cPanel)

VPS/Dedicated Server

Cloud Hosting (AWS/GCP/Azure)

🔧 Advanced Configuration

Multiple Agents per Server

Load Balancer Configuration

🔍 Testing and Verification

Agent Health Check

Monitor Integration

Log Monitoring

🛡️ Security Best Practices

1. Secure Configuration

2. File Permissions

3. Firewall Rules

4. Hide Directory Listings

📊 Monitoring Agent Performance

Performance Metrics

Health Monitoring

🆘 Troubleshooting

Common Issues

Debug Mode

Support

🎯 Next Steps