Skip to content

deployment-guide.md

Latest commit

 

History

History
408 lines (300 loc) · 7.76 KB

deployment-guide.md

File metadata and controls

408 lines (300 loc) · 7.76 KB

Deployment Guide - Ubuntu VPS with systemd

This guide covers deploying Botical to a traditional Ubuntu VPS with systemd and Nginx.

Other deployment options:

Prerequisites

  • Ubuntu 22.04 LTS or later
  • Root or sudo access
  • Domain name pointing to your server (for HTTPS)
  • Resend account for email sending

1. Install Bun

curl -fsSL https://bun.sh/install | bash
source ~/.bashrc
bun --version  # Verify installation

2. Create Botical User (Optional but Recommended)

sudo useradd -r -m -s /bin/bash botical
sudo su - botical

3. Clone and Install

cd /opt
sudo git clone <repository-url> botical
sudo chown -R $USER:$USER botical
cd botical
bun install

4. Configure Environment

Create the configuration directory and file:

sudo mkdir -p /etc/botical
sudo nano /etc/botical/.env

Add the following configuration:

# Environment
NODE_ENV=production

# Server
BOTICAL_PORT=4096
BOTICAL_HOST=0.0.0.0
BOTICAL_DATA_DIR=/var/lib/botical
BOTICAL_LOG_LEVEL=info

# Auth & Email
APP_URL=https://your-domain.com
RESEND_API_KEY=re_xxxxxxxxxxxxxxxxxxxxx
EMAIL_FROM=noreply@your-domain.com

# Security - Generate with: openssl rand -base64 32
BOTICAL_ENCRYPTION_KEY=your-secure-encryption-key-here

Important: Generate a secure encryption key:

openssl rand -base64 32

Secure the config file:

sudo chmod 600 /etc/botical/.env
sudo chown botical:botical /etc/botical/.env  # If using botical user

5. Create Data Directory

sudo mkdir -p /var/lib/botical
sudo chown botical:botical /var/lib/botical  # Or your user

6. Create systemd Service

Copy the service file:

sudo cp /opt/botical/docs/botical.service /etc/systemd/system/botical.service

Or create manually:

sudo nano /etc/systemd/system/botical.service

Contents (adjust user/paths as needed):

[Unit]
Description=Botical AI Agent Server
Documentation=https://github.com/your-org/botical
After=network.target

[Service]
Type=simple
User=botical
Group=botical
WorkingDirectory=/opt/botical
EnvironmentFile=/etc/botical/.env
ExecStart=/home/botical/.bun/bin/bun run src/index.ts
ExecReload=/bin/kill -HUP $MAINPID
Restart=always
RestartSec=10
TimeoutStopSec=30

# Security hardening
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=read-only
PrivateTmp=true
PrivateDevices=true
ProtectKernelTunables=true
ProtectKernelModules=true
ProtectControlGroups=true
RestrictSUIDSGID=true
ReadWritePaths=/var/lib/botical

# Resource limits
LimitNOFILE=65535
MemoryMax=2G

# Logging
StandardOutput=journal
StandardError=journal
SyslogIdentifier=botical

[Install]
WantedBy=multi-user.target

7. Enable and Start Service

sudo systemctl daemon-reload
sudo systemctl enable botical
sudo systemctl start botical

Check status:

sudo systemctl status botical

8. Configure Nginx (Reverse Proxy)

Install Nginx:

sudo apt update
sudo apt install nginx

Create site configuration:

sudo nano /etc/nginx/sites-available/botical

Contents:

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 configuration (will be added by Certbot)
    # ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    # ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:4096;
        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;

        # WebSocket support
        proxy_read_timeout 86400;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/botical /etc/nginx/sites-enabled/
sudo rm /etc/nginx/sites-enabled/default  # Remove default site
sudo nginx -t  # Test configuration
sudo systemctl reload nginx

9. Setup SSL with Certbot

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

Certbot will automatically configure SSL and set up renewal.

10. Verify Installation

Test the health endpoint:

curl https://your-domain.com/health

Expected response:

{"status":"ok"}

Upgrade Workflow

To update Botical to a new version:

cd /opt/botical
sudo systemctl stop botical
git pull
bun install
# Migrations run automatically on startup
sudo systemctl start botical

For zero-downtime upgrades (if using multiple instances behind a load balancer):

# On each instance:
cd /opt/botical
git pull
bun install
sudo systemctl restart botical
# Wait for health check to pass before proceeding to next instance

Backup

Database Backup

# Single file backup
cp /var/lib/botical/botical.db /backup/botical-$(date +%Y%m%d).db

# Full directory backup (includes project databases)
tar -czf /backup/botical-full-$(date +%Y%m%d).tar.gz /var/lib/botical

Automated Backup (cron)

sudo crontab -e

Add:

# Daily backup at 2 AM
0 2 * * * tar -czf /backup/botical-$(date +\%Y\%m\%d).tar.gz /var/lib/botical
# Keep only last 7 days
0 3 * * * find /backup -name "botical-*.tar.gz" -mtime +7 -delete

Logs

View logs:

# Recent logs
sudo journalctl -u botical -n 100

# Follow logs in real-time
sudo journalctl -u botical -f

# Logs since last boot
sudo journalctl -u botical -b

# Logs from specific time
sudo journalctl -u botical --since "2024-01-01 00:00:00"

Troubleshooting

Service won't start

Check logs for errors:

sudo journalctl -u botical -e

Common issues:

  • Missing environment variables
  • Wrong file permissions
  • Port already in use

Permission errors

sudo chown -R botical:botical /var/lib/botical
sudo chown -R botical:botical /opt/botical

Database locked

sudo systemctl stop botical
# Wait for any locks to release
sleep 5
sudo systemctl start botical

Email not sending

  1. Check Resend API key is correct
  2. Verify EMAIL_FROM domain is verified in Resend
  3. Check logs for email-related errors

SSL certificate issues

# Test certificate
sudo certbot certificates

# Force renewal
sudo certbot renew --force-renewal

Security Checklist

  • BOTICAL_ENCRYPTION_KEY is set and secure
  • /etc/botical/.env has restricted permissions (600)
  • Firewall allows only ports 80, 443, 22
  • SSH key authentication only (disable password auth)
  • Regular security updates applied
  • Backup encryption enabled for off-site backups
  • Rate limiting configured in Nginx

Firewall Configuration (ufw)

sudo ufw allow 22/tcp    # SSH
sudo ufw allow 80/tcp    # HTTP (for Let's Encrypt)
sudo ufw allow 443/tcp   # HTTPS
sudo ufw enable

Resource Monitoring

Install monitoring tools:

sudo apt install htop iotop

Monitor resource usage:

# CPU and memory
htop

# Disk I/O
sudo iotop

# Disk space
df -h /var/lib/botical

Related Documentation