circagraph
Sign inSign up

Administration, storage limits and automation

Installation administrator

Set these values in the operator's private .env before starting Compose:

ADMIN_USERNAME=admin
ADMIN_EMAIL=operator@example.org
ADMIN_INITIAL_PASSWORD=use-a-unique-password-of-at-least-15-characters
DEFAULT_USER_STORAGE_BYTES=500MiB
API_KEY_REQUESTS_PER_MINUTE=120

Use your own password, never the example. ADMIN_EMAIL is optional; configure a real recovery address and Resend before offering password recovery. Migration creates one verified installation administrator with a storage exemption. It refuses to promote an existing username/email, protecting against username squatting. The bootstrap ID is saved in PostgreSQL: restarting, rebuilding, or changing the environment password does not reset an existing account. Configure RESEND_API_KEY, AUTH_EMAIL_FROM and a persistent AUTH_ENCRYPTION_KEY to enable the existing password/email/MFA management flows. After first login, change the password in Account, enable authenticator MFA, and store recovery codes. Remove ADMIN_INITIAL_PASSWORD from the environment after successful setup. Keep .env out of source control and restrict its file permissions.

Resetting the administrator's password

An administrator who cannot sign in can have their password set back to ADMIN_INITIAL_PASSWORD from the configuration. To choose a new password, write it there first. The command needs access to the server and its configuration:

InstallationCommand
Debian, Ubuntu, Rocky, RHEL and Fedora packagessudo openchronology-reset-admin-password
FreeBSD packageopenchronology-reset-admin-password, as root
macOS (Homebrew)openchronology-reset-admin-password
Windowsopenchronology-reset-admin-password in the installation folder, as an administrator
Docker Composedocker compose run --rm migrate node server/reset-admin-password.mjs
From the sourcenpm run reset-admin-password (reads .env)

It resets the ADMIN_USERNAME account, or the administrator the installation created first if ADMIN_USERNAME is empty:

  • Its sessions, pending desktop sign-ins and password-reset links end, and the reset is recorded in the administration audit.
  • Its API keys and authenticator stay. If two-factor authentication is on, signing in still asks for the code.

Changing the configuration alone, or restarting, does not change an existing password.

The configuration is read the way systemd and Docker Compose read it: # starts a comment only at the beginning of a line, so a password may contain # (#118). Releases before this one read it in openchronology-migrate with Node's --env-file, which ends a value at an unquoted #. An administrator created that way has a password cut off at the #. Sign in with the part before it, or run the reset command after upgrading.

Open /account, sign in, and follow Site administration to /admin. Administrators can search and paginate users and timelines, grant/revoke admin access, suspend/reactivate users, set quotas and exemptions, feature timelines, change visibility, and delete timelines. Reports is the review queue for what readers report (moderation). Each user shows its standing, which decides whether browsing lists its public timelines; mark an account trusted or untrusted to override it. Suspensions preserve user-owned data; there is no automatic ownership transfer or destructive account removal. The last active administrator cannot be suspended or demoted. Private timelines are available to site administrators for management; private-fork publication restrictions still apply. Operators should disclose their access to private data.

Inspecting an account's timelines. A user card's Timelines lists that account's timelines alone, private ones included, and each title opens the timeline. Only an enabled administrator signed in to the site sees them: an administrator's API key reaches only what its own account owns or was given, so no script or integration inspects private timelines. Opening a timeline is not recorded in the audit, and an administrator may save changes to it as its owner could, so look without saving. The list is GET /api/admin/timelines?owner=<username>.

Releasing an account from the directory. An account made by a directory sign-in has no password, and cannot add one or another way to sign in, so that the directory decides who signs in. When directory sign-in is turned off, or a person moves off the directory, such an account is stranded. Its user card says Signs in only through the directory and offers Release from directory, confirmed like any change. It unlinks the directory account, signs the account out everywhere, revokes its API keys, and emails a link to choose a password to its confirmed address; the link lasts 30 minutes, and Forgot password on /login sends another. Signing in through the directory again afterwards makes a new account. The release is recorded in the audit with whether a link was sent (reset_link_sent; none without a confirmed address or configured email, in which case the person uses Forgot password once email works). It is deliberately never automatic: a directory that is unconfigured only by mistake does not release anyone. Ending access is automatic, though: the server checks directory accounts hourly by default (LDAP_CHECK_MINUTES) and signs out, and revokes the API keys of, people the directory no longer lets in, recording each in the audit as directory-left (when someone leaves the directory); suspending an account still ends its access at once. An administrator who itself signs in only through the directory and is locked out uses the password reset command, which gives it a password, then releases the others from /admin; there is no separate command.

Admin mutations require a live interactive session, the current password, and a fresh authenticator/recovery code when MFA is enabled. An administrator without a password (signed up through a provider) instead signs in again within five minutes of the change. Mutations are recorded in oc_admin_audit without passwords or codes. Suspension/demotion revokes sessions, API keys, and pending desktop login requests. Access checks query live account state instead of trusting a browser-supplied role.

Upgrading

