# Domain

A generated name under elements.online for an app that has no domain yet, so
the first deploy answers on HTTPS with nothing to register. One command gets
it and the next deploy points it at the machines.

## Get a Name

Run it in the project, after the machine exists and before the first deploy:

```bash Get a generated name
elements domain
```

The name is generated by Elements, two words and a number, like
`tidy-lexer-4821.elements.online`, and written to `deploy.domain` in
`config.jsoc`. Names are not chosen: the words come from a fixed list, so
nothing under elements.online is anyone's choice but ours. An app that wants
a name of its own uses its own domain, below.

A domain already in `config.jsoc` is never replaced quietly. The command
stops and says what is there; `-force` replaces it and `-append` adds the
generated name to it, so both are served.

The name belongs to your account, not to a machine or a project. Each
account can hold five.

## Deploy

Nothing else changes. `elements deploy` reads `deploy.domain`, points the
name at the environment's machines before it provisions them, and the load
balancer gets its certificate the same way it does for a domain of your own.
The deploy ends with the url:

```text Deploy output
Ok
Live at https://tidy-lexer-4821.elements.online
```

With `-json` the url is in the result as `url`. A second deploy onto new
machines moves the name with it; the record changes within a minute.

## Your Own Domain

The elements.online name is a value of `deploy.domain` like any other. When
you have a domain, point an `A` record at the machine and put it in
`config.jsoc` in place of the generated name, or alongside it in a list.
Both are served and both get a certificate. See
[Load Balancer](load-balancer) for TLS and DNS.

```jsonc config.jsoc
deploy: {
  domain: ["example.com", "tidy-lexer-4821.elements.online"],
}
```

## Release a Name

```bash Give the name back
elements domain release
```

The record is deleted and the name leaves `config.jsoc`; a domain of your
own listed beside it stays. The name is held for your account for 90 days,
in which only you can claim it again; after that anyone can. Release a name
when the app is gone, not when it moves: a redeploy carries the name along.

If your license lapses, the names keep answering for 14 days. Pay inside
them and nothing changes. After them the records are removed and the 90 day
hold starts. Paying again inside it gets the names back: run
`elements domain` in each project, and the name in its `config.jsoc` is the
one that comes back.

## Agents

An agent setting up a machine asks for nothing about domains. Its one
confirmation says the app will answer at a generated address under
elements.online unless the user has a domain they want to use, and the user
says yes or gives a domain. On yes the agent runs `elements domain` after
provisioning and before the first deploy, then reports the url the deploy
prints.