Configuration

Every .env key, the Settings panel inside the app, and which of the two wins when both say something.

There are two places to configure Astrolabe, and they mostly cover the same ground.

1. An .env file. This is a plain text file next to the app, one KEY=value per line. The server reads it once, when it starts. To change something here you edit the file and restart.
2. The Settings panel. This is inside the app itself. When you change something there, the server writes it to a file called settings.json in its data directory, and the change takes effect immediately. No restart.

Most settings exist in both places. When they disagree, the Settings panel wins: a value saved in the panel overrides the same key in .env. If you clear the field in the panel, the .env value takes over again. A few keys are the exception: the security-sensitive ones (the password, the session secret, the port, and so on) live in .env only, and the panel never shows or changes them.

Updating a server you run yourself

The server reads its version from package.json, and the client carries the version it was built with. After git pull, run npm run build and restart: the pull moves the version, the build moves the files. If an open tab outlives a deploy it says Astrolabe X is now on the server; reload to catch up, once. If a reload brings the same old build back — the files were never rebuilt, or a service worker is still handing out the old shell — the app says so instead, once per version, and stops asking: the server says it is Astrolabe X but serves the Y build. That line means exactly one thing: run npm run build (or reinstall the package) on the machine that runs the server. The desktop app and the Android app ship their own build with their own server, so they never show it.

Environment variables

An environment variable is a named value the server reads when it starts. You can set it in .env or in the shell that starts the server; either way it reaches the same place.

The npm scripts load .env on their own (node --env-file-if-exists=.env), so you never need export or source. The file .env.example in the repository root lists every key with a comment explaining it. The table below is the short version.

If you installed this when it was called Vellum. Every key above still answers to its old spelling: VELLUM_VAULT, VELLUM_DATA and the rest are read when the ASTROLABE_* key is not set, so a .env, a systemd unit or a shell alias written before the rename keeps working. When both are set the new spelling wins, and the startup line names the old keys it leaned on, once. /vellum.sty is still served beside /astrolabe.sty, for papers written against the old package name.

Request size limits. Every request to the server is capped in size before anything reads it, and there is no key for this: 10 MB on any /api request, and a much smaller 64 KB on the two things anonymous visitors can send (comments and login attempts). Anything bigger is refused with HTTP 413 ("request too large") instead of being held in memory. Uploads have their own, separate allowance. If you run the app behind a proxy, a matching limit there is a sensible extra layer — in nginx, client_max_body_size 10m;, or 256m if you will drop films into notes, since a video upload's own allowance is 256 MB.

The Settings panel

Most of the site-identity keys above can also be changed at runtime, from the app — no .env edit, no restart. As admin, open Settings (the gear in the top cluster, or the command palette). Its rail has two levels: four groups — You, Your site, Data and App — each a heading over short pages named for what you came to do rather than for where a value is stored. A page answers one question, opens with its name and one sentence saying what it decides, and shows at most ten rows before its Advanced line. A search box above the rail finds any row by its name, its one-line help, the paragraph behind its ⓘ or its environment variable, and takes you to it wherever it lives. On a phone the same four groups are headed lists, and each page is a screen of its own.

One row, one look. Every row is a label, one line of help under it, and one control in a single column at the right (at the left in Arabic): a switch, a set of segments, a list, a row of named chips, a slider whose value sits in the label (Screen warmth · 30%), a path field with Pick… inside it, a text field, or — for the few rows that are tables — the row's full width. A switch has no "On"/"Off" beside it: the label says what on means. A ⓘ beside a label opens a paragraph under the row saying why you would change it, and — where one stands behind it — the environment variable, ready to copy.

Saved, or kept here. A row kept in this browser saves itself the moment you choose. A page made only of such rows (Appearance, This device) says so once under its sentence; elsewhere the few that are wear a small This device mark. Every other row is the site's, and a Save bar rises at the foot as soon as one of them changes (with Discard beside it), and goes when you save.

You