An upgrade of the Linux and FreeBSD packages stops the server, the mail worker, the log importers (syslog and, on Linux, journald) and the GitHub receiver until the database is migrated. openchronology-migrate then starts the server, and each of the mail worker, the log importers and the GitHub receiver that is enabled (on macOS, whose launchd agent was started; on Windows, whose service starts with Windows, as the installer also does). One left disabled, because it is not configured, stays stopped. openchronology-migrate --no-restart migrates only and starts nothing. Releases up to 0.12.1 started only the server, so account email (confirmations, password resets, security notices) waited in oc_mail_outbox until someone started the worker (#371), and logs went unimported until someone started the importers (#374); after upgrading such an installation, check them with systemctl is-active openchronology-mail openchronology-syslog openchronology-journald. With Docker Compose, see upgrades.

The rename to Circagraph. The project was called OpenChronology until 2026-11-14. Configurations written for OpenChronology keep working beside the new names:

  • Settings: each OCH_<name> setting may be given as CIRCAGRAPH_<name> instead, such as CIRCAGRAPH_API_KEY, CIRCAGRAPH_API_URL or CIRCAGRAPH_CONFIG, in the environment or in a configuration file. When both are set, the new name wins.
  • API keys: new keys begin cg_key_. Keys beginning och_key_, made before the rename, keep working until they expire or are revoked.
  • Files: the editor and the desktop app open .circa (desktop) and .circax (exchange) files as they open .och and .ochx, and the server accepts application/vnd.circagraph.sqlite beside application/vnd.openchronology.sqlite.
  • NixOS: the module's options are services.circagraph; services.openchronology still works, with a warning to rename it (Nix).

Newer releases (#601): when an administrator is signed in and a newer release than the server's is out, a banner under the header says so. It links the release notes and these instructions. Only administrators see it, and Dismiss until the next release hides it for that release, for that administrator, on any device. The server asks GitHub for the latest release at most every ten minutes, as the download page does. A server built from an untagged commit never shows it. Set UPDATE_NOTICES=off to turn it off, for a server that keeps its version on purpose. The desktop app tells its users the same way, asking at most once a day; its banner can be dismissed per release, or turned off with Don't check for updates.

Data quotas

The default quota per user comes from the environment file or from /admin:

  • Set in the environment file: DEFAULT_USER_STORAGE_BYTES (a byte count, or a size such as 500MiB or 2GB; decimal units are powers of 1000, binary ones of 1024) applies at every start. /admin shows it, and changes it only when the variable is removed.
  • Unset or empty: the default starts at 100 MiB and is changed in /admin, where it persists across restarts.

An invalid value stops the server at startup with a message saying why. A user's quota can inherit the site default, override it with an exact byte count, or bypass the limit. Administrators and the reserved, non-login seed account are exempt. Set the default to 0 for a read-only installation, then grant exemptions or positive limits to designated data suppliers. Reading public or shared data is unaffected; local in-memory drafts and .ochx exports remain available. Timeline-data deletion is allowed to free space.

Usage measures logical UTF-8 JSON bytes: the current timeline, every retained saved revision, proposals (including base/proposed documents), comments, and published plugin definitions. Moment metadata, embedded images, custom scripts, and presentation settings are inside those documents. Saved revisions count separately even if physical snapshot storage is shared. Proposals and their revisions are charged to their author; ordinary timeline/history writes are charged to the timeline's owner. Indexes, database overhead, account settings and bounded avatar uploads are excluded. This is a predictable contribution quota, not a disk-volume limit; operators still need database backups and disk monitoring.

PostgreSQL triggers maintain a storage ledger and serialize charges against the user row. Concurrent writes cannot both consume the same remaining allowance; over-limit growth rolls the entire transaction back with HTTP 413. A zero limit denies contribution operations with 403. Lowering a limit or migrating existing data never deletes it: existing usage is retained, and future growth is blocked. Deleting a timeline can retain historical ancestors required by forks or pull requests, so usage may not drop to zero. History is intentionally immutable; saving checkpoints consumes quota even if edits are small.

Timeline size

A timeline holds at most 200,000 moments, and at most as many durations and as many relationships. TIMELINE_ENTRY_LIMIT in the environment file changes this for the server: a whole number of at least 1000 (such as 1000000), or unlimited. Empty or unset is 200,000. An invalid value stops the server at startup with a message saying why. The server tells its pages the limit, and they warn when a timeline reaches three quarters of it.

How large a time may be

Times are exact rationals of any size in the editor, the desktop app and the offline file. On a server, a time's exact fraction (in lowest terms) may have at most 1,000 digits over 65: from 10^-64 to below 10^1000 of the timeline's unit, such as seconds. That's far beyond any timeline so far (the largest use 18 and 7 digits). TIME_DIGIT_LIMIT in the environment file changes it: <numerator>/<denominator> digits, each from 20 to 1,000,000 (such as 5000/500), or unlimited. Empty or unset is 1000/65. An invalid value stops the server at startup with a message saying why.

The limit is there because a shared server reads, compares and summarizes every time it stores, and the cost of that grows quickly with their digits: a few moments timed in fractions of thousands of digits each keep the server busy for minutes, and anyone who may save a timeline could send them. Times past the limit are refused, counted by their digits before any arithmetic, with a message naming the limit. Set unlimited where everyone who may save a timeline is trusted, such as a server of your own or your team's, to keep times as unbounded on the server as everywhere else.

The default suits a public platform, where the server is shared. Most work on a timeline reads or changes only part of it, at a cost that grows slowly with its size:

  • Saving changes the timeline's index in place and keeps, in its saved history, only the versions of what changed. A save's time and its storage charge follow the change, not the timeline's size.
  • Viewing reads only what is on screen.

Some work handles the whole timeline at once, and its time grows with it: exporting to .ochx and reading a saved revision (history pages). Both stream: the server sends the document as it reads it, a page at a time, so its memory stays about the same at any size. The editor exports a server timeline of over 100,000 moments with no unsaved edits the same way, straight from the server to the file, rather than assembling it in the browser; images it links to by address are then not embedded (those the timeline stores are). Forking, pull requests, merges and syncs read only what changed.

These figures come from an 8-core virtual machine with PostgreSQL 17, using the benchmark timelines (moments with titles, descriptions and tags, plus one duration and one relationship for every ten moments):

MomentsSaving 10 momentsSaving 5,000 new momentsHistory it keepsReading a saved revisionExportingServer memory
200,0000.05 s2–3 s0.4 MB3.4 s3 s0.1 GB
1,000,0000.1–0.2 s4–6 s0.4 MB14 s12 s0.1 GB

A save reads the index nodes it changes in one statement, which follows the nodes on the paths to its moments rather than the moments themselves: appended log moments share nearly their whole path. bench/save-size.mjs measures saves against timeline size. The server stops any statement after 30 s and answers 503; the log importer and the syslog receiver save at most 5,000 entries at a time (the importer 4,999), and halve their saves when one takes 8 s or more or is stopped, so they keep working as timelines grow.

Upgrading copies each timeline's current state into its saved history once, during openchronology-migrate: about 14 s for 200,000 moments and 45 s for a million. Earlier revisions keep the form they were saved in.

Upgrading to a release that keeps background addresses of up to 1,024 characters (#365) rebuilds, once, the indexes of timelines with a duration whose web address is 257 to 1,024 characters long, and of the forks reading through to them, so those backgrounds show. Finding them reads every duration's definition once; oc_migrations records that it ran, so later upgrades skip it.

The large tables are maintained more often than PostgreSQL's defaults. By default, autovacuum waits until a fifth of a table has changed, or grown by a fifth, and refreshes the planner's statistics after a tenth. With hundreds of millions of rows, that's far too late. openchronology-migrate sets the timelines' index tables, their retired versions and their saved history to be vacuumed after about 2% of their rows change or are added, and analysed after 1%. Vacuum skips pages nothing changed, so small installations barely notice. A value you've set yourself on one of these tables, with ALTER TABLE ... SET, stays across upgrades.

A timeline can stop keeping saved history (Keep saved history in its settings), for logs and other timelines whose past revisions nobody reviews. History roughly doubles what a timeline is charged: at 200,000 moments, a 38 MB timeline was charged 78 MB with it and 38 MB without. Turning it off took 1 s; turning it on again copies the current state once, as upgrading does (15 s). Upgrades start no history for timelines without it. See timelines without saved history.

Forks and duplicates share saved history with the timeline they copy, instead of copying it: a new copy keeps no history beyond its settings, and its saves keep only what they change. At 200,000 moments, a fork used to add 37 MB of history and now adds a few hundred bytes. A copy shares its source's index too: it reads through to it, keeping rows of its own only for what it changes, so a fork of any size is ready at once (at 200,000 moments it used to take 30 s to copy, and before that 2 minutes to rebuild). Reading a fork takes about 1.2 to 1.5 times as long as reading its source. Once forked, a timeline keeps the earlier version of each index row it changes while a fork reads it, so its index grows by about one row per row its saves change. Those versions go when the forks reading them are deleted, saved as whole documents, or compacted: a fork that has rewritten half of its moments copies the rest of its index in the background after saving and stops reading through. A deleted timeline's index is kept while forks read through to it, then removed. Upgrading removes the versions earlier releases kept after a fork was deleted. A copy of a copy of a copy of a copy (four levels) reads through to all of them; a copy one level deeper copies only what its source changed itself, inside the database, and reads through to the rest, so it costs what its source changed rather than the whole timeline. When that is 20,000 rows or more, the copy is answered at once and made afterwards, while its page says it is being prepared. At 200,000 moments, a copy whose source changed 1,000 moments took 5.5 s (most of it refreshing the planner's statistics, as after a save of 1,000 changes to a fork), and one whose source changed 26,000 was answered in 0.4 s and ready in 9 s (a whole copy used to take about 30 s). Until it is ready, the API answers HTTP 409 for its index, and only its metadata, sharing, settings and deletion are available. A copy left unprepared by a restart is prepared when the server starts. Reading one of the copy's saved revisions takes about a third longer than reading the original's (6 s rather than 4.6 s), because it reads through to the original.

Pull requests keep no whole timelines. A pull request refers to saved revisions, and a timeline submitted for review is kept as rows that read through to its base, so it is charged only for what it changes. Reviewing, merging and rebasing one, and syncing a fork, read only what changed. At 200,000 moments, merging a fork's pull request of 200 changes took 0.35 s (150 s when merges read whole timelines), and syncing 100 upstream changes into a fork 0.9 s (161 s before). Opening the proposed timeline reads it whole, as does submitting one from the editor.

Some limits stay the same whatever this setting is:

  • The offline HTML file and the desktop app's .och files hold 200,000 moments. The platform's pages follow the server's limit, including timelines kept in the browser, but the browser is slow well before that: past about 10,000 moments, save the timeline to the server (see Timeline size and platforms).
  • An HTTP request carries at most 16 MiB, so creating or importing a whole timeline in one request stays below roughly 100,000 moments. Larger timelines grow through saves: the platform's editor, the log importer and the syslog receiver all save in batches. Requests anyone may make carry only what they need: a query of a timeline at most 1 MiB and 64 KiB (most are a few hundred bytes; an overview may carry a comparison's plugins), the desktop and social sign-in starts and the desktop poll 1 KiB, and a JSON body nested more than 128 levels deep is refused unread.
  • Without an account, an address may query timelines 600 times a minute in each server process (an IPv6 address counts by its /64 network, as for every per-address limit). A separation by tags or relationships is built on its first query for each saved revision: at most 20 builds a minute per address without an account and 60 per account, two at once in each process with up to 16 waiting (503 "Separating is busy" beyond). Filters naming tags or entities a timeline lacks build nothing new (how separations are read).
  • .och files exchanged with the server are at most 64 MiB. TIMELINE_FILE_BYTES in the environment file changes this: a size from 1MiB to 1GiB, such as 128MiB. An invalid value stops the server at startup. The limit applies to uploads, exports, and the converter's input and output; the converter's memory limit is 512 MiB, or eight times the file limit when that is more. At most two conversions run at once, so a raised limit can briefly use two uploads' worth of server memory, and up to twice the converter's memory limit. An .och file is usually larger than the same timeline as .ochx, mostly from its indexes: 200,000 moments with a title and a 150-character note make about 61 MB of JSON and a file just over 64 MiB. A conversion stopped by a limit says which one.

A timeline's moments and durations can link to entities on other timelines, or to other timelines as a whole (links to other timelines). A timeline has at most 10,000 such links, counting the links at both ends: a link from one timeline to another counts against both. TIMELINE_LINK_LIMIT in the environment file changes this: a whole number of at least 1, or unlimited. Empty or unset is 10,000; an invalid value stops the server at startup. Adding a link past either timeline's limit is refused, with how many links it has. The administration page shows each timeline's count.

The limit bounds what links cost. The cost of these grows with how many links a timeline has:

  • Saving a timeline with links checks that the entities they join still exist.
  • Comparing two linked timelines finds the links crossing the view.
  • Deleting a timeline deletes its links.

Creating and removing links is limited to 60 a minute per account, besides the rate limit of API keys. Only someone who may save both timelines can link them, so nobody can attach links to someone else's timeline.

Cached downloads

Downloading a whole timeline (.ochx or .och) makes the file from the database each time, which at 100,000 moments takes over a second. With the export cache, the server keeps each file it makes for a revision and sends that file to the next person who downloads the same revision. A save makes a new revision, so the next download is made fresh and kept in turn. The cache covers the editor's Export of large timelines (/api/timelines/{id}/export/…), .ochx downloads with ?download=1 (of a timeline or of a saved revision), and .och files (/api/timelines/{id}/file). Comparisons are not cached: they are read from their sources.

Measured on the benchmark timelines (bench/export-cache.mjs), to the last byte:

Moments.ochx sizeWithout the cacheFirst downloadFrom the cache
20,0003.5 MB0.32 s0.39 s0.08 s
100,00018 MB1.4 s1.7 s0.26 s
200,00036 MB2.6 s2.6 s0.46 s

The first download of a revision is sent as it is made, as without the cache, while it is written to the cache beside it. A file is only kept once it is complete, and only for the revision it was asked for: a save landing while it is made makes it a newer revision's, sent but not kept.

Who may download is checked on every download, cached or not, exactly as without the cache: a cached file of a private timeline goes only to those who may see it. A saved revision whose content was later forgotten (saved history turned off) is no longer served.

Settings in the environment file:

  • EXPORT_CACHE: disk, s3 or off. Unset, the cache is on (disk) when it has a directory, and off otherwise. The Debian and RPM packages' service gives it one (systemd's CacheDirectory, /var/cache/openchronology/exports), so it is on there by default. Set off to turn it off.
  • EXPORT_CACHE_DIR: the directory for disk. With s3, where files are written before they are uploaded (the system's temporary directory when unset).
  • EXPORT_CACHE_MAX_BYTES: the most the cache holds, a size such as 10GB or 500MiB (at least 1MiB). Unset, 2 GiB. When a new file takes it past the limit, the files downloaded least recently are removed until it fits. A file larger than the whole limit is sent but not kept.
  • EXPORT_CACHE_PUBLIC_URL: an address where the cache's files can be downloaded directly: a web server or CDN in front of EXPORT_CACHE_DIR, or the bucket's public address (or a CDN in front of it). When set, downloads of public timelines' files, once cached, redirect there (302) from the editor's export address and saved revisions' downloads, so the file is served by that server rather than by Circagraph. A file's address is <EXPORT_CACHE_PUBLIC_URL>/<key>: its folder (32 random hexadecimal digits) and file name under the directory, or the bucket key (with EXPORT_CACHE_S3_PREFIX). Private timelines' files are never redirected: Circagraph checks access and sends them itself.
  • For s3 (AWS S3, Cloudflare R2, DigitalOcean Spaces, MinIO, SeaweedFS or another S3-compatible store):
    • EXPORT_CACHE_S3_ENDPOINT: the service's address, such as https://s3.us-east-1.amazonaws.com, https://<account>.r2.cloudflarestorage.com or https://nyc3.digitaloceanspaces.com;
    • EXPORT_CACHE_S3_REGION: us-east-1 unless set (R2 uses auto);
    • EXPORT_CACHE_S3_BUCKET and EXPORT_CACHE_S3_PREFIX (such as exports/);
    • EXPORT_CACHE_S3_ACCESS_KEY_ID and EXPORT_CACHE_S3_SECRET_ACCESS_KEY: a key allowed to put, get and delete objects under the prefix, and nothing else;
    • EXPORT_CACHE_S3_PATH_STYLE: 1 (the default) addresses the bucket in the path (https://endpoint/bucket/key), 0 as a host name (https://bucket.endpoint/key).

A setting the server cannot use stops it at startup, saying which. If the cache's directory cannot be written, it logs why and serves downloads without the cache.

The files are named so they can't be guessed, with 32 random hexadecimal digits each, but a server or CDN in front of the cache's directory or bucket serves every file in it, private timelines' included, to anyone who has its address. Circagraph never hands out a private timeline's file address, so keep directory listings off (and the bucket's listing private). When a timeline is deleted, its cached files go at once. When one that was handed out at the public address stops being public (made private by its owner, or restricted by moderators), its files go within ten minutes (the cache sweeps every ten minutes as downloads arrive). A CDN may keep its own copy until that copy expires: the files are sent with Cache-Control: public, max-age=31536000, immutable from S3, so set a shorter lifetime at the CDN if that matters, or purge it. A storage provider or CDN that holds cached files is a processor of timelines' contents: name it in your privacy notice.

Several servers can share one cache (one database, one bucket or shared directory): a revision is made and stored by one of them, and the others send their own copy while it is being made. A download that starts on the same server while the file is being made waits for it and is then sent from the cache.

Name and analytics

PLATFORM_NAME (for example Example Timelines) replaces "circagraph" in the platform's header. It is also used as the site name in page titles, link previews and oEmbed responses, and the footer then adds "Powered by Circagraph", linked to the project. The pages' structured data names the site with Circagraph as its other name, and says that it runs Circagraph, so search engines and AI answers tie the two names together (#472). When it is empty, Circagraph's name is shown. The name is at most 60 characters, and the server refuses to start if it is longer.

SUPPORT_URL is where visitors can support the platform, such as https://github.com/sponsors/you, an Open Collective page or a page of your own. When it is set, the header ends with a ♥ Support link and the footer has Support this site. When it is empty, neither appears. It must be an https:// address; the server refuses to start with anything else.

GOOGLE_ANALYTICS_ID enables Google Analytics 4 with a measurement ID such as G-ABC123DEF4. When it is empty, nothing changes: pages load no analytics, and the content security policy allows no Google hosts. When it is set:

  • The content security policy allows Google's tag script and measurement endpoints.

  • Each visitor is first asked in a small banner, and Google's script loads only for visitors who choose Allow analytics.

  • The choice is kept in the visitor's browser. Analytics settings in the footer asks again; declining after accepting stops analytics from that page on.

  • Analytics run with Google signals and ad personalization turned off.

  • Embedded timelines (/embed/…) and the editor's frame never load analytics.

  • The site sends each page view itself, with Google's automatic page view turned off, so Google gets only an address and title the site chose:

    • A public timeline's page, and its moments' and durations' pages, are sent at their address and with their title.
    • Every other page of a timeline (a private or unlisted one, its settings and history, a page that doesn't exist) is sent as /timelines, titled "Timeline": not its owner, address or title.
    • /compare is sent without the timelines it compares, /editor without what it opens, and desktop sign-in as /connect, without its code.
    • No address keeps its query (searches, which can name private timelines, and where to return after signing in), and any other ID in a path is sent as (id).
    • Titles are the site's own names for its pages ("Help · Example Timelines"), never the browser's title, which on the editor's pages follows the open timeline.

    In the Google Analytics data stream's Enhanced measurement, turn off Page changes based on browser history events, which would count pages twice and may send their real addresses, and Outbound clicks and File downloads, which report the addresses of links a visitor follows, such as a private timeline's sources.

An ID that is not a measurement ID is refused at startup. Mention analytics in your privacy notice; legal/PRIVACY.md describes the default.

Landing page

A server opens on the timeline browser at /. To pitch it to particular audiences instead, turn on the landing page (#379):

LANDING_PAGE=1
LANDING_EXAMPLES=athan/deep-time,athan/ancient-egypt,athan/computer-science
LANDING_EXAMPLES_EDUCATORS=athan/abraham-lincoln,athan/ancient-egypt,athan/deep-time
LANDING_VIDEO_EDUCATORS=https://www.youtube.com/watch?v=…

LANDING_PAGE is on when it is 1, true or yes, and off otherwise, which is the default. When it is on:

  • / is the landing page: "Any span of time, on one exact line" (titled "Circagraph: free timeline editor for history and research" for search engines and link previews), with Explore timelines, Sign up (when the site takes registrations; Your timelines when signed in) and Start a timeline, the video, a card for each audience, a few public timelines, and the page's copy.
  • /for lists the audiences, and /for/<audience> is each one's page: educators, researchers, investigators, operations, writers and developers. Each has a one-line promise, its example timelines, its video, what that audience can do, and what it can count on. Any other audience is not found.
  • /explore is the timeline browser, with everything / had: drafts, and Explore's search of the library, whose filters also find your own timelines and favorites, with each list's search, tag, sort and page in the address. The header gains an Explore link, the account menu Your timelines, and signing in without a page to return to goes there.
  • The sitemap's pages.xml lists /explore, /for and each audience's page. Each page has its own title, description, canonical address, link preview and schema.org WebPage description, and all of them work without JavaScript, at phone width, and in light or dark mode.

When it is off, / is the timeline browser as before, /explore shows the same browser (its canonical address is /), and /for is not found. The username for is reserved for these pages; an account that already has it keeps its profile at /users/for.

Example timelines. LANDING_EXAMPLES names the landing page's, and LANDING_EXAMPLES_EDUCATORS, _RESEARCHERS, _INVESTIGATORS, _OPERATIONS, _WRITERS and _DEVELOPERS each audience's: owner/slug addresses separated by commas, shown in that order as the browser's cards, with their images. Two or three suit a page; it shows at most six. A timeline that is missing, private, labelled as sensitive, still being copied, or whose owner is suspended is left out without a word. When a page names none, it shows the first three public timelines the browser lists, featured first (featuring).

Videos. LANDING_VIDEO and LANDING_VIDEO_<AUDIENCE> take a YouTube address (youtube.com/watch?v=…, youtu.be/…, /embed/… or /shorts/…). The page shows a poster that links to the video on YouTube; nothing is loaded from YouTube until a visitor clicks it, when YouTube's privacy-enhanced player (youtube-nocookie.com) plays it in place, and the page says so beside it. The player is sent the site's origin as its referrer, which YouTube needs; the site sends none elsewhere. When any video is set, the content security policy of / and /for/… allows frames from https://www.youtube-nocookie.com, and nothing else changes. An address that names no YouTube video stops the server starting, with the setting's name. Mention the videos in your privacy notice if you set them.

The copy is Markdown in platform/content/landing/: home.md, audiences.md and one file for each audience. Each begins with front matter: title (the page's title in search results, browser tabs and link previews, followed by the site's name unless it already contains it), heading (the heading the page shows, when it differs from its title, such as "Any span of time, on one exact line"), promise, description (for search engines and link previews; at most about 160 characters shows whole), and for an audience its label and the card line on the landing page. To write your own, copy the files you want to change into a directory, edit them, and set LANDING_CONTENT_DIR to it; a file it lacks is read from the built-in copy. Pages read the files as they are asked for, so changes show without a restart. The Markdown can have headings, lists, emphasis, code and links to the site's pages or to https: and mailto: addresses; HTML shows as text. A directory that does not exist stops the server starting. In Docker, mount it into the app service, for example - ./landing:/landing:ro under volumes with LANDING_CONTENT_DIR=/landing.

IndexNow

IndexNow tells search engines that take it (Bing, Yandex, Naver, Seznam and others; not Google, which reads the sitemap) which pages changed, so they visit them within minutes instead of at their next crawl (#389). It is off unless you set a key:

INDEXNOW_KEY=$(openssl rand -hex 16)

The key is 8 to 128 letters, digits and dashes; anything else stops the server starting. Once it is set:

  • The site serves the key at /<key>.txt, which is how the engines know submissions for your site are yours. Keep the same key; a new one is fine, but the old file stops being served.
  • About once a minute, the server compares the pages the sitemap lists (public timelines, and the profiles of accounts that own one and are not suspended) with what it saw a minute before, and sends the addresses that changed to https://api.indexnow.org/indexnow, which passes them on to every participating engine: a timeline created or made public, saved, given a new address (the old and the new), made private or deleted (its old address, so engines drop it), and a profile that gains or loses public timelines. Up to 10,000 addresses go in one request, with APP_ORIGIN's host and /<key>.txt as the key's location.
  • The pages of moments and durations go too (#453), for the timelines whose entities the sitemap lists (public, without sensitive-content labels, and with at most SITEMAP_TIMELINE_ENTITIES moments): all of a timeline's when it is made public or given a new address, and after a save those it added, changed or removed, and both ends of each relationship it added or removed, read from the timeline's saved history. A timeline that keeps no saved history sends only its own page. Adding or removing a link between timelines sends the pages of both its ends: a moment's or duration's where its timeline's entities are listed, a timeline's own page for a link to it as a whole. When a timeline is renamed, made private or deleted, its entities' old addresses are not sent; engines drop them at their next crawl, as the sitemap no longer lists them.
  • Each address is sent at most once an hour, so a timeline a log stream saves all day is sent hourly. A timeline that was never public is never sent.
  • It runs in the background of the platform's process, with a ten-second limit on each request, and never holds up a page or a save. A request that gets no answer, 429 or a server error is tried again after a minute, then two, four and so on up to an hour; one refused (400, 403, 422: a wrong key or APP_ORIGIN) is logged and dropped.
  • What changed while the server was stopped is not sent: the first comparison after a start only takes stock. The sitemap covers it.
  • Nothing is sent while APP_ORIGIN is localhost or a loopback address, which the engines could not reach.

Check it works by opening https://<your site>/<key>.txt, then watch the log for IndexNow: submitted … after you save a public timeline. Bing Webmaster Tools lists what it received under IndexNow.

Reverse proxy, page caching and page speed

The server renders each page as it is asked for. A reverse proxy in front of it, such as nginx, can keep a copy of the public pages that signed-out visitors and search engines read, and answer from it for a minute, so a busy timeline is rendered once a minute rather than for every reader (#473).

What the server allows a shared cache to keep. These pages, asked for with GET or HEAD and without a session cookie (oc_session, or __Host-oc_session over HTTPS) or an Authorization header, are sent with Cache-Control: public, s-maxage=60, stale-while-revalidate=300 and Vary: Cookie:

  • the home page, /explore, /for and each audience's page, and the help (/help, /help/<page>);
  • profiles (/<username>, /users/<username>);
  • a timeline's page, and its moments' and durations' pages, at either of its addresses (/<owner>/<slug>/… or /timelines/<id>/…).

Signed out, a private timeline's pages are not found, the same for everyone, so that 404 may be kept too. Everything else is sent with private, no-cache, no-store: every page seen with a session, the sign-in, account, administration, editor, download and plugin pages, a timeline's history, settings and pull requests, the router's payload that the site's own links fetch, server errors, and the API. Little changes for a site without a cache: s-maxage gives browsers no lifetime, and Vary: Cookie keeps a copy from before signing in from being shown after.

A page carries a fresh nonce for its content security policy, written into its scripts and its Content-Security-Policy header alike, and a kept copy keeps both, so it runs as it did. Everyone who reads that copy gets the same nonce. That doesn't weaken the policy: script injected into a page would have had to carry the nonce before the render that chose it, and the next render, a minute later, chooses another.

What it means for changes. A change to a public page, a timeline made private, or content taken down by moderation reaches signed-out readers within a minute, and one reader more may get the old copy while the cache fetches the new one. To remove something at once, empty the cache (below). Do the same after upgrading, since pages kept from before name script files the new version no longer has.

A cache in nginx. In the http block (for example a file in /etc/nginx/conf.d/):

# Leave nginx's version out of its Server header and error pages.
server_tokens off;
# Where kept pages go: 10 MB of keys, at most 1 GB, dropped when unread for 10 minutes.
proxy_cache_path /var/cache/nginx/openchronology levels=1:2 keys_zone=openchronology:10m
                 max_size=1g inactive=10m use_temp_path=off;
# A request with a session cookie, in either form, is a signed-in visitor's.
map $http_cookie $openchronology_session {
    default 0;
    "~(^|;)\s*(__Host-)?oc_session=" 1;
}

And the site:

server {
    # With nginx before 1.25.1, `listen 443 ssl http2;` instead of `http2 on;`.
    listen 443 ssl;
    http2 on;
    server_name timelines.example.org;
    ssl_certificate /etc/letsencrypt/live/timelines.example.org/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/timelines.example.org/privkey.pem;
    server_tokens off;

    location / {
        proxy_pass http://127.0.0.1:5173;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        # One address, the client's, so the server may set TRUST_PROXY=1.
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 256m;
        proxy_read_timeout 1h;

        # Keep what the server marks public for as long as it says, never a session's, a
        # token's or the router's payload, and refresh a stale page in the background.
        proxy_cache openchronology;
        proxy_cache_key $scheme$host$request_uri;
        proxy_cache_bypass $openchronology_session $http_authorization $http_rsc;
        proxy_no_cache $openchronology_session $http_authorization $http_rsc;
        proxy_cache_use_stale updating error timeout http_502 http_503 http_504;
        proxy_cache_background_update on;
        proxy_cache_lock on;
        add_header X-Cache-Status $upstream_cache_status always;
    }
}

nginx follows each response's Cache-Control, so it keeps only the pages above, for a minute; with no proxy_cache_valid, it keeps nothing the server didn't mark. It also follows Vary: a visitor who carries other cookies, such as Google Analytics' after allowing it, gets a copy of their own. The session cookie bypasses the cache outright, so a signed-in visitor never gets a signed-out copy. Live updates (/api/live) send X-Accel-Buffering: no, so they stream with buffering on, which a cache needs. X-Cache-Status shows MISS, HIT, STALE, UPDATING or BYPASS: curl -sI https://timelines.example.org/help | grep -i -e cache-control -e x-cache-status twice should show a MISS, then a HIT. To empty the cache, delete what is in its folder, /var/cache/nginx/openchronology/; nginx carries on without a reload.

The NixOS module's virtual host (services.openchronology.nginx.enable) sets server_tokens off but keeps no cache, and turns proxy_buffering off, which a cache can't work with. To cache there, leave nginx.enable off and write the virtual host from the sample above, putting the http block's lines in services.nginx.appendHttpConfig. Caddy, which the packages' READMEs show, has no cache of its own and doesn't announce its version.

Measuring page speed. Google ranks pages partly by their Core Web Vitals: how soon the largest thing on the page shows (LCP, good under 2.5 s), how soon it responds to a click or key (INP, good under 200 ms) and how much it shifts as it loads (CLS, good under 0.1). They need a site on the public internet and a browser, so CI doesn't measure them; measure your own site:

  • PageSpeed Insights: enter an address. It shows what real Chrome users measured over the last 28 days, once the site has enough of them (INP is only measured there), and a Lighthouse run from Google's servers, for phones and computers.
  • Lighthouse, in Chrome's developer tools (Lighthouse, then Analyze page load, in a guest window so you are signed out), or from the command line: npx lighthouse https://timelines.example.org/ --only-categories=performance --view. Its lab run reports LCP and CLS, with Total Blocking Time standing in for INP.
  • Google Search Console's Core Web Vitals report groups the site's pages by how they fare, from the same real-user data.

Measure the home page, /explore, a timeline's page and a moment's page, signed out, each twice in a row: with a cache, the second is served from it, which shows in its time to first byte. Write the results down with the date and version, to compare after upgrades.

Terms and privacy policy

Every account agrees to the terms of service and privacy policy in force: at registration, at a social account's email step, or, for an account made earlier (including the first administrator), when asked on its next visit. Until then it can read and manage its account but not save or share. Each account records the version (oc_users.terms_version, the policies' effective date) and when (terms_accepted_at); SELECT username,terms_version,terms_accepted_at FROM oc_users lists them. Changing the policies materially means changing POLICY_VERSION in server/policies.mjs and oc_policy_version() in schema.sql; see authentication.

Account settings

/account includes password changes, verified email changes, MFA/recovery codes, session revocation, Google/GitHub/Facebook/Microsoft and directory-account linking and unlinking, and avatar settings. OAuth provider registrations, directory (LDAP and Active Directory) sign-in and Resend configuration are described in authentication. Linking uses the existing explicit OAuth flow; unlinking requires fresh confirmation and retains at least one sign-in method. Avatars accept HTTPS image URLs or PNG/JPEG/WebP uploads up to 256 KiB. Remote images are requested by the browser, not fetched by the server; their hosts receive the viewer's network request. SVG and executable URL schemes are not accepted. Changing or resetting a password, confirming a new email address, and changing two-factor authentication, recovery codes or passkeys also revoke existing API keys.

API keys

In Account → API keys, name a key, choose read access or read/write access, and set an expiry of 1–365 days (default 90). Confirm your password/MFA as above. The complete secret is shown once; only its SHA-256 hash and safe metadata are stored. Copy it to your ingestion service's secret store. Keys can be revoked immediately or removed. At most 100 key records per account are retained.

Use the HTTPS API with Authorization: Bearer <key>; never put keys in URLs, exports, client-side scripts, logs, or timeline metadata. A key cannot manage accounts, create other keys, change authentication settings, use file conversion endpoints, or access site administration. It acts with the user's existing permissions and quota on /api/timelines endpoints only. Read scope includes POST search and bounded query operations. Write scope permits creating/saving user-owned timelines and other contribution actions allowed by their role. Private timelines belonging to other users remain inaccessible unless the key's user already has access. Requests are rate-limited per key (default 120/minute, operator-configurable from 1–1000). MFA is required when issuing keys, not for every unattended API request. Suspension, expiry, revocation, and password changes stop their use.

Example ingestion sequence (store the key in your process environment):

# Create a timeline from an exported, validated .ochx JSON document.
curl --fail-with-body https://circagraph.org/api/timelines \
  -H "Authorization: Bearer $OCH_API_KEY" \
  -H 'Content-Type: application/json' --data-binary @timeline.ochx

Keep the returned timeline UUID and revision. To update, fetch GET /api/timelines/<id> for the current revision, then send PUT /api/timelines/<id> with { "revision": "<current>", "document": <document> }. A stale revision returns 409; fetch again and reconcile instead of blindly overwriting. Partial moment updates use the same revision check at PUT /api/timelines/<id>/changes, or merge onto a newer revision when they say what they were made on; see saving while others save. Use POST /api/timelines/<id>/query for bounded windows instead of downloading whole large documents. Keys are also accepted from desktop/aggregation clients; interactive browser sessions retain their existing CSRF protection.

Design references: OWASP authentication guidance and REST security guidance.

Verification

node --test test/administration.test.mjs validates quota, avatar, key-definition and scope boundaries. With DATABASE_URL pointing to a dedicated test database with pgmp, run node test/administration-postgres.mjs. It tests real HTTP and PostgreSQL enforcement, bootstrap idempotence, permission/CSRF failures, quota rollback and concurrent writes, key hashing/scopes/expiry/revocation, suspension, and migration accounting. The integration test temporarily changes installation policy and creates an administrator; never run it against a production database. GitHub CI runs it with the other PostgreSQL integration suites.

This page is docs/administration.md in the source code, as this server runs it.