Self-Hosted Deployment

Deploy Pongo on your own VPS or bare metal server for complete control over your infrastructure.

Requirements

System Requirements

OS: Ubuntu 22.04+ / Debian 11+ / CentOS 8+ (or any Linux distribution)
RAM: Minimum 1GB, 2GB+ recommended
Storage: 5GB+ for application and data
CPU: 1+ cores
Network: Public IP address and open ports 80/443

Software Requirements

Bun: Latest version (runtime)
Node.js: 18+ (alternative to Bun)
PostgreSQL: 14+ (recommended) or SQLite
Nginx: Latest (reverse proxy)
systemd: For process management
Git: For deployment

Installation

Install Bun

curl -fsSL https://bun.sh/install | bash
source ~/.bashrc

Install PostgreSQL (optional)

# Ubuntu/Debian
sudo apt update
sudo apt install postgresql postgresql-contrib

# Start and enable
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create database and user
sudo -u postgres psql
CREATE DATABASE pongo;
CREATE USER pongo WITH PASSWORD 'your-password';
GRANT ALL PRIVILEGES ON DATABASE pongo TO pongo;
\q

Clone repository

cd /opt
sudo git clone https://github.com/TimMikeladze/pongo.git
cd pongo

Install dependencies

bun install --frozen-lockfile

Configure environment

cp .env.example .env
nano .env

Set the following variables:

.env

DATABASE_URL=postgres://pongo:your-password@localhost:5432/pongo
ACCESS_CODE=your-secret-password
NODE_ENV=production
NEXT_PUBLIC_URL=https://your-domain.com

Run database migrations

# PostgreSQL
bun run db:pg:migrate

# SQLite (if using)
bun run db:sqlite:migrate

Build the application

bun run build

Process Management with systemd

Create systemd service files to manage Pongo processes.

Web Dashboard Service

Create /etc/systemd/system/pongo-web.service:

pongo-web.service

[Unit]
Description=Pongo Web Dashboard
After=network.target postgresql.service

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/pongo
Environment="NODE_ENV=production"
EnvironmentFile=/opt/pongo/.env
ExecStart=/root/.bun/bin/bun run start
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=pongo-web

[Install]
WantedBy=multi-user.target

Scheduler Service

Create /etc/systemd/system/pongo-scheduler.service:

pongo-scheduler.service

[Unit]
Description=Pongo Monitor Scheduler
After=network.target postgresql.service

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/pongo
Environment="NODE_ENV=production"
EnvironmentFile=/opt/pongo/.env
ExecStart=/root/.bun/bin/bun scheduler
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=pongo-scheduler

[Install]
WantedBy=multi-user.target

Archiver Service (Optional)

Create /etc/systemd/system/pongo-archiver.service:

pongo-archiver.service

[Unit]
Description=Pongo Data Archiver
After=network.target postgresql.service

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/pongo
Environment="NODE_ENV=production"
EnvironmentFile=/opt/pongo/.env
ExecStart=/root/.bun/bin/bun archiver
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal
SyslogIdentifier=pongo-archiver

[Install]
WantedBy=multi-user.target

Enable and Start Services

# Reload systemd
sudo systemctl daemon-reload

# Enable services to start on boot
sudo systemctl enable pongo-web
sudo systemctl enable pongo-scheduler
sudo systemctl enable pongo-archiver  # if using

# Start services
sudo systemctl start pongo-web
sudo systemctl start pongo-scheduler
sudo systemctl start pongo-archiver  # if using

# Check status
sudo systemctl status pongo-web
sudo systemctl status pongo-scheduler

Nginx Reverse Proxy

Configure Nginx as a reverse proxy with SSL termination.

Install Nginx and Certbot

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

Configure Nginx

Create /etc/nginx/sites-available/pongo:

pongo

server {
    listen 80;
    server_name your-domain.com;

    # Redirect HTTP to HTTPS
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    # SSL certificates (will be configured by certbot)
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    # SSL configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    # Logs
    access_log /var/log/nginx/pongo-access.log;
    error_log /var/log/nginx/pongo-error.log;

    # Proxy to Next.js
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        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;
        proxy_cache_bypass $http_upgrade;
    }

    # Optional: Scheduler API
    location /scheduler/ {
        proxy_pass http://localhost:3001/;
        proxy_http_version 1.1;
        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;
    }
}

Enable Site and Obtain SSL Certificate

# Enable site
sudo ln -s /etc/nginx/sites-available/pongo /etc/nginx/sites-enabled/

# Test configuration
sudo nginx -t

# Obtain SSL certificate
sudo certbot --nginx -d your-domain.com

# Reload Nginx
sudo systemctl reload nginx

Auto-Renewal

Certbot automatically sets up certificate renewal. Test it:

sudo certbot renew --dry-run

Firewall Configuration

# Allow SSH, HTTP, HTTPS
sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# Enable firewall
sudo ufw enable

