Highport orbital control

Your first site

This is the screen your site launches from. Everything on it is filling in a form and watching a page load; the hard part was the DNS record, and you have already done it.

One screen does all of it. You pick what fills the page, either your own files or a design somebody has published. You press Get it ready, then you press Publish, and the page starts answering at your domain as soon as Highport sees the record arrive. This page walks the whole thing in order, and names what Orbital Control is doing behind each step.

Before you start

You do not have to wait for the domain to clear before you start composing. The editor works from the moment the domain is registered, and every check it runs against your page runs the same whether DNS has propagated or not. That goes for the paths, the manifest and the redirects alike. What waits is Publish.

Where the flow starts

Create a site in the Hub's dashboard header opens the new-site screen, which asks for the address before anything else: "Choose the address first. A name under ours is ready the moment you pick it; a domain you already own takes two DNS records and a few minutes."

That screen registers the domain and hands you the two DNS records. Its first option, Use a name we provide, appears only where the deployment offers such a name, and one registered that way is verified on sight and has no DNS to add. If you keep your records in a space, that screen is also where you choose it, and Spaces covers what changes.

A name under Highport's own gets one thing more. A starter page is written into your account on the way to the editor, so the tile is already picked and something is already serving before you have typed anything. That step is best effort and silent. If the tile is unavailable the editor opens empty and nothing says so.

Once the domain is registered it has a row on your dashboard, and clicking anywhere on that row opens the site's own page at /sites/{domain}. That page has two tabs — Content and Settings — and Content is the one it opens on. Content is the screen everything below is about. You can come back to it as often as you like. The files you upload go to your account as you add them, but no site record is written until you press Publish.

Three ways to fill the page

Under the heading What this page shows, three radios: "Three ways to fill it. Pick one."

A tile is a page design published as its own record, which you fill in with your details instead of writing yourself. Pick one if you want a page today and do not want to write HTML. Using a tile on your site covers choosing one, filling it in, and what happens when its author publishes a newer version. The picker's cards say what each tile will ask you for, or Nothing to fill in. for one that asks nothing.

Pick Upload files for this page only if you already have a site, meaning a folder with an index.html in it, and you want it served exactly as it is. The rest of this page is about that choice.

The third choice publishes a tile under your own account first and then binds this site to it. It is a longer road and it earns you something reusable. Building a tile is where it goes.

Adding your own files

The section is headed Your files: "Served exactly as you upload them. Nothing to fill in — that is what a ready-made tile gives you instead."

There are three ways in, and all three end in the same table:

• Drop a folder or files onto the drop zone.
• Choose files, the ordinary file picker.
• Choose a folder, the same picker in directory mode.

The two buttons are not decoration. A drop target cannot be operated from a keyboard at all, so the buttons are the accessible route to the same table.

The path each file answers at

Each file becomes one entry in your site's manifest: the list, keyed by address, of which of your files answers where. The zone says how the keys are made: "Paths are taken relative to what you drop. Hidden files are skipped, and a root index.html becomes /."

What happens to each dropped file, in order:

1. .DS_Store, Thumbs.db, desktop.ini, .gitkeep and .gitignore are skipped at any depth, and the panel says how many.
2. The path is normalized. A leading / is added, repeated slashes collapse, . segments are dropped, a trailing / is stripped.
3. A file at /index.html becomes the key /, so it answers at the root of your domain.
4. Anything left that cannot be a key is refused by name, with the reason.

Dropping a folder keeps the folder's own name on the front of every path. Drop site/ and its index.html becomes /site/index.html instead of /, so nothing answers at the root of your domain. Choose a folder does the same. Open the folder and take the files themselves, either by dropping those or by using Choose files, and a root index.html becomes / as the zone says.

The Path column in the table is the address each file will answer at, and it shows "from …" in muted text whenever normalization renamed something. Read that column before you publish. It is the fastest way to find the one file in two hundred that is not where you think it is.

The refusals you can actually meet:

