Deployment

Self-Hosting Guide

Deploy Ondara on your own infrastructure for full data control and maximum cost savings.

Server Requirements

Minimum (up to 50K MAU)

• 2 vCPU / 4 GB RAM
• 20 GB SSD storage
• Docker 24+ & Docker Compose v2
• Linux (Ubuntu 22.04+, Debian 12+, or Amazon Linux 2023)

Recommended (100K+ MAU)

• 4 vCPU / 8 GB RAM
• 50 GB SSD storage
• Managed PostgreSQL (RDS, Cloud SQL, etc.)
• Managed Redis (ElastiCache, Memorystore, etc.)

Network: Standard licenses require outbound HTTPS to api.ondara.co for heartbeats. With offline JWT licenses, no internet connectivity is required.

Step 1: Get a License Key

1. Log into the Ondara Console
2. Navigate to Settings → Licenses
3. Click Create License, select the services you need (Data Service, Economy Service), and set the max instances
4. Copy the license key — it's only shown once!

Step 2: Deploy with Docker Compose

Clone the repository

git clone https://github.com/ondara-cloud/ondara-services.git
cd ondara-services/self-hosted

Configure environment

cp .env.example .env
# Edit .env with your values:
# ONDARA_LICENSE_KEY=ondara_lic_xxxxxxxxxxxx
# M2M_SECRET=<generate a random 32+ char string>
# DB_PASSWORD=<strong password for PostgreSQL>
# CORS_ORIGINS=https://yourgame.com

Start the services

docker compose up -d

# Check that everything is running
docker compose ps

# View logs
docker compose logs -f

Verify health

curl http://localhost:8091/health  # Data Service
curl http://localhost:8092/health  # Economy Service

Both should return {"status":"ok"}

Step 3: Environment Variables Reference

Variable	Required	Description
`ONDARA_LICENSE_KEY`	✅	License key from Ondara Console
`M2M_SECRET`	✅	Shared secret for control plane communication
`DB_PASSWORD`	⚠️	PostgreSQL password (default: ondara_selfhosted)
`CORS_ORIGINS`	No	Allowed CORS origins (default: *)
`CONTROL_PLANE_URL`	No	Ondara API URL (default: https://api.ondara.co)
`DEPLOYMENT_MODE`	No	Set automatically to "selfhosted" by docker-compose

Step 4: Connect with the Dashboard

1. In the Ondara Console, go to Settings → Infrastructure
2. Select Self-Hosted mode
3. Enter your service URLs:
- • Data Service: http://your-server:8091
- • Economy Service: http://your-server:8092
4. Click Test All Connections to verify connectivity
5. Save. The console will now route data operations through your self-hosted services.

Offline JWT Licenses

Ondara supports offline JWT license tokens that allow your self-hosted services to run without any internet connectivity. Unlike the standard heartbeat-based licensing, offline licenses are self-contained JWT tokens valid for up to one year.

How it works

• The license key is a signed JWT containing your plan, allowed services, max instances, and expiry date
• Services validate the JWT locally using Ondara's public key — no outbound network call needed
• Hardware binding (optional) ties the license to specific machine fingerprints for extra security
• Tokens auto-renew when connectivity is available, but continue working offline for the full validity period

Configuration

# .env
ONDARA_LICENSE_KEY=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

# Optional: bind to specific hardware
ONDARA_HARDWARE_BIND=true

# Optional: disable heartbeat entirely (offline mode)
ONDARA_OFFLINE_MODE=true

To request an offline license, go to Console → Settings → Licenses and select "Offline JWT" as the license type. Professional and Enterprise self-hosted plans include offline licenses.

Architecture

┌─────────────────────┐       ┌──────────────────────┐
│   Your Game Client  │       │   Ondara Console     │
│   (Unity/Unreal/Web)│       │   (Dashboard)        │
└────────┬────────────┘       └────────┬─────────────┘
         │                              │
         │ API Key auth                 │ Clerk JWT
         ▼                              ▼
┌─────────────────────────────────────────────────────┐
│                 Your Server                          │
│  ┌──────────────┐    ┌──────────────────┐           │
│  │ Data Service  │    │ Economy Service   │          │
│  │ :8091         │    │ :8092             │          │
│  └──────┬───────┘    └──────┬───────────┘           │
│         │                    │                       │
│  ┌──────▼────┐   ┌──────────▼────┐  ┌────────────┐ │
│  │ PostgreSQL │   │  PostgreSQL    │  │   Redis    │ │
│  │ (data)     │   │  (economy)     │  │            │ │
│  └────────────┘   └───────────────┘  └────────────┘ │
└──────────────────────┬──────────────────────────────┘
                       │ License heartbeat (HTTPS)
                       ▼
              ┌────────────────┐
              │ api.ondara.co  │
              │ (Control Plane)│
              └────────────────┘

Troubleshooting

Services won't start

Check docker compose logs for errors. Common issues: invalid license key, PostgreSQL connection failure, or port conflicts.

License activation failed

Ensure your server can reach api.ondara.co over HTTPS. Check that ONDARA_LICENSE_KEY is set correctly and the license hasn't been revoked.

Health check returns offline

The heartbeat has a 1-hour grace period. If the control plane is unreachable for over an hour, services will return 503. Restore connectivity to resume.

Next Steps

Configuration →

Fine-tune service settings

Unity SDK →

Connect your game to your self-hosted backend