Subdomains, Site Mode & Hosting

OcaltQL gives you direct programmatic control over your ocalt.site subdomains and live site hosting — all from within a script running in your namespace.

SUBDOMAIN

SUBDOMAIN ADD registers a new subdomain under your namespace. SUBDOMAIN REMOVE deregisters one. SUBDOMAIN LIST returns every subdomain you own. SUBDOMAIN SEARCH filters that list.

SUBDOMAIN ADD "mysite" SET ?result
AFTER EMIT ?result
(* ?result("success") = true, ?result("subdomain") = "mysite", ?result("url") = "https://mysite.ocalt.site" *)
(* Fails with an error if the subdomain is under 5 characters, contains anything other than letters/numbers/hyphens, is already taken, or your tier's subdomain limit is reached *)

SUBDOMAIN ADD "mysite" AT "/mounted/mysite" SET ?result
AFTER EMIT ?result("path")
(* AT places the subdomain's folder anywhere under /root or /mounted.
   Omit it entirely and the folder is created at /root/sites/mysite *)

SUBDOMAIN ADD "shop" ON "tld.com" AT "/mounted/shop" SET ?result
AFTER EMIT ?result("url")
(* Serves at https://shop.tld.com from /mounted/shop *)

AFTER SUBDOMAIN ADD "docs" ON "tld.com" SET ?result2
AFTER EMIT ?result2("url")
(* Serves at https://docs.tld.com from /root/sites/tld.com/docs *)

SUBDOMAIN REMOVE "mysite" SET ?result
AFTER EMIT ?result
(* Fails with an error if the subdomain does not exist, or does not belong to you *)

SUBDOMAIN LIST SET ?subs
AFTER FOREACH ?subs SET ?sub
OPEN
  EMIT ?sub
CLOSE

SUBDOMAIN SEARCH "my" SET ?results
AFTER EMIT ?results
(* Returns only your own subdomains matching the search text *)

Namespace Path

Registering a subdomain creates a real directory at:

/root/sites/{subdomain}/

Every file placed inside this directory becomes reachable at https://{subdomain}.ocalt.site/, following the routing model below.

Routing Model

An incoming request path is resolved in strict priority order:

• Directory wins. If the path resolves to a real directory, its index.oql is used if present, otherwise index.html.
• Exact file match. If the literal path (with its real extension) exists as a file, it is served directly.
• Extensionless fallback. If no exact file exists at the literal path, .oql is tried first, then .html.
• Otherwise, the request 404s.

(* /root/sites/mysite/about/index.oql *)
(* Reachable at https://mysite.ocalt.site/about/ — directory wins *)

(* /root/sites/mysite/contact.oql *)
(* Reachable at https://mysite.ocalt.site/contact — extensionless fallback *)

(* /root/sites/mysite/contact.html *)
(* Also reachable at https://mysite.ocalt.site/contact.html — exact match, always available regardless of the fallback *)

Site Mode Execution

A matched .oql file has its full text executed against the standard OcaltQL API, authenticated internally as the site's owner. Every page view is one real query against the owner's daily quota.

EMIT "<h1>Welcome</h1><p>Powered by OcaltQL.</p>"

Static Files

Any file that is not .oql is served directly with its correct content type. Supported types include:

(* /root/sites/mysite/logo.png — served directly as image/png *)
(* /root/sites/mysite/demo.mp4 — served directly as video/mp4 *)
(* /root/sites/mysite/embed.html — served as text/html, embeddable in an iframe *)

Custom Domains

There are two ways to point a domain at Ocalt, and the choice decides what you can do with it afterwards.

Option 1 — An A record, keeping your own DNS

At whoever provides your DNS, create an A record for the domain pointing at 41.61.20.37. For the apex that is a record on @; for www a second A record, or a CNAME to the apex.

You keep full control of the zone, so anything you already run on the domain stays exactly where it is. Ocalt sees only the traffic that arrives.

Mail is not a reason to choose this route. NEW EMAIL ACCOUNT gives you real mailboxes on the domain either way — under delegation Ocalt writes the records itself; on an A record you add one MX pointing at Ocalt and everything else follows. See IMAP & POP3.

The cost is that every subdomain you want served has to be created by you, at your provider, one record at a time. SUBDOMAIN ADD "shop" ON "tld.com" tells Ocalt which folder to serve, but nothing resolves until an A record for shop.tld.com exists in your zone. A wildcard * record pointing at 41.61.20.37 solves it in one line if your provider allows one.

Option 2 — Delegation to Ocalt’s nameservers

At your registrar, set the domain’s nameservers to dns1.ocalt.com and dns2.ocalt.com. Ocalt then serves the entire zone.

The zone is created with a wildcard, so every subdomain of the domain resolves immediately — shop.tld.com, docs.tld.com, anything you name later. SUBDOMAIN ADD ... ON is the only step, and there is no second system to keep in sync. Certificates are issued for the whole domain rather than one host at a time, because Ocalt can answer the DNS challenge itself.

Mail is handled for you. NEW EMAIL ACCOUNT "hello" AT "tld.com" WITH PASSWORD "..." creates a real mailbox on the delegated domain, and Ocalt writes the MX and authentication records the moment it exists — nothing to configure, nothing to point anywhere. The mailbox is then managed from OcaltQL with the IMAP and POP3 verbs like any other, or from any mail client.

DOMAIN "tld.com" TO "mysite.ocalt.site" SET ?var
AFTER NEW EMAIL ACCOUNT "hello" AT "tld.com" WITH PASSWORD "Password" SET ?acc
AFTER EMIT ?acc("address")

AFTER NEW EMAIL IMAP ?acc("imap_host") WITH "Password" AS ?acc("address") SET ?conn
AFTER EMAIL ?conn INBOX SET ?inbox
AFTER COUNT ?inbox SET ?n
AFTER EMIT ?n & " messages in hello@tld.com"

A domain you already own can be pointed at one of your ocalt.site subdomains — or at a tunnel token subdomain — from a script, with DOMAIN. Point the domain's DNS at Ocalt first; DOMAIN then registers it, reports whether the DNS actually resolves to Ocalt, and issues a certificate.

DOMAIN "tld.com" TO "subdomain.ocalt.site" SET ?var
AFTER IF ?var("status") IS EQUAL TO true
OPEN
  EMIT "pointed"
CLOSE
OR
OPEN
  EMIT ?var("message")
CLOSE

DOMAIN STATUS "tld.com" SET ?status
AFTER EMIT ?status("status")
AFTER EMIT ?status("message")

DOMAIN SSL "tld.com" SET ?ssl
AFTER SWITCH ?ssl("status")
OPEN
  CASE "already in progress"
    EMIT "certificate is being issued, check back shortly"
    BREAK

  CASE "successful - certificate is live"
    EMIT "https is live on tld.com"
    BREAK

  CASE "failed try again"
    EMIT "issuance failed — confirm DNS still points to Ocalt, then retry"
    BREAK
CLOSE

DIRECTIVE "home-nas" TUNNEL PORT 3000 SET ?tunnel
AFTER DOMAIN "tld.com" TO ?tunnel("url") SET ?var
AFTER EMIT ?var("message")
(* The same verb points a domain at a tunnel token subdomain as at an ocalt.site subdomain *)

Namespace Isolation

Site Mode scripts execute inside the site owner's own namespace — the same /root and /mounted filesystem access already available to that account's regular OcaltQL scripts.