Skip to main content
Version: Next

Working with Custom Domains

Codesphere allows you to connect your own domains (e.g., example.com) to your Workloads, replacing the generated *.[your codesphere instance URL] URLs. This process involves adding the domain to your team, verifying ownership, and then routing traffic to your specific Landscape.

Adding a Domain to Your Team​

domains overview

  1. Navigate to the Domains tab in your team dashboard.
  2. Click the + Add Domain button in the top right corner.
  3. Enter your domain name (e.g., your-domain.com) in the popup window and click Add.

Verifying Ownership (DNS Configuration)​

Once added, you need to prove you own the domain by adding DNS records.

domains verification records

  1. Click the Settings (gear icon) next to your newly added domain to open the configuration panel.
  2. Go to the Verification records tab.
  3. You will see two options for verification. Choose the one that fits your use case:
Verification Options
  • Option 1 (Recommended for subdomains): Add a CNAME record pointing to the value shown (e.g., ...workspaces.codesphere.com).
  • Option 2 (Required for root domains): Add an A record pointing to the provided IP address (e.g., 145.40.95.110) and a TXT record with the provided verification string.
  1. Log in to your domain registrar (e.g., GoDaddy, Namecheap, Cloudflare) and add these records.
  2. Wait a few minutes for propagation, then click Check Status in Codesphere.

Routing Traffic to Your Services​

After verification, you need to tell Codesphere which Landscape should receive traffic for this domain.

domains routing settings

  1. Switch to the Routing tab in the domain settings.
  2. Domain Access: Choose whether the domain is Public (accessible to everyone) or Private (restricted to team members only).
  3. Path-based routing:
    • In the URL field, leave the default / to route all traffic.
    • In the Workspaces dropdown, select the Landscape you want to connect.
    • Click + Add new path if you want to route specific paths (like /api) to different Landscapes.
  4. Click Save changes.

TLS/SSL Certificates​

Codesphere automatically manages SSL certificates for verified domains.

  1. Go to the TLS Certificate tab.
  2. Ensure Automated is selected. Codesphere will generate and renew certificates automatically once the domain is verified.
  3. (If the status is "Domain unverified," complete Step 2 first.)
Self-Managed Certificates

If you want to manage the certification yourself, click the Self-Managed button. In this case, you will need to ensure your certificates stay up to date and replace expired certs on your own to prevent application downtime.

Removing a Domain​

If you need to remove a domain:

  1. Click the Trash bin icon next to the domain in the list.
  2. Confirm the action by clicking Remove Domain in the warning popup.
Workspace Availability

If you link a domain to a workspace that is currently stopped, Codesphere will try to wake it up when a user visits the domain, but cold starts may cause a slight delay. Ensure your production workspaces are set to "Always On" for the best user experience.