These render together under Some files could not be added, with a Dismiss button. Nothing is added silently and nothing is dropped silently. Every file you hand over ends up in the table, in the skipped count, or in that list.

The reserved prefixes are /_bard/, /.well-known/rasl/, /.well-known/acme-challenge/, and the exact path /.well-known/atproto-did. Highport answers those itself. The origin's rules has the full set. A file at /.well-known/site.standard.publication is added like any other, and is refused when you publish only if the site also names a standard.site publication for Highport to answer there.

Where your files actually go

Every file you add is uploaded to your own account's server, three at a time, so a large folder saturates your connection without stalling the page. Highport passes the bytes through and never writes them to disk. They are yours, they stay yours, and a site record is a list of references to them.

Two consequences worth knowing before you spend an hour in this screen.

There is no draft. The working set lives in the page and nowhere else. Not on a Highport server, not in your browser's storage. Close the tab before you publish and you compose it again, and nothing warns you on the way out. The uploaded files survive on your own account. The list of what goes where does not.

Your account's server sets its own ceiling on a single file, and Highport does not know the number. If it refuses one, its own message is shown above the table, verbatim: "Your PDS refused a file: …", PDS being the server that holds your account. The message names the size, the part that makes it actionable, so it is relayed instead of paraphrased. Highport has a ceiling of its own on one upload, and Limits and quotas carries it.

If a single file fails, its row gets a red failed pill and the error beside it. Press Remove on that row and add the file again. The ones that already landed stay where they are.

Content types and overrides

The type each file is served as is taken from its extension, not from what your browser called it. That matters more than it sounds. The type is stored with the file and the origin serves it as that for as long as the file exists. A browser that calls a .wasm file application/octet-stream makes it unrunnable, and nothing about the page looks broken until somebody loads it.

Thirty-four extensions are recognized. An extension that is not, and a file with no extension at all, is uploaded as application/octet-stream.

A checkbox, Show content type and encoding overrides, reveals two more columns. Serve as sets the type explicitly. Encoding declares that a file is already compressed, as br, gzip or zstd. A row served as application/wasm or application/manifest+json, which is to say a .wasm or a .webmanifest file, carries a "· consider an override" note until you set one, because those are the two a browser is most likely to get wrong. Everything else can be left alone.

The running totals

One line sits above the table. While anything is uploading it reads Uploading to your PDS…. Otherwise it reads how many entries you have and what they add up to, counting files that have not landed yet. With nothing added at all, the table is replaced by Nothing added yet.

That total is not shown against a ceiling, because no ceiling is published to the page. The ceilings are enforced when you check the page, and a manifest over one of them comes back as an InvalidManifest problem in the list. Limits and quotas carries the numbers: how many entries a site may hold, how large it may get, how big a single upload may be, and how many pages may be waiting to publish at once.

The page that answers at the root

A visitor who types your domain with nothing after it gets the entry keyed /. Check for it before you publish, not after. The Path column shows one row reading /.

Nothing refuses a site that has no such entry. Not the editor, not the check. A site of your own files without one still serves: a request for / falls through to /index.html if you published that key, and to your not-found page, or Highport's own, if you did not. A tile must bring its own. That check is on the tile and not on your site, and the tile builder tells an author whose tile has none.

The Extra settings block below your files holds redirects, the not-found page, and the two files Highport serves on your behalf. None of it is needed for a first site. Redirects, missing pages, and being your own handle covers all three, and the handle warning in it is worth reading before you turn anything off.

Checking as you type

Highport checks your page continuously, 500 ms after each change, and shows what it finds in two lists above the buttons:

• Fix these before publishing, for problems with the manifest, the paths, the redirects, or the tile you bound.
• Fix these in your details above, for problems with the values you filled into a tile.

Each problem shows its name in a code style beside the sentence, so RedirectTargetNotFound sits next to an explanation naming the exact redirect and where it points. The check re-runs as you fix them. There is nothing to press.

If the check itself cannot run, because the network went or the session lapsed, you get a callout headed "The check could not run" instead. That is different from a problem with your page, and it is why the two are worded apart.

