Storage modes

The fs setting in a project’s noemata.json determines where the deployment (the published revisions everyone reads) and the drafts (each user’s unpublished edits) are stored. See fs for the fields, and Publishing & fetching for how a draft becomes a revision.

fs.local

The project directory contains both the deployment and the draft. The server reads and writes the directory directly, stores the published revisions under .shared/deployment/, and never writes to ClickHouse. The deployment head and the workflow scheduler’s records are on disk too, under .data/coordination/, and an fs.local server refuses to start with coordination: { clickhouse_keeper: {} }. noemata init writes this mode for a new project, and it is the default when fs is not set. It suits an individual, or a team that uses git as the source of truth.

The server must run on the same host as the files.

fs.remote

The deployment is in the file store in ClickHouse, so several servers and checkouts can share it. The draft is one of two things:

• The user’s draft in the store (the default). The browser is the only client, and the server writes nothing to the project directory. Use this mode for a deployment that people read and edit through the app. Each user’s edits in the notebook and editor panels go to their own draft, layered over the published revision. An open browser shows a revision published through the same server, and draft changes made in another tab, immediately. It checks for changes made elsewhere every 10 seconds while you use it. While the tab is idle it checks less often, down to once every 5 minutes, and while the tab is hidden it does not check.
• The project directory, with disk: true. The local server serves the files on disk, reloads the browser when they change, and runs the agent panel in that directory. While the server runs, it writes each newly published revision to the files you haven’t changed, so your editor, the browser and the CLI read the same files. It checks for a new revision every 10 seconds while you work, and at least once a minute otherwise. When a revision changes a file that you also changed, your version stays on disk and the server logs the conflict. noemata publish sends your changes to the deployment, and noemata fetch writes the deployment’s changes to disk when no server is running. The draft on disk is not copied to the store, so the hosted app shows your changes only after you publish them.

noemata up --edit sets disk for one run and turns off workflow scheduling for that run. A checkout of a production config can then preview edits without running production workflows.

fs.remote requires coordination: { clickhouse_keeper: {} } and a standing identity: a service_account, hybrid, or anonymous principal. Without them, the server does not start, because the default local coordinator stores the deployment head and the workflow scheduler’s records on the instance’s disk. A managed ClickHouse binary configures Keeper coordination. With an external ClickHouse, set it in config/server/server.overrides.yml. Multi-tenant servers always use the local coordinator, so they cannot run fs.remote.