Domain Administration

Manage subdomain provisioning, custom domain registration, and domain purchases for your kuploy-cloud platform.

Subdomain Provisioning

Every kuploy-cloud instance can provision *.kuploy.app subdomains for its users' applications. Subdomains are managed through the kuploy.app licensing hub — your instance communicates with the Domain API automatically.

How It Works

1. A user requests a subdomain (e.g., myapp) through the application UI
2. Your kuploy-cloud instance checks availability with kuploy.app
3. If available, the subdomain is reserved and DNS is provisioned
4. The subdomain (myapp.kuploy.app) goes live instantly

Subdomain Limits

Subdomain allocation is controlled by your platform plan:

Plan	Free Subdomains
Hobby	1
Starter	2
Growth	5
Business	10
Enterprise	Unlimited

Subdomain Rules

• 3-63 characters
• Lowercase letters, numbers, and hyphens only
• Cannot start or end with a hyphen
• Must be unique across all Kuploy users

Reserved Names

The following subdomain names are reserved and cannot be used:

www, app, api, admin, mail, smtp, pop, imap, ftp, ssh,
ns1, ns2, dns, test, dev, staging, prod, production,
beta, alpha, status, help, support, docs, blog, cdn,
static, assets, media, images, img, dashboard, billing,
account, login, signup, register, auth, oauth, sso, kuploy

Custom Domain Management

Custom domains allow your users to attach their own domains (e.g., app.example.com) to their applications.

Requirements

• Starter plan or higher (custom domains are not available on the Hobby plan)
• DNS configuration by the end user (CNAME or A record)

Custom Domain Limits

Plan	Custom Domains
Hobby	0
Starter	3
Growth	10
Business	50
Enterprise	Unlimited

Wildcard DNS Setup

For platforms serving many applications, configure a wildcard DNS record pointing to your cluster's ingress IP:

*.yourdomain.com.  A  <your-ingress-ip>

This allows users to create subdomains of your domain (e.g., app1.yourdomain.com, app2.yourdomain.com) without individual DNS entries.

SSL Certificates

SSL certificates for custom domains are provisioned automatically via Let's Encrypt. Ensure:

• DNS records are properly configured before adding the domain
• Your ingress controller supports automatic certificate provisioning
• CAA records (if present) allow Let's Encrypt: yourdomain.com. CAA 0 issue "letsencrypt.org"

Domain Purchasing

Domain purchasing allows your end users to search for, buy, and manage custom domains directly from the kuploy-cloud dashboard, without leaving your platform.

How It Works

1. Users search for available domains on the landing page or My Domains dashboard page
2. Available domains show badges and pricing
3. Users on eligible plans can purchase domains through the checkout flow
4. DNS records are automatically configured to point to your server
5. Purchased domains can be assigned to applications immediately

Access Control

Domain purchasing uses a license-first, plan-fallback feature gate:

Priority	Check	Source	Description
1st	License feature	cloud_license_cache.features.domainPurchase	Read directly from DB. If your kuploy.app platform plan (e.g., Enterprise) enables domainPurchase, all users on your instance can purchase domains — no per-user plan check needed.
2nd (fallback)	Subscription plan feature	cloud_plans.features.domainPurchase	Checked only if the license check doesn't grant access. Enabled per organization plan (Pro/Business by default).

How it works in practice:

Your License	User's Plan	Result
Enterprise with domainPurchase: true	Any (even Free)	Allowed — license grants platform-wide access
No license / no domainPurchase	Pro or Business	Allowed — plan fallback grants access
No license / no domainPurchase	Free	Blocked — user sees "Upgrade Required"

This means you can either:

• Enable it platform-wide by having an Enterprise license with the domainPurchase feature
• Enable it per-plan by configuring Pro/Business plans with domainPurchase: true in your kuploy.app plan catalog

License check reads from database

The license check reads cloud_license_cache directly from the database, not from volatile in-memory state. This means it works reliably even after server restarts or Next.js hot-reloads.

Purchasable Domain Limits (Default Plans)

Plan	Purchasable Domains
Free	0
Pro	3
Business	10

These limits are configurable — you can adjust them in kuploy.app when defining your plan catalog.

Landing Page Integration

When a domain registrar is configured, the landing page shows a domain search bar in the hero section across all landing page templates. Visitors (even unauthenticated) can search for domain availability:

• While the registrar status loads, a skeleton placeholder is shown to prevent layout shift
• Available domains display a green "Available" badge
• Clicking Buy or Sign Up to Buy takes users to sign-up (if not logged in) then the checkout page
• The search bar hides itself automatically if no registrar is configured

User Purchase Flow

Authenticated users with an eligible plan:

1. Navigate to /domains (My Domains)
2. Search for a domain name
3. Click Buy → redirected to /domains/checkout
4. Select registration duration (1, 2, 3, or 5 years)
5. Confirm the purchase
6. DNS records (A and CNAME) are automatically set
7. Domain appears in "My Purchased Domains" list