Checking writes nothing. Your files are already in your account, because uploading put them there. The record that says where they go arrives only when you publish. Validate before you write is the mechanism, if you want it.

Get ready, then publish

Two buttons, under the heading Get ready, then publish: "Highport checks your page as you type, and nothing is saved until you say so. Get it ready fetches your files in advance; Publish puts the page live."

Get it ready is the one that does work. It asks Highport to fetch every file your page names and build the page in advance, holding it ready for the record you are about to write. Publish then writes the record to your account.

A verdict sits beside the buttons and says exactly why Publish is or is not available:

Before any of that, four conditions block both buttons outright, and each says which one it is: "Choose a tile first.", "Add at least one file — a root index.html becomes /.", "Waiting for the uploads to finish.", and "None of these files finished uploading. Check the errors beside them, then remove and add them again."

Everything else on this screen works while a domain is still clearing. Compose the whole page, fix every problem, and leave it as it is. The moment the registration verifies, press Get it ready and the verdict changes.

Editing after you press Get it ready

Change anything after a preparation stands and the preparation is dropped, and Publish disables until you press Get it ready again. Nothing is lost, and it is not an error. It is Highport noticing that the page it got ready is no longer the page on your screen.

Publishing

Publish writes one record into your account, keyed by your hostname, containing exactly what the check returned. That record is your site: a list of which of your files answers at which address, plus whatever else you set. It is stored with your account, not in a database we own, and you can read it, copy it or delete it with any AT Protocol tool. The site record is the field-by-field treatment.

If the write fails, the failure comes back with your account server's own words under a heading reading "Publishing failed". A session that lapsed while you were working is the first thing to check. Sign in again and publish again. Reloading the editor is what costs you, because the list of what goes where lives only in the page. The uploaded files themselves survive in your account.

Publishing also lists your domain publicly. Every address serving here appears at hub.highport.space/explore/sites, with the account that published it. That is a DID and not a handle, because the listing carries no handle yet. For a site built from a tile it also names the tile and that tile's author. Highport renders the listing on the server as well as in the browser, marked index,follow, so search engines index it, and nothing on the record or in the editor takes a site out of it. A site leaves the listing when its record is deleted or its domain released, which Editing, deleting and moving on covers.

While it indexes

By the time you press Publish, Orbital Control has already fetched your files and built the page. The write is a confirmation, not the work. Most of what you are about to watch is a record crossing the network.

A panel appears below the buttons and updates every two seconds. It names where your page has got to, and shows a bar while files are still being fetched.

Live is the one you are waiting for. A page that went through Get it ready first has very little left to do, because the files were already fetched and the page already built, so what remains is the swap. The panel watches for two minutes, which is comfortably more than that normally takes. If it does run out, reload the domain's own page, which keeps checking on its own every five seconds. How your site reaches people is where the timing and the caching are.

You do not have to sit here. Below the panel: "You can close this page — {domain} goes on showing the progress." A Visit site link appears on the domain's own page once there is something to visit.

Four other outcomes mean the work has stopped instead of moving on: Failed, Rejected, The check expired — check again, and Replaced by a newer version. The last of those is ordinary. It means you published again while this one was still running.

Under Technical details the panel carries the record's CID, the revision it was published at, how many entries the manifest holds and how many files back them. For a tile-bound site those two numbers are the tile's, not yours.

When a file cannot be fetched

If Highport cannot get one of your files after the record is published, it is listed under "Files Highport could not fetch" with the error and advice for that kind of file:

No button reads Check any more. That was Get it ready's old label, and the advice has not caught up.

For a file of your own this means your account's server no longer answers for those bytes. Upload it again and publish again without leaving it long, because nothing obliges a server to keep a file that no record refers to yet.

After the first one

Editing is this same screen, these same two buttons and the same wait. There is no separate update anywhere in the system. Changing your site means writing the record again at the same key. Editing, deleting and moving on covers that, along with taking a site down, releasing the domain, and getting your files back out.

Site owners · 3 of 12