Skip to main content
Product9 min read

1004 - Your own domain

Every environment has an address from the moment it exists, and every one of them asks for a sign-in. A domain you add in the portal puts your own name on an environment, private until the owner makes it public. The main address, the per-environment addresses, adding a domain, making it public, and the names a site cannot take.

What you will take away from this lesson

prod serves release 2 at addresses that ask for a sign-in. This lesson puts ACME’s own name on it, makes that one name public, and gives the review copy a private name of its own.

An address is the part of a website other people depend on. Plexara treats it that way: every environment has one from the moment it exists, a domain belongs to an environment and stays private until the owner makes it public, and the working copy can never be given one.

Learning Objectives

  1. 01Name the three kinds of address a site answers at and what each serves.
  2. 02Say what the main address serves on a new site, who can move it, and what it shows when it serves nothing.
  3. 03Add a domain to an environment and say what Deasil does next.
  4. 04Make a domain public through approval, and say what stays private.
  5. 05Explain what a private domain does for a visitor.
  6. 06List the names a site, an environment and a domain cannot take, and why.

Where this lesson sits

Lesson 1003 shared stage and set out what it takes for an address to answer anyone. prod serves release 2, and every address it has so far asks for a sign-in.

1000 Series: Sites

Open index

The 1000 series builds on the forms and endpoints of the 700 series and the sharing model of the 800 series: a site is where the pages people open live, with the same people, personas and approvals deciding who reaches them.

Three kinds of address

A site answers at three kinds of address. Two of them are assigned by the platform and exist as soon as the site and its environments do. The third is yours.

The three kinds of address

AddressExampleWhat answers
The main addressacme-stores.pages.example.comThe one environment the owner gives it to: prod on a new site. Given to none, it answers “Nothing is published here”. Always asks for a sign-in.
An environment’s own addressacme-stores--stage.pages.example.comThat environment, always, whichever environment holds the main address. Always asks for a sign-in.
A domain you addstores.example.comThe environment it was added to. Private until the owner or an administrator sets it public.

The first two exist without anyone asking. Create an environment called client-review and acme-stores--client-review answers the moment it serves a release. A reviewer gets a link that will keep meaning the same environment for as long as the environment exists.

The main address

The main address is the site’s name on your deployment’s pages address. On a new site it serves prod, which is why the agent gave Grace dev’s own address in lesson 1001. Like every address on the pages address, it asks for a sign-in.

Where each environment answers

What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.

→ manage_site
  { "command": "get", "site": "acme-stores" }

← { "site": { "name": "acme-stores", "main_environment": "prod", ... },
    "pages_addresses": {
      "dev":   "https://acme-stores--dev.pages.example.com/",
      "stage": "https://acme-stores--stage.pages.example.com/",
      "prod":  "https://acme-stores--prod.pages.example.com/" },
    "addresses": {
      "dev":   "https://acme-stores--dev.pages.example.com/",
      "stage": "https://acme-stores--stage.pages.example.com/",
      "prod":  "https://acme-stores.pages.example.com/" } }

prod has held the main address since the site was created, so it already points at the version people should reach. Main address, above the environment cards, gives it to another environment. The move takes effect at once and needs nothing from Deasil, because the address already exists; only what it serves changes. Every environment keeps its own address, so a bookmark to acme-stores--dev keeps meaning the working copy.

Moving the main address is the owner’s or an administrator’s, for the same reason making a domain public is: it changes what people reach at an address they already use. Setting it to none is how a site is taken off its main address without deleting anything.

Adding your own domain

ACME wants the store finder at stores.example.com, open to anyone. That takes four steps, and your team does the first and the last.

Putting your own domain on an environment

  1. 1

    Add the domain to an environment

    On the site’s page, Add domain, with the name and the environment it serves. Anyone who manages the site can do it, and the domain is added private. Ask the agent and it makes the same request.

  2. 2

    Deasil routes it

    Deasil sees every address a site needs, routes your domain to your deployment and serves it over HTTPS. There is nothing for your team to install or renew.

  3. 3

    Open it signed in

    The domain asks for your organization’s sign-in, so the people who manage the site read prod at its real name before anyone else can reach it.

  4. 4

    Make it public

    The owner or an administrator makes the domain public. From then on it answers anyone, from whatever release prod points at: promote and the domain follows, roll back and it goes back with it.

What the agent calls

Asked to put stores.example.com on prod, the agent makes one call. The domain is recorded against the environment, private, and the site’s Domains tab lists it beside the addresses the platform assigned.

Adding stores.example.com to prod

What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.

→ manage_site
  { "command": "add_domain", "site": "acme-stores",
    "hostname": "stores.example.com", "environment": "prod" }

← { "hostname": "stores.example.com", "site": "acme-stores",
    "environment": "prod", "public": false, "status": "done",
    "created_by": "[email protected]" }

The domain is added private. Naming an environment that does not exist yet creates it in the same step, placed after the environment you name, so a new campaign site can get its environment and its domain in one request. A site can carry several domains, and an environment can answer on more than one, such as stores.example.com and www.stores.example.com, each private or public on its own.