• Appearance — your theme and the two eye-comfort sliders (see Theming), which edge the notes sidebar sits on, and the writing column's width. All of it is kept on this device.
• Layout & type — the direction and alignment of note prose, which any note may override from its own frontmatter (see Note direction & alignment), and the four font slots (reading text / interface / code / Arabic face) over a curated, self-hosted catalog or faces you upload yourself, with a live specimen that stays on screen while you choose (see Typography).
• Language — your language (Follow site / English / العربية — the app's own words for you on this device, never what visitors get) beside the site language (what visitors read it in); Spellcheck in — one row of chips naming the languages whose lines are handed to the spellchecker: in a browser the four the editor recognises, none until you choose; in the desktop app the dictionaries your computer really has (see the editor); and for visitors, the language filter and the optional visitor switch.
• Dates & calendar — the date calendar (Gregorian / Hijri / both, with a live specimen of today, and with Both which one leads and the mark between them — see Hijri dates); under Advanced, the date locale.
• Writing — Open on launch (where the app opens — where you left off, the Sigils page, the Orbits shelf, today's note, or a note of your choosing — on top of the restored session, and never over a pasted link), the formatting toolbar, Auto-correct French, the properties card (off hides it in your own views — visitors still see it; see the editor) with the empty-note card under it; where new attachments are written (see Attachments), the tags folder and the tag labels table — display names for canonical tags, for a front end that should read «برمجيات» over a vault that keeps #software (see Localised tag labels); under Advanced, the drawings folder.
• New notes & templates — the templates folder and the template for new notes, the periodic notes (one table: the folder the four kinds share, and a name and a template each for the day, the week, the month and the year), the unique note's folder and name, and the capture inbox and the clipper.
• Reading — numbered headings in the reading view, search inside books (PDF search) and feeds with the note that lists them; under Advanced, the hadith corpus folder (the notes that answer > [!hadith] callouts — see Ayah and hadith callouts).
• Read aloud & voice notes — Read aloud and whether your blog's readers may listen; the voice notes' transcription language, the model and where it runs, and whether recordings are kept (see Capture); under Advanced, your own voices.

Your site

• Site identity — name, tagline, a logo image (replaces the text wordmark in the sidebar and the blog masthead), a favicon (served at /favicon.ico with its real content type and injected into every page's <link rel="icon">), the default theme visitors arrive on and the ambient masthead; under Advanced, the footer line.
• Publishing — how much of the site is public, said in numbers at the top; the public layout (app / blog / designed, with the door to the designer under it); the home page — classic note mode with a chosen home note, or the dashboard magazine layout, plus an optional hero banner (read by the blog and designed layouts only, so with Public layout: app the page greys them and says so); share buttons and external video; under Advanced, excluded tags and your other sites.
• Comments & mentions — comments, webmentions and the fediverse, each off until you turn it on.
• Collections — whether categories come from tags or from folders, and your own hand-made collections and where they sit. See Blog mode.
• Library — the public shelf: on or off, its name, where its door is, which folders fill it and the exceptions. See The library.

Data

• Backup & sync — commit the vault and push it to a private git remote you own, manually or on a timer (off until you turn it on); under Advanced, the branch and pull-first. See Backup & sync.
• Versions & travel — keep a copy of each note before every save; what the vault's .astrolabe/ folder carries to the next machine; and whether this browser's preferences travel with it.
• Ask — which models read the notes and answer about them, with the embedding model and the passages per answer under Advanced. See Ask the vault.

App

• This device — the offline copy of what you open, Vim keys (with relative line numbers), the what's-new deck after an update, and in the desktop app only its name, its icon, a launcher entry and Software updates (see the desktop app). All of it is kept on this device.
• About — the version, the Node version, the vault's counts, and the absolute paths of the vault, the data directory, settings.json and the uploaded-fonts folder.

A pocket vault (a GitHub repository opened on the Android app) shows fourteen: Publishing, Comments & mentions, Collections, Library and Ask need a server, and the rows it cannot keep are drawn greyed, with one line saying why.

Image fields reuse the banner machinery: pick from the vault's attachments or upload right there (drag & drop; bytes are sniffed; lands wherever the Attachments setting points).

Attachments

An attachment is any file you put into the vault that is not a note — a picture, a PDF, an audio clip. Where new attachments go is a setting, named the same way Obsidian names it (Default location for new attachments), so a vault that moved from Obsidian behaves the way its owner already expects. It lives in Settings → Writing → New attachments, beside the templates folder and the tags folder.

The setting only decides for uploads that did not name a place themselves: a picture pasted into a note, or a file dropped into the editor. A file dropped onto a folder in the sidebar tree already names a place, and lands in that folder.

The folder you type is checked like every vault path: it must stay inside the vault, it cannot be a dot-folder (a folder whose name starts with . — the tree, the indexer and the file watcher all ignore those), and it is created when first needed. Attachments you already have are never moved. The setting decides where the next upload goes; existing embeds keep working because a note finds its images by file name, whatever folder they are in.

Every way of uploading obeys the setting: paste or drop in the editor, drop onto the sidebar tree, and the upload button in any picker. A note's banner and a Media entry's cover count as uploads into that note, so under Same folder and Subfolder the picture lands beside the note (or the tracker note) it belongs to. The site-wide pickers — home banner, logo, favicon — belong to no note and are measured from the vault root. Fonts (ASTROLABE_DATA/fonts) and custom.css have their own homes and are not affected.

Any file the vault can hold, not just images. POST /api/upload accepts images (png, jpeg, webp, gif, svg, avif, heic, bmp), PDF, audio (mp3, m4a, wav, ogg, oga, opus, flac) and video (mp4, m4v, mov, webm, mkv, ogv). A film may be up to 256 MB and is written to disk as it arrives; every other file is capped at 10 MB. The contents of the file are inspected, so a program renamed to .png is refused whatever its extension says. Anything not on that list is refused in the browser, before the upload starts, with a message naming what was refused and what would have been accepted.

Drop files anywhere on the tree. Drag files from your file manager onto a folder in the sidebar (or onto a note — they land beside it) and they are added to the vault. The row lights up and says how many files are coming. Afterwards a toast names the folder they actually landed in and offers Undo, which moves them to .trash/. If a name is already taken, the new file gets the first free name-2.ext and the toast says so.

Deleting tells you what it is really taking. The sidebar tree shows notes only. So a folder that still held four images after its note moved away used to describe itself as "0 notes" — and deleting it silently broke a published essay. Now every delete confirmation asks the server what is actually inside:

Move "Media" to .trash? 0 notes, 60 attachments — 53 of them referenced by 48 notes. All of it moves to the vault's .trash folder — recoverable from disk.

When only a few notes reference the files, they are named. Only notes that survive the delete count as breakage; a note that goes in the same act is not a broken link. Both kinds of link count — wikilink embeds (![[fig.png]]) and Markdown links (![](assets/fig.png)) — and so does a note's banner:. The confirmation for a permanent delete repeats the same inventory, and deleting a single attachment (the × on a row in the banner picker's list) asks the same question.

Every control in the panel is drawn by Astrolabe, not by your operating system. A dropdown list is a themed popover attached to its button and kept inside the panel: it grows no taller than the room available, flips upward when there is no room below, and takes arrow keys and type-ahead, Enter to confirm and Esc to put the old value back. Switches are switches; three-way rows (inherit / on / off) show all three states at once; numbers carry their unit inside the field. The reason: a native <select> opens a window drawn by the operating system, which no theme can style and no panel can keep inside its bounds — exactly what a font list of twenty-seven faces must not do.

On a phone (the phone layout) the panel is a list of the same nine sections, in the same order and under the same names — More → Settings — with the same search above it, and each section is a screen of its own showing the same rows. As soon as a section holds a change, a bar rises from the bottom with Discard and Save; leaving the section any other way with changes unsaved asks first. A row marked This device saves itself as you choose and never raises the bar.

Settings keys

These are the keys ASTROLABE_DATA/settings.json can hold. The panel writes them, and so does PATCH /api/settings. Any key that is absent falls back to its .env default from the table above.

Two more keys are write-only: gitToken and gitUser. PATCH /api/settings accepts them and stores them in ASTROLABE_DATA/git-credentials.json, readable only by the system user the server runs as (mode 0600). They never go into settings.json and can never be read back: a read answers gitSync.tokenSet: true and the username, nothing more.

settings.json is written atomically, meaning the file is either fully old or fully new — a crash in the middle cannot leave it half-written. Changes apply live: the site name, the layout, the default theme, the excluded tags, the comment routes and the favicon all update without a restart. If the file is ever corrupted, the server logs one warning and runs on the .env defaults.

The security-sensitive keys are deliberately .env only, forever. The panel and /api/settings can neither read nor write them: ADMIN_PASSWORD_HASH, SESSION_SECRET, TRUSTED_PROXIES, PORT, HOST, ASTROLABE_VAULT, ASTROLABE_DATA, PUBLIC. SITE_URL is .env only too, for a duller reason: nothing has ever needed to change it while the server runs.

The settings API

For scripts. Admin only; a visitor gets a 404.

• GET /api/settings returns the stored keys, plus effective (the merged values actually in use), the font catalog, and an about block (version, Node version, absolute paths, counts).
• PATCH /api/settings takes a partial object. Only the keys you name change; null clears a key so it falls back to .env. Validation is strict — an unknown key is a 400 — and the answer has the same shape as GET. The git credential keys additionally require that the instance has a real password.