Custom Domains for Your Applications

Eyevinn Open Source Cloud allows you to assign custom domain names to applications deployed via the "My Apps" feature. This guide explains the two types of domains available and how to configure each one.

Domain Types: Managed vs Custom

OSC supports two distinct domain types. Understanding the difference is important before you begin.

Managed Domains

Managed domains are subdomains under the OSC platform domain. They are covered by a wildcard TLS certificate managed by the platform — no DNS configuration is required from you.

Managed domain patterns:

Environment Pattern
Production <subdomain>.apps.osaas.io
Stage <subdomain>.apps.stage.osaas.io
Dev <subdomain>.apps.dev.osaas.io

You choose the subdomain prefix; the platform ensures it is unique and provides automatic HTTPS.

Custom Domains

Custom domains are domain names you own and control (e.g., myapp.example.com). They require:

  • A paid OSC plan
  • DNS configuration at your domain registrar (CNAME record pointing to the OSC load balancer)
  • An individual Let's Encrypt certificate, which the platform provisions automatically once DNS is configured

Custom domains are not available on the free plan. The option is disabled in the web console unless your account is on a paid plan.

Default Application URL

When you deploy an application via My Apps without configuring a domain, it receives a default URL in this format:

https://<10-char-hash>.apps.osaas.io

The 10-character hash is a stable identifier derived from your tenant ID and application name.

Prerequisites

  • A deployed application in OSC via the My Apps dashboard
  • For managed domains: any plan
  • For custom domains: a paid OSC plan, a domain name you own, and access to your DNS provider's settings

Setting Up a Managed Domain

Managed domains are the simplest option. No DNS changes are needed.

Via Web Console

  1. Navigate to My Apps
  2. Click the Domains tab
  3. Click Add Domain
  4. Select Managed as the domain type
  5. Enter your desired subdomain (e.g., my-app)
  6. The full domain is shown in the UI (e.g., my-app.apps.osaas.io)
  7. Select the instance to map to this domain
  8. Click Add Domain to confirm

The domain is active immediately once created.

Via MCP (AI Agent)

You can ask the OSC Architect to set up a managed domain:

"Create a managed domain my-app.apps.osaas.io for instance myapp of service eyevinn-web-runner"

Or use the MCP tool directly:

create-my-domain
  domain: "my-app.apps.osaas.io"
  instanceName: "myapp"
  serviceId: "eyevinn-web-runner"
  isManaged: true

Setting isManaged: true explicitly requests a platform-managed domain. When omitted, the platform infers the type from the domain pattern.

Setting Up a Custom Domain

Custom domains require DNS configuration in addition to the steps above.

Step 1: Add the Domain in OSC

Via Web Console

  1. Navigate to My Apps
  2. Click the Domains tab
  3. Click Add Domain
  4. Select Custom as the domain type (requires a paid plan)
  5. Enter your domain name (e.g., myapp.example.com)
  6. Select the instance to map to this domain
  7. Click Add Domain to confirm

After creation, the domain appears in the table with a Custom badge. Click the info icon next to it to see the DNS target you need to use.

Via MCP (AI Agent)

"Create a custom domain myapp.example.com for instance myapp of service eyevinn-web-runner"

Or use the MCP tool directly:

create-my-domain
  domain: "myapp.example.com"
  instanceName: "myapp"
  serviceId: "eyevinn-web-runner"

The tool returns the domain details including the dnsTarget value you need for the next step.

Step 2: Get the DNS Target

After creating a custom domain, OSC returns a dnsTarget value. This is the hostname or IP address of the OSC load balancer, dynamically provided by the platform.

In the web console, you can retrieve this at any time by clicking the info icon next to the domain in the Domains tab.

Via MCP:

list-my-domains

The output for each custom domain includes a DNS Target line with the value to use.

Step 3: Configure DNS at Your Registrar

In your domain registrar's DNS management panel:

  1. Create a new CNAME record
  2. Set the Name/Host to your subdomain (e.g., myapp for myapp.example.com)
  3. Set the Value/Target to the DNS target shown in the OSC web console or returned by the API
  4. Set TTL to 300 (5 minutes) is recommended initially

Example DNS record (using the target provided by OSC after domain creation):

Type Name Value TTL
CNAME myapp <dns-target-from-osc> 300

Do not use a hardcoded hostname — always copy the actual dnsTarget value from OSC, as it reflects the live load balancer address.

Step 4: Wait for DNS Propagation

