Operations

This page is for running Finia’s optional infrastructure and keeping data safe. For the design behind sync, see Architecture & Decisions.

Hosting the sync relay

The standalone relay lives in sync-server/ — an Axum binary with its own Cargo.toml, intended to be self-hosted. The simplest deployment is Docker:

cd sync-server
docker compose up -d

The relay is zero-knowledge: it stores and forwards encrypted event payloads and key bundles, but never holds the keys needed to read them. Losing the relay loses no plaintext; it only interrupts replication until it is back.

The relay is distinct from the embedded hub server that runs inside the desktop app. If one device acts as a hub, other devices can sync directly to it without a standalone relay at all. Run a standalone relay when you want an always-on meeting point independent of any single device.

Backups

The source of truth is each device’s local SQLite database. Because the relay only holds ciphertext, it is not a backup — a device that loses its data and its keys cannot recover plaintext from the relay alone.

Recommended practice:

  • Keep a periodic copy of each device’s SQLite database file.

  • Store the recovery code generated when encryption is enabled somewhere safe and offline — it is required to re-derive keys if a master passphrase is lost.

Key management

Finia holds two kinds of key material:

  • At-rest key — protects the encrypted secret columns in the local database. It lives in the OS keyring with a 0600 file fallback.

  • Sync data-encryption key (DEK) — protects sync payloads end-to-end, wrapped by the user’s master passphrase and exchanged via encrypted key bundles.

If key material is lost, the app reports that some credentials could not be decrypted and resets them; the sync token must be re-entered and E2EE re-unlocked. The database rows themselves survive — only the secrets protected by the lost key are affected.

Android caveat. On Android the OS keyring can silently fail to persist, so the master key may rotate on every reinstall — and likely every store update. When that happens, at-rest secrets and E2EE break for that device until the sync token is re-entered and encryption is re-unlocked. Durable Android key persistence is tracked work; until it lands, treat an Android reinstall as "re-enter the sync token and re-unlock E2EE".

Recovering a device

After a reinstall or a lost keyring:

  1. Reinstall or relaunch the app; the local database (if present) is intact.

  2. Re-enter the sync token under Settings → Synchronisierung.

  3. Unlock E2EE with the master passphrase (or the recovery code).

  4. Let the client pull; peer-created rows materialize as events are applied.