# 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:

| Hostname                  | Record type                              | Name in the `example.com` zone      | Value                 |
| ------------------------- | ---------------------------------------- | ----------------------------------- | --------------------- |
| `app.example.com`         | CNAME                                    | `app`                               | `ingress.socra.cloud` |
| `example.com` (zone apex) | Provider ALIAS/ANAME or CNAME flattening | `@` or blank, depending on provider | `ingress.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](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/resource-record-sets-choosing-alias-non-alias.html) 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](/docs/run/reference/cli). 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](/docs/domain/reference/cli) for commands or the [API reference](/docs/domain/reference/api) for resources, request fields, and responses.

## Related services

- [Run](/docs/run)

---

Company: Socra — Multiply Your Judgment
Canonical URL: https://cloud.socra.com/docs/domain