Skip to content
Cloud
Docs

Domains

Domains establishes ownership of a DNS namespace and lets Projects claim exact hostnames beneath it. It connects an Account's domain ownership to the Project that will use a particular address.

Why use Domains?

A custom hostname needs a verified owner and a clear assignment before an application can serve traffic through it. Domains records those claims, while Run manages the connection from a claimed hostname to a running service.

What you can do

  • Register a Domain record and obtain its DNS TXT verification challenge.
  • Verify ownership, inspect status, and reverify or disable a Domain.
  • Claim an exact Hostname for a Project beneath a verified Domain.
  • Manage Hostname claims before using them in Run Routes.

Core concepts

A Domain belongs to an Account and represents a verified DNS namespace. A Hostname is one exact address claimed by a Project. A Route, owned by Run, maps that Hostname to a service Workload.

Account verification proves control of the DNS namespace. A project hostname claim assigns an address to a Project. DNS points that address at Socra ingress. A Run Route selects the workload that serves it. You can configure the hostname claim and DNS before choosing a workload.

Connect a hostname and configure DNS

Keep your domain registered and your nameservers at your existing provider. The examples below use example.com as the verified account Domain and app.example.com as the project hostname.

1. Verify the account Domain

If your account already has a verified Domain covering the hostname, continue to the next step. Otherwise, an account owner creates the Domain, publishes the returned TXT challenge at the DNS provider, and verifies it:

Bash
socra domain create example.com

Add the returned verification_name and verification_value as a TXT record, then verify:

Bash
socra domain verify dom_…

The TXT record proves ownership; it does not direct web traffic to Socra.

2. Assign the hostname to a project

Enable Domains on the Project and claim the exact hostname:

Bash
socra service enable domain.socra.cloud --project proj_…
socra domain hostname create app.example.com --project proj_…

The response includes the hostname ID, claim status, and routing_target. Repeating the claim for the same Project reuses it; a hostname claimed by another Project is rejected. Project members can claim subdomains; assigning the verified Domain apex requires an account owner.

3. Add the record at your DNS provider

Use the returned routing_target, currently ingress.socra.cloud, as the DNS target:

HostnameRecord typeName in the example.com zoneValue
app.example.comCNAMEappingress.socra.cloud
example.com (zone apex)Provider ALIAS/ANAME or CNAME flattening@ or blank, depending on provideringress.socra.cloud

For a subdomain in AWS Route53, open the hosted zone, choose Create record, enter app as the record name, select CNAME, enter ingress.socra.cloud as the value, and save. A TTL of 300 seconds is suitable. Some providers require the full hostname instead of app.

A CNAME cannot coexist with other records at the same name. Replace conflicting records for that hostname while preserving unrelated records, including email and ownership verification records.

A zone apex cannot use a standard CNAME. Provider ALIAS support varies: Route53 limits alias targets and cannot alias an apex to an arbitrary external hostname such as ingress.socra.cloud. If your provider cannot flatten that target at the apex, use a subdomain. Do not copy an IP obtained by resolving the ingress hostname into an A record; it can change.

4. Verify DNS resolution

Bash
dig +short CNAME app.example.com
dig +short app.example.com

The CNAME query should return the routing target. The second query should resolve through it to ingress addresses. Apex ALIAS/ANAME records typically return addresses directly. DNS caches may retain previous answers until they expire.

An active Hostname means the project claim is active. DNS resolution means requests can reach Socra ingress. Neither confirms that an application or HTTPS certificate is ready.

Route to a workload when ready

Configure the workload destination separately using Run Routes. Adding the DNS record does not create a Run Route or select a workload. Run manages application ingress and TLS when the hostname is routed to a service Workload.

Use Domains

Read the CLI reference for commands or the API reference for resources, request fields, and responses.