Upgrading from OSS to Cloud Edition

If you're running the open-source edition of Kuploy and want to add multi-tenant billing, licensing, and quota enforcement, you can upgrade to the Cloud edition in-place.

Prerequisites

Before upgrading:

1. Get a license — Sign up at kuploy.app and create a license
2. Create a Stripe account — Required for billing your users (see Cloud Billing Setup)
3. Back up your database — Always back up before major changes

# Backup current database
kubectl exec -it postgresql-0 -n database -- pg_dump -U kuploy kuploy > backup-pre-upgrade.sql

Upgrade Steps

1. Run the Upgrade

# Upgrade from OSS to Cloud
python deploy.py --edition cloud --domain console.example.com

# Watch rollout
kubectl rollout status deployment/kuploy -n kuploy

The deployer will prompt you for Cloud-specific configuration:

• STRIPE_SECRET_KEY — Your Stripe API secret key
• STRIPE_WEBHOOK_SECRET — Stripe webhook signing secret
• BETTER_AUTH_SECRET — Authentication secret (32+ characters)
• LICENSE_KEY — Your license key from kuploy.app
• PLATFORM_ADMIN_EMAIL — Email of the first platform admin

2. Link Your License

After the upgrade completes, link your instance to your license. See Licensing for claim code or manual configuration options.

3. Configure Billing

Set up Stripe products and plans for your users. See Cloud Billing Setup for the full walkthrough.

4. Verify the Upgrade

# Check the running image
kubectl get deployment kuploy -n kuploy -o jsonpath='{.spec.template.spec.containers[0].image}'

# Should show: ceduth/kuploy-cloud:latest

# Check pods are running
kubectl get pods -n kuploy

Database Migrations

kuploy-cloud runs database migrations automatically on every container startup, before the app starts. The Docker entrypoint runs:

1. Kuploy core migrations — schema changes for the base platform
2. Cloud-server migrations — schema changes for billing, plans, and subscriptions

You do not need to run any manual migration commands. When you deploy a new version, the pod startup handles schema changes before accepting traffic.

Pre-upgrade checklist

1. Back up your database (see Prerequisites above)
2. Deploy the new image — migrations run automatically
3. Watch the pod logs for Running cloud-server database migrations...
4. If a migration fails, the container exits with code 1 — your previous pod keeps running

danger

Never use drizzle-kit push (npm run db:push) in production. kuploy-cloud shares the same database as kuploy core, and db:push would try to delete all non-cloud tables. Only the sequential migration runner (db:migrate) is safe.

What Changes

Aspect	OSS	Cloud
Container image	ceduth/kuploy:latest	ceduth/kuploy-cloud:latest
Billing	None	Stripe-based subscription plans
License	Not required	Required (syncs with kuploy.app)
Quotas	None	Per-organization + aggregate
Admin dashboard	Basic	Full (Stripe, SMTP, theme, admins)
Authentication	Basic	Better Auth (OAuth, 2FA, teams)

Rollback

If you need to roll back to the OSS edition:

python deploy.py --edition oss --domain console.example.com

caution

Rolling back removes Cloud-specific features. Organizations, billing subscriptions, and Cloud-specific data remain in the database but won't be active.