Documentation/Deployment/On-Premise Deployment

On-Premise Deployment

Run the entire Supero platform — API, data, and admin console — on infrastructure you control, then deploy your apps against it. No cloud account, no phone-home.

Overview

On-premise deployment is for teams that need Supero's backend to run entirely inside their own network — data residency, air-gapped environments, or internal policy that rules out a cloud-hosted API. You install a signed package on a VM you control, bring up the platform, and every login, CRUD call, and schema upload stays on your infrastructure.

There are two separate things you deploy, and they happen in order. First, the backend: the Supero platform itself, shipped as a Debian package and installed once per environment. Second, apps: each app you build is a self-contained bundle that you deploy separately, pointing it at your backend. Apps push their data model (schemas) into your backend and serve their own UI.

Phase	What	How often
A — Backend	Install and initialize the Supero platform (API + admin console) on a VM you own	Once per environment
B — Apps	Deploy each app you build, pointing it at your backend	Once per app

ℹ️ What this edition includes

The on-premise package ships the core platform runtime and admin console — the CRUD/data engine, authentication, schemas, and the admin panel for managing domains, projects, and API keys. You still build and generate apps in Supero Cloud (App Studio, AI-generated schemas and UI); the on-premise package is where you deploy and run them. Connectors, the integrations catalog, and a self-hosted AI agent are available as separate, optional add-on packages — see the On-Prem Add-On Packages page.

A license is a signed file, installed offline and verified locally on your backend — there is no license server your platform has to reach, and no runtime dependency on Supero once it is running.

System Requirements

Backend host (the Supero platform)

Resource	Minimum	Recommended
OS	Ubuntu 22.04 / Debian 12, x86_64 (amd64)	same
CPU	2 vCPU	4 vCPU
RAM	4 GB	8 GB
Disk	5 GB free, plus room for your data to grow	20 GB+
Access	root / sudo	—
Inbound ports	80	443, with TLS enabled

Only the reverse proxy port needs to be reachable from outside the host — everything else the platform depends on binds to the host itself. Runtime dependencies (MongoDB, nginx, Redis) are installed for you by the CLI; see Deploying the Backend below.

App host (where each app runs — can be the same VM)

Resource	Requirement
Runtime	Python 3.9+, or Docker
Network	Reachable to your backend's URL
Package install	Internet access to install the Supero SDK from PyPI, or provide it as offline wheels
Port	One free port per app for its UI (the default is 5648; give each app on a host a distinct port)

Phase A — Deploy the Backend

⚠️ Two different programs are called supero

The supero used throughout this page is the platform operator CLI that the on-premise package installs. It is run with sudo and manages a self-hosted Supero installation. There is a second, unrelated supero installed with pip, which runs a single generated application on a developer machine and has an entirely different command set — see CLI (App Runner). They share a name and nothing else. If a command below is not recognised, check which one is on your PATH.

Bring the platform up once per environment. Do this on a fresh VM that meets the requirements above.

1. Install the package

bash

# verify the package checksum before installing
sha256sum -c supero-core_<version>-1_amd64.deb.sha256

# install
sudo dpkg -i supero-core_<version>-1_amd64.deb
sudo apt-get -f install -y      # only if dpkg reports a missing dependency

2. Install runtime dependencies

bash

# installs and starts MongoDB, nginx, and Redis for you
sudo supero install-deps

3. Initialize and start

bash

sudo supero init      # generates secrets, wires up MongoDB and Redis
sudo supero start
sudo supero status     # confirm the platform's services are active
sudo supero health     # confirm health checks pass

4. First-run setup

Open http://<vm-ip>/setup in a browser (or run sudo supero setup --interactive on the VM for a headless flow) and provide:

•Domain name — the top of your Supero hierarchy for this deployment (lowercase, e.g. acme-corp)
•Admin email and password (12+ characters, mixing upper/lower case and a digit)
•A license key, if your build requires one
•MongoDB connection — accept the local default, or point at your own managed MongoDB; the wizard tests the connection before finishing

bash

# leave setup mode and enter normal serving mode
sudo supero restart

Sign in at http://<vm-ip>/ with the admin email and password you just set. This first account is created as a domain_admin — it can create projects, manage schemas, and issue API keys.

5. Verify

bash

sudo supero status
sudo supero health

# confirm login works against your own backend
curl -s -X POST http://<vm-ip>/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"<your-password>","domain_name":"your-domain"}' \
  | grep -q access_token && echo "LOGIN OK" || echo "LOGIN FAILED"

⚠️ Secure MongoDB before going further

Before you expose this deployment beyond your own testing, secure the MongoDB instance the CLI installed: enable authentication, create dedicated users, and put the authenticated connection string in your platform configuration (or re-enter it at the setup wizard). Do this before opening the backend up to real traffic.

Phase B — Deploy an App

Build your app the same way you would for Supero Cloud — describe it, refine its schemas, and generate it. Then, instead of going live on Supero Cloud, download the app bundle and deploy it against your own backend. The bundle is self-contained: it uploads its own schemas to whichever backend you point it at and serves its own UI, so nothing about it stays tied to Supero Cloud once deployed on-prem.

1. Provision a domain, project, and API key

On your backend's admin panel, signed in as a domain_admin: confirm the domain exists (created during backend setup), create or choose a project for the app, then generate an API key scoped to that project and copy it.

2. Point the app at your backend

Each app bundle ships with an on-prem deploy script alongside its default one. Pass your backend URL, domain, project, and API key as flags — the script writes them into the app's local configuration, repoints its UI at your backend, uploads its schemas into your domain/project, and starts the app.

bash

./run_on_prem.sh --backend_url https://your-domain \
  --domain your-domain --project your-project --api-key ak_... \
  --port 5648 --no-interactive

A Docker alternative is also included in the bundle:

bash

SUPERO_BACKEND_URL=https://your-domain SUPERO_DOMAIN=your-domain \
SUPERO_PROJECT=your-project SUPERO_API_KEY=ak_... PORT=5648 \
docker compose -f docker-compose.yml -f docker-compose.on-prem.yml up --build

💡 No internet on the app host?

The platform package does not ship SDK wheels for apps. On a host with internet access, download them ahead of time — pip download 'supero>=<minimum-version>' -d ./wheels — copy the wheels folder to the app host, then deploy with --sdk-dir ./wheels instead of installing from PyPI.

Deploying more than one app to the same host? Each app needs its own project, its own API key, and its own UI port — reusing a project across multiple apps risks schema collisions, so prefer one project per app, and give each app a distinct port.

3. Verify

•The app's schemas appear under its project in your backend's admin panel.
•The app's saved backend URL points at your own domain, not a Supero-hosted one.
•The app UI loads in a browser with no network calls back to Supero Cloud.
•A create-then-read through the app UI persists after a page reload, confirming the full CRUD path.

License Lifecycle

A license is a signed file you install on the backend; it is verified locally, offline, against keys already built into the platform. There is no license server the platform calls out to at runtime.

bash

sudo supero license install /path/to/license.lic
sudo supero restart
sudo supero license status      # shows licensed, domain, tier, days remaining

To renew or upgrade, install a new license file for the same domain and restart:

bash

sudo supero license install /path/to/new-license.lic
sudo supero restart

A license's domain must match your deployment's domain. If a license is close to expiring, the platform enters a grace window and keeps running until the grace period ends — install a renewal before then.

Going Air-Gapped

Once it is running, the platform has no runtime dependency on Supero Cloud — logins, CRUD, and schema uploads all stay inside your network. Getting to a fully offline deployment means accounting for three things that need network access at install time, not at runtime:

•Backend dependencies — supero install-deps uses your package manager to install MongoDB, nginx, and Redis. Point it at an internal mirror, or pre-install these yourself, on a host with no internet access.
•The app's Python SDK — the platform package does not bundle SDK wheels. Download them ahead of time on a host with internet access and deploy the app with --sdk-dir, as shown above.
•The app UI's front-end libraries — a generated app's UI loads its JavaScript framework, styling, chart library, and web fonts from public CDNs by default. On a fully offline host, vendor these assets into the app bundle before deploying, or run the app on a host that can reach those CDNs.

Troubleshooting

Symptom	Check / fix
Services won't start	sudo supero status and sudo supero health; then sudo supero logs <service> for whichever one is failing (supero logs --help lists them)
Database errors on startup	Confirm MongoDB is running and reachable at the URI in your platform configuration
Web UI returns errors	Confirm nginx is running and proxying correctly; sudo supero status
Setup wizard won't finalize	Confirm the platform is reachable from your browser and rerun sudo supero setup --interactive; check the logs
App can't reach the backend	Confirm the backend URL the app was deployed with is correct and reachable, the backend is running, and the API key belongs to the target domain and project

Reference

On the backend

Path	What
/usr/bin/supero	The CLI: install-deps, init, start, stop, restart, status, health, setup, license, logs, version
/etc/supero/	Runtime configuration and the installed license
/var/www/supero/frontend/	The admin console

CLI

bash

sudo supero install-deps | init | start | stop | restart | status | health
sudo supero setup --interactive
sudo supero license install <file> | status
sudo supero logs <service> 200            # supero logs --help lists services
sudo supero version                       # baked mode/edition/license info

In an app bundle

bash

./run.sh                                   # deploy to Supero Cloud (default)
./run_on_prem.sh --backend_url <url>       # deploy to your own backend
docker compose -f docker-compose.yml -f docker-compose.on-prem.yml up --build

Next Steps

•Choosing a Deployment Option — a full side-by-side comparison of Supero Cloud, your own AWS or GCP, and on-premise.
•Deploy to Your Own AWS or GCP — publish your app's UI into your own cloud account instead of self-hosting the whole platform.
•On-Prem Add-On Packages — add connectors, the integrations catalog, or a self-hosted AI agent to your on-premise backend.
•Python SDK — the client library your apps use to talk to whichever backend you point them at.

← PreviousDeploy to AWS / GCP — Verification Runbook Next →On-Prem Add-On Packages

On this page