Skip to main content
Version: 1.89.x (Q2 26)

Working with Custom Domains

Codesphere allows you to connect your own domains (e.g., example.com) to your Workloads in addition to the generated <workspace-id>.<data-center>.<your-codesphere-instance-domain> URLs. This process involves adding the domain to your team, verifying ownership, and then routing traffic to your specific Workspace.

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 (Typically required for root/apex 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. Note: Some DNS providers (e.g., Cloudflare) also support CNAME records for root domains.
  1. Log in to your DNS provider (e.g., Cloudflare or Azure DNS) for the specified domain 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 Workspace 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, or specify a path prefix (e.g., /api/) to route only matching requests.
    • In the Workspaces dropdown, select the Workspace you want to connect. You can select multiple Workspaces to create a traffic split (e.g., for A/B testing or gradual rollouts).
    • Click + Add new path if you want to route specific paths (like /api) to different Workspaces.
  4. Click Save changes.
Connecting Multiple Workspaces to the Same Domain

You can connect multiple Workspaces to the same domain. In this case, traffic is split 1/N between all Workspaces.

TLS/SSL Certificates​

Codesphere automatically manages TLS 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.)
Private Cloud Installations

In Private Cloud installations, automatic provisioning of TLS certificates depends on the specific configuration.

Self-Managed Certificates

If you want to manage the certificates 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.