DNS changes can take anywhere from a few minutes to 48 hours to propagate globally. Typically, it takes 5-15 minutes.

You can check propagation using:

# Check if your CNAME is resolving
dig myapp.example.com CNAME

# Or use nslookup
nslookup myapp.example.com

Step 5: SSL Certificate Provisioning

Once DNS is correctly configured, OSC automatically provisions an individual Let's Encrypt TLS certificate for your custom domain via cert-manager. Certificate provisioning typically takes 2-5 minutes after DNS propagation completes.

You can verify the certificate by visiting your custom domain in a browser:

https://myapp.example.com

The browser should show a valid SSL certificate without warnings.

Updating a Domain

To change the domain mapped to an existing instance:

Via Web Console

  1. Navigate to My Apps and click the Domains tab
  2. In the row for the domain you want to change, click Edit
  3. Enter the new domain and confirm

Via MCP

update-my-domain
  instanceName: "myapp"
  domain: "newdomain.example.com"
  serviceId: "eyevinn-web-runner"

If switching to a custom domain, a new DNS target will be returned — update your DNS accordingly.

Removing a Domain

To remove a domain mapping from your application:

Via Web Console

  1. Navigate to My Apps and click the Domains tab
  2. In the row for the domain you want to remove, click Delete
  3. Confirm the deletion in the dialog

After removing the domain in OSC, also delete the corresponding DNS record from your registrar (for custom domains).

Via MCP

delete-my-domain
  serviceId: "eyevinn-web-runner"
  instanceName: "myapp"

Listing Your Domains

Via Web Console

All your domain mappings are listed in My Apps under the Domains tab. The table shows the domain name, instance name, service ID, and domain type (Managed or Custom).

Via MCP

list-my-domains

Checking Domain Availability

Before creating a managed domain, you can verify whether a subdomain is already taken.

Via MCP

check-domain-availability
  domain: "my-app.apps.osaas.io"

The tool returns whether the domain is available. If it is already in use by another tenant, you will need to choose a different subdomain.

Using a Root Domain (Apex Domain)

Some DNS providers do not allow CNAME records on root domains (e.g., example.com without a subdomain). Options:

Option 1: Use ALIAS or ANAME Records (if supported)

Some DNS providers (Cloudflare, DNSimple, NS1) support ALIAS or ANAME records that function like CNAME records for root domains. Use the DNS target from OSC as the value.

Option 2: Use a Subdomain and Redirect

  1. Configure www.example.com as a custom domain in OSC
  2. Set up a redirect from example.com to www.example.com in your DNS provider's dashboard

Troubleshooting

Certificate error on custom domain

Possible causes: - DNS record not yet propagated - CNAME target is incorrect - Let's Encrypt certificate not yet provisioned

Steps to resolve: 1. Verify the DNS record using dig myapp.example.com CNAME 2. Confirm the CNAME value exactly matches the dnsTarget shown in the web console 3. Wait 5-10 minutes for certificate provisioning after DNS propagation completes

"Not Found" or 404 on the custom domain

Possible causes: - Domain not yet created in OSC - Application instance not in a running state - DNS not yet propagated

Steps to resolve: 1. Verify the domain mapping exists in the Domains tab 2. Check that the application instance is running in My Apps 3. Verify DNS propagation with dig or an online tool like https://dnschecker.org

DNS not propagating

Steps to resolve: 1. Reduce TTL to 300 seconds (5 minutes) if it is higher 2. Clear your local DNS cache: ```bash # macOS sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder

# Windows ipconfig /flushdns

# Linux sudo systemd-resolve --flush-caches ``` 3. Test with a public DNS server (e.g., Google's 8.8.8.8) to confirm propagation

Custom domain option is disabled in the web console

Custom domains require a paid OSC plan. If the Custom option is greyed out in the Add Domain dialog, your current plan does not include custom domains.

Best Practices

  • Use subdomains rather than root domains to avoid CNAME limitations.
  • Set a low TTL (300 seconds) initially so DNS changes take effect quickly.
  • Once DNS is stable, you can increase TTL (e.g., 3600 seconds) for better caching.
  • If you delete an application in OSC, also remove the DNS record at your registrar.
  • Let's Encrypt certificates renew automatically. If a renewal fails, verify the DNS record still points to the correct target.

Security Notes

  • All custom domains receive SSL/TLS certificates via Let's Encrypt automatically.
  • HTTP requests are automatically redirected to HTTPS.
  • The maximum request body size is 64MB.

Need Help?

If you encounter issues setting up a domain: