Pages

Oak Pages publishes a folder of a repo as a static website:

https://<name>.oak.page/

You pick the name, and it's yours across all of oak.page. A repo can have as many sites as you like, each from its own folder: docs/ at one name, examples/demo/ at another. Every merge to main redeploys them. There's no build step on Oak's side: the site serves the files that are on main.

Pages is in early access. If you don't see Settings → Pages on your repo, please let us know and we'll turn it on.

Create a site#

From a checkout of the repo:

oak site create acme-docs --dir docs     # https://acme-docs.oak.page/ ← docs/ on main
oak site create acme-demo --dir examples/demo --spa
oak site list

Or open the repo's Settings → Pages and use Add site. Leave the folder empty to publish the whole repo.

Creating, renaming and deleting sites, changing their folder and setting a password take an owner or admin of the repo's organization, because a site claims a name for the organization. Anyone with write access can redeploy or roll back.

Names#

A name is one DNS label: lowercase letters, digits and hyphens, up to 63 characters, starting and ending with a letter or digit.

Some names aren't available:

• Names Oak uses or might use, and names that could be used to impersonate a service: www, api, mail, docs, login, support and many more. Names starting with oak- are reserved too.
• A name that matches an organization's slug belongs to that organization. Only acme can claim acme.oak.page.
• When a site is deleted or renamed, its old name stays with its organization for 30 days, so nobody else can pick it up and receive its traffic. During that time a renamed site's old address redirects to the new one.

oak site check NAME tells you whether a name is free.

How files are served#

For a request to /path, Oak serves, in order:

1. path/index.html when the path ends in / (the root is index.html).
2. The exact file, then path.html, so /about finds about.html.
3. A redirect to /path/ when path is a folder, so relative links work.
4. With the SPA fallback on, index.html for any path without a file extension. Use this for single-page apps with client-side routing.
5. Your 404.html, with status 404, if the site has one.

Each site is its own origin, so root-relative links like /assets/app.js work without setting a base path in your build. Sites can't read each other's cookies or storage, or oak.space's.

Responses are cached for up to a minute, so a new deploy can take that long to show everywhere.

Deploys#

Every merge to main redeploys each of the repo's sites from the new main. A merge that doesn't change a site's files doesn't create a deployment for it. A deploy that fails (the folder is empty, or a limit is exceeded) is recorded with its reason, and the site keeps serving the last good deployment.

oak site deploys acme-docs           # history, newest first
oak site redeploy acme-docs          # deploy main again now
oak site rollback acme-docs          # back to the previous good deployment
oak site rollback acme-docs --to 42  # or a specific one

A rollback lasts until the next merge to main that changes the site.

If your site needs a build step, commit the build output to a folder and point the site at it. Uploading a build from CI is on our list.

Private repos and path permissions#

You can publish a site from a private repo. The site itself is public, so only publish folders you mean to share. Files that path permissions hide from a repo's readers are never published, whatever folder the site points at.

To keep a site private, set a password in Settings → Pages or with oak site set NAME --password-user USER --password-file FILE. Visitors then get a browser sign-in prompt (HTTP Basic Auth).

Limits#

Sites serve static files with GET and HEAD only. Paths under /_oak/ are reserved for Oak (/_oak/health reports the live deployment).

Moving and deleting#

Transferring a repo to another organization deletes its sites, and their names stay with the old organization for 30 days. Deleting a repo deletes its sites the same way.

Reporting abuse#

To report a site for phishing, malware or other abuse, email [email protected] with its address. We can disable a site immediately.