Repository navigation
v0.19.0
Before you upgrade a server that ran 0.18 or older: add one line to
.env.
0.19 renames the compose project, volumes, database role and database from the old project namenodianto
inkling, and takes the names from a new required setting,INKLING_DATA_NAME. Put
INKLING_DATA_NAME=nodianin.envbeforedocker compose up(for example
printf '\nINKLING_DATA_NAME=nodian\n' >> .env) and nothing else changes: the same containers, volumes and
data. Without the line compose refuses to start (and leaves the running stack alone); do not answer that by
settinginklingon an existing server, which starts an empty instance next to your data. Moving to the new
names is optional and can wait:./deploy/rename-from-nodian.sh --dry-run, then without--dry-run(copies the
volumes, keeps the old ones,--rollbackat any point). Local trials started with./deploy/local.shneed
nothing. Details: docs/OPERATIONS.md.
A minor release that moves the data plumbing from the project's old name to inkling, gives public links a toolbar
(wide view, Save as PDF and a Markdown download the link's owner can turn on), fixes the app's PDF export and the
sidebar's "More", shows a notice with a Reload button where a screen used to stay white, and greets new accounts
with a short intro, a Getting started card and a sample page. Two database migrations, both additive:
0059_share_allow_download (pages.share_allow_download) and 0060_onboarding (user_onboarding, one row per
existing account). A 0.18 database goes from 59 to 61 applied migrations. No new dependency. One new setting,
INKLING_DATA_NAME, required and without a default (see above); two optional ones, ONBOARDING and
ONBOARDING_EXISTING_USERS. The MCP tool list is unchanged (48 tools, 32 in core). Upgrade matrix adds v0.18.0,
and a new rename job upgrades and renames installs from v0.17.1 and v0.18.0 (.github/workflows/upgrade.yml).
Checked in Chrome only (desktop and a 390 px window): the public page toolbar, its PDF, the app's PDF export, the
sidebar, the start-up notices, the intro and the Getting started card were not tried in Safari, Firefox or on a touch device. The rename job has not
run on GitHub Actions yet; the same script passed locally from v0.17.1 and from v0.18.0 (docs/KNOWN-ISSUES.md,
"Added in 0.19.0").
Upgrade notes
-
The order on a server from 0.18 or older: the upgrade first, on the old names; the rename later, if at all,
after the upgrade is checked, so a migration and a rename never happen in one go../deploy/backup.sh printf '\nINKLING_DATA_NAME=nodian\n' >> .env # 1. keep the old names git pull && docker compose pull app && docker compose up -d ./deploy/rename-from-nodian.sh --dry-run # 2. optional, later: plan, sizes, free disk, downtime ./deploy/rename-from-nodian.sh # the rename (asks once; --rollback at any point)
Without the line every compose command stops with "required variable INKLING_DATA_NAME is missing a value";
nothing was created or stopped. New installs copy.env.example(inkling). Keeping the old names is supported
at least until 1.0 (docs/adr/2340-, 2341-). -
Set
inklingon an old server by mistake: compose starts an emptyinklingproject next to the untouched old
volumes. PutINKLING_DATA_NAME=nodianback,docker compose -p inkling down,docker compose up -d, and delete
the emptyinkling_inkling-*volumes. -
Servers that run Docker through sudo: run the rename script the way you run compose,
sudo ./deploy/rename-from-nodian.sh --dry-run. It writes.envin place (owner and mode kept) and its state
under./backups/rename-nodian-to-inkling/(root-owned when run with sudo). -
An override that names old volume keys (
nodian-data:/…) must use the new keys (data,db,backups,
backup-ctl,rclone-bin); compose reports "undefined volume" until then. -
After the rename, containers are
inkling-app-1,inkling-db-1,inkling-backup-1: cron lines that name
nodian-*containers need the new names.POSTGRES_USER/POSTGRES_DBlines in.envare not read (they never
were); delete them. -
Migration 0059 adds
pages.share_allow_download boolean not null default false(a constant default:
metadata-only, no backfill, milliseconds). Existing links keep the download off. Going back to 0.18.0 after the
upgrade needed no restore in a check before onboarding was merged: the v0.18.0 image started on a database
migrated to 60 rows (0059 only), served a new share link and logged no error (a near-empty database, not a copy of
production). With 0060'suser_onboardingtable this was not checked again (KNOWN-ISSUES ONBOARD-5). A link that allowed downloads,
unpublished and published again while 0.18.0 runs, keeps the setting and offers the download again once 0.19 runs
(KNOWN-ISSUES SHARE-5). -
Migration 0060 adds
user_onboardingand gives every existing account a row{"legacy": true}(one
INSERT…SELECT overusers): people who already use Inkling are not shown the intro or the checklist after the
upgrade. They can open both from Settings › About (docs/adr/2380-*). -
New optional variables
ONBOARDING(empty = on,off= no intro, card or sample page for anyone) and
ONBOARDING_EXISTING_USERS(once= accounts from before the upgrade also see the intro once, on their next app
load; closing or skipping it is stored per person, so it does not come back after restarts, and unsetting the
variable later changes nothing for those who saw it; their checklist stays off and no sample page is made for
them). Accounts first seen whileONBOARDING=offcount as existing accounts if it is turned on later. Both are
passed through bycompose.yaml; recreate the container after changing them (docs/adr/2383-*), then check that
the value arrived:docker compose exec app printenv ONBOARDING_EXISTING_USERSprintsonce(an empty line means
unset). Withonce, an existing account that closes the tab while the intro is still playing (without Skip, Esc
or reaching the end) sees it again on its next app load; it counts as seen only once it is closed or finished.
Guests never get the intro. -
Templates with a database and an inline view of it: a custom template that contains a database and an
inline view (page embed) of that database now gives each new copy a view of its own copy; before, the view pointed
at the original database. This applies to "Start from template" in the app and toPOST /api/pages/from-template
(the MCPcreate_from_templatetool uses it); embeds of pages outside the template are kept as before
(docs/adr/2381-*). -
Markdown downloads of public pages link images and files with
PUBLIC_URL(APP_URLas fallback). Set it in
production; without it the request host is used, as for OAuth metadata. -
PATCH /api/pages/:id/shareacceptsallowDownload: boolean;POST /api/pages/:id/sharedoes not (strict body:
400 if sent). New audit actionshare.download_changed(before/after{ allowDownload }). -
Developers: the dev database moves to
inkling-db-1on the same port 55432; stop an oldnodian-db-1first and
drop anodianDATABASE_URLfrom your.env(CONTRIBUTING.md).
Added
deploy/rename-from-nodian.sh(--dry-run,--yes,--rollback) moves an install to the new names:
pre-rename backup (sidecar, orpg_dumpwhen there is none), row counts, a copy of every volume whose name
changes (the old ones are only read and never deleted), the role and database renamed inside the copy (the
password set again from.env, which covers MD5),.envswitched, then health, counts, files and a backup
checked under the new names. It continues where an interrupted run stopped, and--rollbackstarts the old
names again from any point. Downtime about a minute for a small server; needs free disk for a copy of the
volumes (docs/adr/2341-*).- Rename test:
scripts/upgrade-test/rename.shand arenamejob in.github/workflows/upgrade.yml(from
v0.17.1 and v0.18.0, by commit): an old release installed like a server, the upgrade refused without the new
line, the new release on the old names with its migrations (the journal may only grow), the rename (also
killed after the copy and after the role rename, and rolled back) leaving the journal as it was, and a new
install with no old name anywhere (docs/adr/2342-*). - Public links: Wide view. Pages follow their own "Full width" setting by default; a visitor's choice is
remembered in their browser. Tables, code, diagrams and the tables of charts, database views and query results
use the whole window; running text stops at a readable width (docs/adr/2360-*). - Public links: Save as PDF opens the browser's print dialog with the page title as the file name. The
printout is the article alone, always in the light palette, with wide tables wrapped to the paper, code wrapped,
toggles open, diagrams, formulas, images and checkboxes, without buttons or the folder list; the browser's own
Print command gives the same result (docs/adr/2361-*). - Public links: Download Markdown, per link and off by default. People who manage links turn it on in the
share dialog ("Let visitors download it as Markdown"); the file holds only what the public page shows
(docs/adr/2362-*). Changes are in the audit log as "Public link download changed". - Public page actions fold into one "⋯" menu on narrow screens, with keyboard support (docs/adr/2363-*).
- Onboarding for new accounts (docs/adr/2380-* .. 2382-). A new account sees a 26-second intro once (notes and
[[links]], databases and views, AI agents over MCP with suggestions and undo, your own server and offline), drawn
in code, skippable, pausable, keyboard and screen-reader friendly, still pictures with reduced motion. A
Getting started card on the empty workspace screen and, folded, at the bottom of the sidebar lists first steps
that tick themselves as you do them (first page,/menu,[[link, database, inviting or sharing, connecting an
AI agent, installing or offline; invited members get "look around the team workspace" and "leave a comment"
instead of the database and invite items). Each item takes you where it is done and points at the button. The
first admin of a new server gets a sample page in their private pages, in their language; anyone can make one
from the card. Settings › About: "Watch the intro again" and a switch for the checklist.ONBOARDING=offturns it
all off;ONBOARDING_EXISTING_USERS=onceshows the intro once to accounts from before the upgrade
(docs/adr/2383-). While a sample page is being made, its own pages do not tick "first page", "database" or
"link". In the sidebar the card opens only within the sidebar's height and scrolls inside when its list is
longer, so the menus, the page tree and the footer stay reachable (docs/adr/2384-*). The intro does not open by
itself over the "could not show this screen" notice; it waits for the next screen.
Changed
- The data plumbing is called
inkling, from one required setting. Up to 0.18 the compose project, the
volumes (nodian-db,nodian-data,nodian-backups,nodian-backup-ctl,nodian-rclone-bin), the database
role and the database were namednodian, the project's old name. They now followINKLING_DATA_NAMEin
.env:inklinggives projectinkling, volumesinkling_inkling-db,-data,-backups,-backup-ctl,
-rclone-bin, role and databaseinkling;nodiangives exactly the 0.18 names. The setting has no default,
so an install that upgrades without reading this cannot come up on new, empty volumes: compose refuses before it
creates or stops anything and says which line to add..env.examplesetsinkling(docs/adr/2340-*). deploy/signup-key.sh,deploy/reset-password.shanddeploy/cli-token.shread the role and database from
the db container instead of assumingnodian, so they work on old-name and new-name installs alike. The db
container now setsPGUSER/PGDATABASE:docker compose exec db psqlneeds no-U/-d.- Development:
pnpm db:upstartsinkling-db-1with role, password and databaseinkling; the default
DATABASE_URL(server, drizzle-kit, benches) ispostgres://inkling:inkling@localhost:55432/inkling. deploy/local.shwritesINKLING_DATA_NAME=inklingfor new trials and addsINKLING_DATA_NAME=nodianto the
.envof a trial started before 0.19, so it keeps its data.ShareStatusDTO.allowDownloadandPublicPageDTO.fullWidth/.downloadare new, additive fields; two new
public routes,GET /api/public/:token/export.mdandGET /api/public/:token/p/:ref/export.md
(docs/API.md, "v0.19.0 additions").- Templates: an inline database view (page embed) of a database inside the same template now points at the new copy
when the template is used (docs/adr/2381-*). - REST:
GET/PATCH /api/me/onboarding,POST /api/me/onboarding/sample, browser session only
(docs/API.md, "v0.19.0 additions"). Agents never see onboarding. - Not changed: MCP tool descriptions, the tool list and the server instructions (full 48 tools ~12,777 tokens, core
32 ~7,533).
Fixed
- A screen that cannot be drawn says so instead of going white. It shows "This screen could not be shown" with
a Reload button (and the error under Details) instead of a blank white tab. A page that fails keeps the sidebar,
and moving to another page tries again. A route chunk that still fails after the one automatic reload (server
restarting, flaky connection) ends there too, and a start whose script never ran shows a reload notice after 12 s
(docs/adr/2324-*). deploy/signup-key.sh newmakes a key that works at once. Since 0.5 the server compares signup keys by their
SHA-256 (docs/adr/1110-*), but the script still stored the key in plain text, so a key from the script was refused
("invalid or expired") until the next app restart hashed it. The script now stores the hash and the last four
characters like the admin screen does;listshows…ABCDfor such keys,revoketakes the full key for both
kinds. Found by the rename test's new-install step.- "More (n)" in the sidebar opens all n menus. On a window that is not full-screen the sidebar folds the menus
that do not fit under "More (n)"; opening it showed about one more row, and the rest scrolled inside a small box
with nothing that said so ("More (3)" opened one). The page tree now gives way while "More" is open (down to
120 px, with its own scroll), so every folded menu shows. On a very short window where even that is not enough,
the list scrolls in whole rows above a "k more below" row that scrolls it (docs/adr/1643-*). - Export as PDF prints wide tables, closed toggles and the dark theme properly. In the app's PDF export a
table with many columns lost its right-hand columns; the columns now share the page width (smaller type from
7 columns). Closed toggles and toggle headings print their contents. In the dark theme the body text printed
almost white on the white page; it prints in the light palette now (docs/adr/0308-*). - PDF export (app and public pages): a heading no longer ends up alone at the bottom of a page.
- Public pages: drawn Mermaid diagrams and formulas no longer turn back into source text when the page re-renders
(closing a presentation, the new width toggle). - Public pages: code blocks were white text on a light grey box; they follow the page palette now.
- Public pages: a table wider than the column scrolls inside its own box instead of running past the column (and
making phones scroll sideways). - Offline copies: a page no longer waits on "Connecting…" for a browser storage that never answers. When
indexedDB.opengave neither success nor error, a page waiting for its device copy stayed on "Connecting…"; after
5 s the device store now counts as unavailable and the page opens from the server. That tab then works without
device copies for the rest of its session, and Settings › Offline says the device storage is unavailable;
reloading the tab tries again. Turning offline copies off waits forindexedDB.deleteDatabase, which has no time
limit and was not tried on a stuck browser (KNOWN-ISSUES OFFLINE-11).
Performance
- Public page bundle (11d0707 → the share branch, before the other 0.19 changes): +822 B on the entry (i18n strings) and +6,278 B JS, +5,827 B CSS on the public page (≈ +3.4 KB
gzip in total) for the toolbar, the print styles shared with the app's PDF export and the view CSS
(docs/PERFORMANCE.md). - Screen notices and the IndexedDB open limit (dd933e5 → 5ee9f3a): entry
index-*.js+1,872 B (+553 B gzip), entry
plus modulepreload +2,852 B (+914 B gzip), precache +3,729 B (102 entries either way). - Onboarding (5ee9f3a → c6634d0): entry
index-*.js+3,223 B (+1,248 B gzip, most of it the en and ko strings),
entry plus modulepreload 26 → 27 files, +14,107 B (+5,619 B gzip), precache 102 → 104 entries, +25,262 B; the
intro is a lazy chunk (20.63 kB, 7.60 kB gzip, not precached) loaded only when it plays. Measured on the merged
tree with gzip -9 (docs/PERFORMANCE.md).
Database
- Migration 0059:
pages.share_allow_download boolean not null default false(docs/adr/2362-*). - Migration 0060:
user_onboarding(one row per account, deleted with the account) and a{"legacy": true}row for
every existing account (docs/adr/2380-*).