Skip to main content

Deployment Guide

Instructions for deploying Nebula components for local development and production.

Components​

  • Nebula Agent - Agent for GPU nodes
  • Nebula Daemon (nebulad) - Platform daemon for orchestration

Nebula Agent​

Agent binaries are automatically built and distributed via https://nebulactl.com for different platforms:

  • linux/amd64 - Linux x86_64
  • linux/arm64 - Linux ARM64
  • darwin/amd64 - macOS Intel
  • darwin/arm64 - macOS Apple Silicon

Download Agent​

# Linux AMD64
curl -O https://nebulactl.com/linux/amd64/nebula-agent
chmod +x nebula-agent
./nebula-agent --version

# Linux ARM64
curl -O https://nebulactl.com/linux/arm64/nebula-agent

# macOS Intel
curl -O https://nebulactl.com/darwin/amd64/nebula-agent

# macOS Apple Silicon
curl -O https://nebulactl.com/darwin/arm64/nebula-agent

Initial Setup​

SSH Configuration​

# Add SSH key to server
ssh-copy-id root@your-server-ip

# Verify connection
ssh root@your-server-ip

Nginx Setup (once)​

make deploy-nginx

This command:

  • Checks Nginx presence on server
  • Verifies Let's Encrypt SSL certificates
  • Installs configuration for nebulactl.com
  • Reloads Nginx

Deploy Binaries​

make deploy

This command:

  1. Builds binaries for all 4 platforms locally
  2. Uploads them to server via SSH
  3. Sets correct permissions
  4. Makes them available via HTTPS

Execution time: ~2-3 minutes

Nebula Daemon (nebulad)​

Platform daemon for managing agents, routing requests, and API gateway.

Quick Deploy​

# Quick deploy (build + copy + restart)
./scripts/deploy-daemon.sh -h your-server-ip

# Or via Makefile
make deploy-daemon HOST=your-server-ip

Initial Installation (with systemd)​

# Install systemd service, enable autostart
./scripts/deploy-daemon.sh -h your-server-ip --setup-service

# Or via Makefile
make deploy-daemon-full HOST=your-server-ip

Script Options​

./scripts/deploy-daemon.sh [options]

Options:
  -h, --host HOST       Server IP or hostname (required for deploy)
  -u, --user USER       SSH user (default: root)
  -P, --port PORT       SSH port (default: 22)
  -t, --target PLAT     Target platform (default: linux/amd64)
  -b, --build-only      Build only, no deploy
  -d, --deploy-only     Deploy only (binary already built)
  --setup-service       Install/update systemd service
  --no-restart          Don't restart service
  --dry-run             Show commands without execution
  --help                Show help

Examples:
./scripts/deploy-daemon.sh -h 192.168.1.100                    # Quick deploy
./scripts/deploy-daemon.sh -h 10.0.0.5 -u deploy               # Different user
./scripts/deploy-daemon.sh -h 10.0.0.5 --setup-service         # With systemd
./scripts/deploy-daemon.sh --build-only                        # Build only
./scripts/deploy-daemon.sh --build-only -t linux/arm64         # Build for ARM

Service Management​

After installation with --setup-service:

# Status
systemctl status nebulad

# Logs
journalctl -u nebulad -f

# Restart
systemctl restart nebulad

# Stop
systemctl stop nebulad

Daemon Configuration​

nebulad \
  --data-dir /var/lib/nebulad \   # SQLite and data directory
  --grpc-port 9090 \               # gRPC server
  --http-port 8080 \               # HTTP gateway
  --log-format json \              # Log format: json/text
  --log-level info                 # Level: debug/info/warn/error

Make Commands​

make help                  # Show all commands

# Agent
make deploy                # Deploy nebula-agent to nebulactl.com
make deploy-nginx          # Configure Nginx on remote server
make dist                  # Build agent for all platforms

# Daemon
make deploy-daemon HOST=<ip>       # Deploy nebulad
make deploy-daemon-full HOST=<ip>  # Deploy + systemd
make build-daemon-dist             # Build nebulad for distribution

Server Structure​

Agent​

/var/www/nebulactl/
├── linux/
│   ├── amd64/nebula-agent
│   └── arm64/nebula-agent
└── darwin/
    ├── amd64/nebula-agent
    └── arm64/nebula-agent

Daemon​

/usr/local/bin/nebulad          # Binary
/var/lib/nebulad/               # Data (SQLite)
/etc/systemd/system/nebulad.service  # Systemd unit

Building Binaries​

Hybrid approach for optimal GPU support:

linux/amd64 (main server platform):

  • Built via Docker with CGO_ENABLED=1
  • Uses Debian-based image for glibc compatibility
  • Full NVML/GPU monitoring support

Other platforms (linux/arm64, darwin/*):

  • Native cross-compilation with CGO_ENABLED=0
  • GPU monitoring via stub (returns empty GPU list)

Build flags:

  • -ldflags="-s -w" - Size reduction (removes debug info)
  • GOOS and GOARCH - Target platform

Troubleshooting​

Check Agent Availability​

for platform in "linux/amd64" "linux/arm64" "darwin/amd64" "darwin/arm64"; do
  echo -n "$platform: "
  curl -s -o /dev/null -w "%{http_code}\n" "https://nebulactl.com/$platform/nebula-agent"
done

Check Daemon Status​

# On server
systemctl status nebulad
journalctl -u nebulad --no-pager -n 50

# Remotely
ssh root@<ip> systemctl status nebulad

View Logs​

# Agent (Nginx)
ssh root@your-server-ip tail -f /var/log/nginx/nebulactl.access.log

# Daemon
ssh root@<ip> journalctl -u nebulad -f

Environment Variables​

For CI/CD or automation:

export DEPLOY_HOST=your-server-ip
export DEPLOY_USER=root
export DEPLOY_PORT=22
export SSH_KEY_PATH=~/.ssh/deploy_key
export DEPLOY_PATH=/usr/local/bin
export NEBULAD_DATA_DIR=/var/lib/nebulad
export NEBULAD_SERVICE_NAME=nebulad

./scripts/deploy-daemon.sh

GitHub Actions​

Deploy can be triggered via GitHub Actions:

  1. Go to Actions → Deploy Nebulad
  2. Click Run workflow
  3. Specify:
    • host — Server IP
    • user — SSH user (default: root)
    • setup_service — Install systemd service

Requires DEPLOY_SSH_KEY secret with private SSH key.

  • CI/CD Pipeline — Detailed CI/CD workflow description, build strategy, semantic versioning
  • GitHub Setup — Complete guide to configure GitHub repository for automated deployments