A site's Domains tab: a table of the site's three pages addresses, each marked Private, then a Domains table with an Add domain button listing three domains: go.example.com on stage and www.example.com on prod marked Private with Make public, and example.com on prod marked Public with Make private, each with Remove.
The Domains tab lists every address a site answers at: the pages addresses, which always ask for a sign-in, and each domain with the environment it serves and its own access.

Making the domain public

Grace signed in at stores.example.com, read the store finder at its real name, and asked for it to be opened to the public. She owns the site, and prod requires approval.

The owner makes stores.example.com public, through approval

What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.

→ manage_site
  { "command": "set_domain", "site": "acme-stores",
    "hostname": "stores.example.com", "public": true,
    "reason": "Store finder and supplier page are ready for the public" }

← { "hostname": "stores.example.com", "environment": "prod",
    "public": false, "status": "awaiting_approval",
    "approval": { "purpose": "site_public", "site_name": "acme-stores",
                  "target": "stores.example.com", "status": "pending",
                  "requester_email": "[email protected]" } }

   ... an administrator approves the request in Approvals ...

→ manage_site
  { "command": "set_domain", "site": "acme-stores",
    "hostname": "stores.example.com", "public": true }

← { "hostname": "stores.example.com", "environment": "prod",
    "public": true, "status": "done" }

The owner asked, prod requires approval, so the request waited and the domain stayed private. After approval the same request made it public. In the portal this is Make public on the Domains tab. An administrator’s own request goes through at once. Someone who manages the site without owning it is refused: opening a site to the world is the owner’s decision. prod’s pages addresses still ask for a sign-in.

Each domain has its own access

A domain is private or public on its own, and a private one opens for the people its environment is shared with. That is what makes it safe to put a memorable name on something private.

Each domain is private or public on its own

A public domain

Opens for anyone at that one name, served from the release the environment points at. The environment’s pages addresses and its other domains keep their own access.

A private domain

Asks for your organization’s sign-in on that domain and sends the visitor back to the page they asked for. It opens for the people the environment is shared with, so an intranet lives at a name people can remember.

Making a domain private again

Anyone who manages the site can do it, and it takes effect on the next request. Making it public again asks again, through approval where the environment requires it.

Removing a domain

Anyone who manages the site removes a domain from an ordinary environment. On an environment that requires approval, only an administrator does, because moving the name to another environment would publish to it unapproved.

A domain on a private environment

Jordan wanted reviewers to stop pasting a long stage address into chat. A domain on stage gives the review copy a name, and the name stays private, so it opens for exactly the people stage is shared with. The same week, someone asked the agent to save time by pointing the public domain at the working copy.

A domain on a private environment, and a domain refused

What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.

→ manage_site
  { "command": "add_domain", "site": "acme-stores",
    "hostname": "preview.stores.example.com", "environment": "stage" }

← { "hostname": "preview.stores.example.com", "site": "acme-stores",
    "environment": "stage", "public": false, "status": "done",
    "created_by": "[email protected]" }

→ manage_site
  { "command": "add_domain", "site": "acme-stores",
    "hostname": "stores.example.com", "environment": "dev" }

← dev is the working copy and cannot have a domain: add the domain to the
  environment people use, and promote dev's release to it

The domain was added private, so preview.stores.example.com opens for exactly the people stage is shared with: store operations and the supplier open a name they can read aloud, sign in once on that name, and see the release waiting for their review. The second request is the one the platform will never grant. The refusal says why and what to do, and the agent adds the domain to prod.

Names a site cannot take

Addresses are where one thing can be mistaken for another, so the platform refuses the names that would allow it.

Names a site cannot take

A domain on dev

refused

dev is the working copy and cannot have a domain. Add the domain to the environment people use and promote dev’s release to it.

A name your deployment already answers on

refused

The portal’s own address, the sign-in address, and anything under the pages address the platform assigns. A site can never stand in front of the portal.

Two hyphens in a name

refused

No site or environment name contains --, so <site>--<environment> is always that site’s environment and never another site.

A name too long for an address

refused

A site and environment name together make one label of an address, at most 63 characters. A site name is at most 57, so its dev and prod addresses always fit.

A two-character site name

refused

Every <site>--<environment> address of a two-character name has the form reserved for encoded international names, and no certificate is issued for it.

A site named after an application

refused

A site and an application answer under the same pages address, so they cannot share a name.

Each refusal comes with its reason in a sentence, so the agent corrects the name and carries on. None of these needs remembering. They are listed here because each one closes a way for one address to be mistaken for another.

The one environment with no domain

What comes next

ACME’s store finder is public on ACME’s own domain, and it is still one hand-written page. Lesson 1005 rebuilds it from records, so that every store has a page and a new store is a new file.

Key terms

Four terms cover where a site answers.

Key Terms

Main address
The site’s own address. The owner or an administrator gives it to one environment, or to none.
Environment address
<site>--<environment> on your deployment’s pages address. Exists for every environment, always serves that environment, and always asks for a sign-in.
Domain
Your own name, added to one environment. It serves that environment’s release, private until the owner or an administrator makes it public.
Pages address
The address Deasil sets aside on your deployment for sites and application pages. Every site and environment gets a name under it.