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
- 01Ask the agent for a site and read the two calls it makes.
- 02Name the four things a site is made of: environments, releases, addresses and access.
- 03Say what dev is and why every change lands there.
- 04List the files a release treats specially.
- 05Open the working copy in a browser and say who else can.
- 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
- 1001Your first siteWhat a site is, the working copy called dev, the first release, the address it answers at, and who may create one.
- 1002Dev, promote, roll backEnvironments people use, promotion of the exact release that was reviewed, approval, rollback, and the history of every move.
- 1003Private environments, public domainsAccess per environment: people, personas, everyone internal, the sign-in every pages address asks for, and the rules for making a domain public.
- 1004Your own domainThe main address, an address for every environment, adding a domain in the portal, making it public, and the names a site cannot take.
- 1005Layouts and recordsLayouts, includes and records: the agent maintains data and the platform generates pages, paged lists and category indexes.
- 1006Editing a live siteReading and patching site files in place, dry runs and diffs, overlays for new files, and one promotion for several edits.
- 1007Capstone: moving an existing site onto PlexaraA crawl that keeps every address, redirects as rules, forms replaced by Plexara forms, and the whole series end to end.
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.
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
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
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
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
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.

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.
