Skip to main content
Product10 min read

1001 - Your first site

Ask the agent for a website and it publishes one: a site with a private working copy called dev, an address of its own, and a first release you open in a browser after signing in. What a site is, what a release holds, who may create one, and why nothing the agent publishes is public until a person decides it is.

What you will take away from this lesson

ACME’s store finder is a spreadsheet export somebody pastes into the corporate website twice a year, and the page that tells suppliers how to work with ACME is a PDF. Both are websites nobody has had the time to build. On Plexara the agent builds them, and Plexara serves them.

This lesson publishes the first version of that site and opens it in a browser. It takes one request. What makes it worth a lesson is what the platform puts around the request: an address, a release with a number, and a private working copy, with nothing reaching anyone else until a person decides it should.

Learning Objectives

  1. 01Ask the agent for a site and read the two calls it makes.
  2. 02Name the four things a site is made of: environments, releases, addresses and access.
  3. 03Say what dev is and why every change lands there.
  4. 04List the files a release treats specially.
  5. 05Open the working copy in a browser and say who else can.
  6. 06Say who may create a site and who owns it.

Where this lesson sits

The 300 series saved reports and dashboards to the portal. The 700 series gave automations an address other systems call and gave forms a hosted page. A site is the next step out: whole web pages, on an address of their own, that people open in a browser without ever seeing the portal.

This series builds one site for ACME across seven lessons and moves a second one over from the system it replaces. Every lesson uses the same site, so the release numbers and addresses carry forward.

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.

What a site is

A site is a set of web pages Plexara serves on an address of its own. It is not an asset in your library and it is not part of the portal: a request to a site’s address reaches the site and nothing else. That separation is what makes it safe to serve a page, with its own scripts, to people who have no business in the portal.

A site is made of five things. The rest of the series is these five, one at a time.

What a site is made of

Site

acme-stores

A named set of web pages the platform serves on an address of its own, outside the portal. It has one owner, the people who manage it, and the people it is shared with.

Environment

dev, stage, prod

A place the site is served from, pointing at exactly one release. Every site starts with two: dev, the working copy, and prod, the environment people use. A review environment such as stage goes between them when it is needed, and a release moves through them in order.

Release

release 1, 2, 3 ...

An immutable, numbered set of files. Publishing writes a new release; nothing ever edits an old one. Promote and roll back choose which release an environment serves.

Address

acme-stores.pages.example.com

Where a browser reaches the site. The site has a main address, every environment has an address of its own on your deployment’s pages address, and a domain you add puts your own name on an environment.

Access

private, or a public domain

Who may open an address. Every address on the pages address asks for your organization’s sign-in and opens for the people the environment is shared with. A domain you add can be made public, and that one domain then opens for anyone.

Five nouns carry the whole series. Each lesson after this one takes one of them further: environments in 1002, access in 1003, addresses in 1004, and releases in 1005 and 1006.

The request

ACME’s web lead, Grace Okafor, asked for the site in one paragraph. She named the pages, where the store data comes from, and the brand guide, and she said where to put it.

What you type

Build a small website for ACME called acme-stores. A home page, a store finder page listing our stores by state with city, address and opening hours from the warehouse, and a page for suppliers explaining how to apply, linking to the supplier application form. Use the ACME brand guide. Save it as a site on Plexara and tell me where to look at it.
Say “a site on Plexara”. Left to itself an assistant will write the files on your own machine, where nobody else can open them and nothing is versioned.

Creating the site

The agent’s first call creates the site. A site’s name is a lowercase slug, and it becomes part of every address the site answers at, so it is worth choosing the way you would choose a folder name you will live with.

Creating the site

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": "create",
    "name": "acme-stores",
    "description": "ACME store finder and supplier information" }

← { "name": "acme-stores",
    "owner_email": "[email protected]",
    "main_environment": "prod",
    "environments": [
      { "name": "dev",  "release": 0, "internal_view": false, "requires_approval": false },
      { "name": "prod", "release": 0, "internal_view": false, "requires_approval": false }
    ] }

A new site has two environments, dev and prod, neither serving a release yet. prod holds the site’s main address, so the address people will use exists from the start, and dev answers at acme-stores--dev. Every one of those addresses asks for a sign-in. The person whose session made the call owns the site. Nothing else exists until it is asked for: no review environment, no domain, nothing public.

The first release

The second call publishes. The agent had already queried the warehouse for the stores, grouped them by state, and written five files: a home page, the store finder, the supplier page, one stylesheet, and a not-found page.

Publishing does two things in one step. It writes release 1, a numbered set of exactly these files that will never change, and it points dev at that release. The site is being served from this moment: the address in the answer works.

Publishing release 1 into dev

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": "publish",
    "site": "acme-stores",
    "note": "First version: home, store finder, supplier page",
    "files": [
      { "path": "index.html",            "content": "<!doctype html> ..." },
      { "path": "stores/index.html",     "content": "<!doctype html> ..." },
      { "path": "suppliers/index.html",  "content": "<!doctype html> ..." },
      { "path": "assets/site.css",       "content": ":root { --acme-blue: #0359A5; } ..." },
      { "path": "404.html",              "content": "<!doctype html> ..." }
    ] }