# Check status
sudo ufw status

Monitoring and Logs

View Logs

# Web dashboard logs
sudo journalctl -u pongo-web -f

# Scheduler logs
sudo journalctl -u pongo-scheduler -f

# All Pongo services
sudo journalctl -t pongo-web -t pongo-scheduler -f

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

Service Status

# Check service status
sudo systemctl status pongo-web
sudo systemctl status pongo-scheduler

# Restart services
sudo systemctl restart pongo-web
sudo systemctl restart pongo-scheduler

Backup and Restore

PostgreSQL Backup

# Backup
sudo -u postgres pg_dump pongo > backup-$(date +%Y%m%d).sql

# Restore
sudo -u postgres psql pongo < backup-20250101.sql

Automated Backups

Create /opt/pongo/backup.sh:

backup.sh

#!/bin/bash
BACKUP_DIR="/opt/pongo/backups"
mkdir -p $BACKUP_DIR

# Backup database
sudo -u postgres pg_dump pongo | gzip > "$BACKUP_DIR/pongo-$(date +%Y%m%d-%H%M%S).sql.gz"

# Delete backups older than 30 days
find $BACKUP_DIR -name "pongo-*.sql.gz" -mtime +30 -delete

Add to crontab:

sudo chmod +x /opt/pongo/backup.sh
sudo crontab -e

# Add line:
0 2 * * * /opt/pongo/backup.sh

Updating Pongo

Pull latest changes

cd /opt/pongo
sudo git pull origin main

Install dependencies

bun install --frozen-lockfile

Run migrations

bun run db:pg:migrate

Rebuild application

bun run build

Restart services

sudo systemctl restart pongo-web
sudo systemctl restart pongo-scheduler

Troubleshooting

Services won’t start

Check logs: sudo journalctl -u pongo-web -n 50
Verify environment variables: sudo cat /opt/pongo/.env
Check file permissions: sudo chown -R www-data:www-data /opt/pongo

Database connection errors

Verify PostgreSQL is running: sudo systemctl status postgresql
Test connection: psql -h localhost -U pongo -d pongo
Check DATABASE_URL format in .env

Nginx errors

Test configuration: sudo nginx -t
Check logs: sudo tail -f /var/log/nginx/error.log
Verify port 3000 is listening: sudo netstat -tlnp | grep 3000

High memory usage

Check process memory: sudo systemctl status pongo-web
Adjust database connection pool size
Consider upgrading server resources

Security Recommendations

Keep system packages updated: sudo apt update && sudo apt upgrade
Use strong passwords for ACCESS_CODE and database
Restrict SSH access: Disable password auth, use SSH keys
Enable automatic security updates
Configure fail2ban to prevent brute force attacks
Regular backup verification
Monitor logs for suspicious activity
Use a dedicated user (not root) for running services

Deployment Options

Configuration

Self-Hosted Deployment

Requirements

System Requirements

Software Requirements

Installation

Process Management with systemd

Web Dashboard Service

Scheduler Service

Archiver Service (Optional)

Enable and Start Services

Nginx Reverse Proxy

Install Nginx and Certbot

Configure Nginx

Enable Site and Obtain SSL Certificate

Auto-Renewal

Firewall Configuration

Monitoring and Logs

View Logs

Service Status

Backup and Restore

PostgreSQL Backup

Automated Backups

Updating Pongo

Troubleshooting

Services won’t start

Database connection errors

Nginx errors

High memory usage

Security Recommendations

Build docs developers (and LLMs) love

Deployment Options

Configuration

​Requirements

​System Requirements

​Software Requirements

​Installation

​Process Management with systemd

​Web Dashboard Service

​Scheduler Service

​Archiver Service (Optional)

​Enable and Start Services

​Nginx Reverse Proxy

​Install Nginx and Certbot

​Configure Nginx

​Enable Site and Obtain SSL Certificate

​Auto-Renewal

​Firewall Configuration

​Monitoring and Logs

​View Logs

​Service Status

​Backup and Restore

​PostgreSQL Backup

​Automated Backups

​Updating Pongo

​Troubleshooting

​Services won’t start

​Database connection errors

​Nginx errors

​High memory usage

​Security Recommendations

Build docs developers (and LLMs) love

Requirements

System Requirements

Software Requirements

Installation

Process Management with systemd

Web Dashboard Service

Scheduler Service

Archiver Service (Optional)

Enable and Start Services

Nginx Reverse Proxy

Install Nginx and Certbot

Configure Nginx

Enable Site and Obtain SSL Certificate

Auto-Renewal

Firewall Configuration

Monitoring and Logs

View Logs

Service Status

Backup and Restore

PostgreSQL Backup

Automated Backups

Updating Pongo

Troubleshooting

Services won’t start

Database connection errors

Nginx errors

High memory usage

Security Recommendations