After purchase, users can:

• Manage DNS records — Add, edit, or remove DNS records via the DNS dialog
• Create a project — Quick link to create a project with the purchased domain
• View status — See renewal status, expiry date, and active/inactive state

Registrar Configuration

kuploy-cloud supports two domain registrar backends. Configure one or both in Admin → Domains.

Supported Registrars

Registrar	API	Use Case
Namecheap	XML API	Most common, requires IP whitelisting
Enom	Reseller XML API	Reseller accounts

Setting Up Namecheap

1. Go to Admin → Domains
2. Scroll to Namecheap Integration
3. Fill in:
   • API User — Your Namecheap username
   • API Key — Generate at Namecheap API Access
   • Username — Usually same as API User
   • Client IP — Your server's public IPv4 address
4. Toggle Sandbox Mode for testing (uses api.sandbox.namecheap.com)
5. Click Save Namecheap Configuration
6. Click Test Connection to verify

tip

You must whitelist your server's IP address in your Namecheap account settings for API access to work. The Client IP is also used as the DNS A record target when domains are purchased.

Setting Up Enom

1. Go to Admin → Domains
2. Scroll to Enom Integration
3. Fill in:
   • Reseller UID — Your Enom reseller account UID
   • Password — Your Enom reseller password
4. Toggle Sandbox Mode for testing (uses resellertest.enom.com)
5. Click Save Enom Configuration
6. Click Test Connection to verify

Choosing the Active Registrar

When both registrars are configured, an Active Registrar card appears. Click the provider button to set which registrar handles new domain searches and purchases.

• Existing purchased domains retain their original provider
• The registrar_provider column tracks which registrar was used for each domain
• Switching the active registrar only affects new operations

Security

All registrar credentials are encrypted at rest using AES-256-GCM with your instance's APP_SECRET. Credentials are never logged or exposed in API responses — only masked values are shown in the admin UI.

Managing DNS Records

For each purchased domain, DNS records can be managed directly from the dashboard:

1. Go to Admin → Purchase Domains (admin) or My Domains (user)
2. Find the domain in the purchased domains list
3. Click DNS to open the DNS management dialog
4. Add, edit, or remove records (A, AAAA, CNAME, MX, TXT)
5. Click Save Records to apply changes

caution

Saving DNS records replaces all existing records for the domain at the registrar. Make sure to include all records you want to keep when editing.

Auto-Configured DNS

When a domain is purchased, two records are automatically created:

Record	Type	Value
@	A	Your server's public IP
www	CNAME	The purchased domain

If automatic DNS configuration fails (e.g., registrar API timeout), it's logged as a non-fatal warning. You can configure DNS records manually via the dialog.

API Integration

For programmatic domain management, see the Domain API Reference. The API supports:

Subdomain operations:

• Check availability
• Reserve subdomains
• Provision DNS records
• Release subdomains
• List subdomains

Custom domain operations:

• Register custom domains
• Remove custom domains
• List custom domains

Purchased domain operations:

• Search domain availability (public, no auth required)
• Check registrar configuration status (public)
• Get plans with domain purchase feature (public)
• Purchase domains (plan-gated)
• List purchased domains
• Get/update DNS records
• Get domain info (status, expiry)

Troubleshooting

Domain Search Returns No Results

• Verify a registrar is configured in Admin → Domains
• Check the registrar connection with Test Connection
• Ensure the domain name is valid (at least 3 characters)

"Domain purchasing requires an eligible plan"

Neither the platform license nor the user's subscription plan has domainPurchase enabled. Check both:

1. License check — Run SELECT features FROM cloud_license_cache WHERE id = 'singleton' and verify domainPurchase is true
2. Plan check — The user may need to upgrade to Pro or Business, or you need to add domainPurchase: true to the plan's features in your kuploy.app plan catalog

"Upgrade Required" after server restart

The /domains page shows an upgrade prompt even for licensed instances. This can happen if the license memory cache was lost during a restart. The system calls ensureLicenseLoaded() to restore state from the database automatically — if the issue persists, verify that cloud_license_cache has data:

SELECT "licenseKey" IS NOT NULL as has_key, features
FROM cloud_license_cache WHERE id = 'singleton';

If the row is empty, trigger a license sync from Admin → Overview or wait for the next automatic sync cycle.

DNS Setup Fails After Purchase

This is non-fatal — the domain was purchased successfully but DNS auto-configuration failed. Use the DNS dialog to set records manually.

"Server IP not configured"

The Namecheap Client IP field is empty. Go to Admin → Domains → Namecheap Integration and set your server's public IP.

Enom API Errors

• Verify UID and password are correct
• Check if sandbox mode is toggled correctly
• Ensure your Enom reseller account is active and has sufficient balance