← { "release": { "number": 1, "source": "files (5)", "file_count": 5,
                 "note": "First version: home, store finder, supplier page" },
    "environment": "dev",
    "address": "https://acme-stores--dev.pages.example.com/" }

A publish names no environment, because there is only one place it can land. The answer carries the release number and the address to open. The store list in stores/index.html came from a warehouse query the agent ran in the same session, so the page is built from governed data on the day it is published.

A publish takes its files three ways: inline as here, as a zip or gzipped tar archive saved to your library, or as a folder in your library. The last two are how a large site, or the output of an automation, becomes a release.

What a release holds

A release is served as it was published, with a short list of conventions that give a plain folder of files the behaviour people expect of a website.

What a release treats specially

index.html in a folder

stores/index.html

Answers at the folder’s address, /stores/.

Any other page

about.html

Answers at /about.html and also at /about, so addresses stay clean without a rule.

Not-found page

404.html

Served, with status 404, for any path nothing in the release answers.

Redirect map

_redirects

One rule per line: from, to, and an optional status that defaults to 301. /old/* with :splat carries the rest of a path across. The file becomes the release’s redirect map and is never served itself.

Fingerprinted files

site.3f2a9c1b.css

A file whose name carries a content hash is served so browsers keep it without asking again, because a changed file would have a different name.

Dotted paths

.env, .git

Refused, apart from .well-known. A source tree’s private files cannot become addresses by accident.

Everything else is served as published. Text files are compressed when they are published, so there is no build step to configure and no optimizer to run. Lesson 1005 adds the one thing that changes what is served: a layouts folder.

Opening the working copy

Grace opened the address the agent gave her. The site asked her to sign in, because the working copy is private, and then showed her the home page.

Opening the working copy

  1. 1

    Open the address the agent gave you

    https://acme-stores--dev.pages.example.com/ in any browser. That is dev’s own address. The main address belongs to prod, which serves nothing until a release is promoted to it.

  2. 2

    Sign in once

    dev is private, so the address sends you to your organization’s sign-in and straight back to the page you asked for. Someone already signed in to the portal arrives with no click.

  3. 3

    Read the site as a visitor would

    Every page, style and image is served from the release exactly as it will be served to anyone else later. There is no preview mode that differs from the real thing.

  4. 4

    Find it in the portal

    The Sites section lists the site with its owner, its main address, and each environment with the release it serves.

Until it is shared, dev opens for the site’s owner, the people who manage the site, and administrators. A colleague who is none of those is refused after signing in, and the refusal shows nothing of the site.

The Sites section of the portal: a New site button and a table of three sites with each one's owner, main address and environments, each environment showing the release it serves and its domains.
The Sites section lists every site you can open, with each environment, the release it serves, and its domains.

Nothing the agent publishes is public

At this point ACME has a website and nobody outside the web team can see it. That is the design, not a missing step.

Who may create, own and manage a site

Sites follow the same access model as the rest of Plexara. What a person may do is decided by their persona and by their standing on the particular site, and their agent has exactly that standing and no more.

Who may create, own and manage a site

Who creates a site

Anyone whose persona includes the Sites tool. An administrator grants it in Admin > Personas, the same way every other capability is granted, and the Sites section appears in the portal for those people.

Who owns it

The person who created it. The owner decides who manages the site, makes a domain public, and chooses which environment the main address serves. An owner or an administrator can hand the site to another owner.

Who manages it

Internal people the owner adds with Can manage. They and their agents publish and edit dev, promote, roll back, add domains and share. People outside your organization can be shared with and are never made managers.

What the agent may do

Exactly what the person it is working for may do. An agent working for someone who manages the site publishes to dev. An agent working for anyone else reads what that person can open and changes nothing.

People work from the portal’s Sites section and agents through one tool, and both go through the same checks, so the portal and the agent can never disagree about who may do what. Personas and the areas of the portal are covered in lesson 804.

What comes next

The site exists, has one release, and is open to the people who build it. Lesson 1002 adds a review environment between dev and prod and moves a release through both. Lesson 1003 decides who opens each one, and what it takes for an address to answer anyone.

Key terms

Five terms cover what a site is and how its first version comes to exist.

Key Terms

Site
Web pages the platform serves on an address of its own, with environments, releases, an owner and the people it is shared with.
dev
The working copy every site starts with, beside prod. The only environment that takes a publish or an edit, always private, and never given a domain.
Release
A numbered, immutable set of files with a note saying what it is for. An environment serves exactly one release at a time.
Main address
The site’s own address, <site> on your deployment’s pages address. It serves one environment the owner chooses: prod on a new site.
Publish
Writing a new release into dev from inline files, an archive, or a folder in your library.