Synced Graphs
A synced graph lives on a Sync Server, so you can open it on every device you own, including phones, Safari and Firefox, which cannot open a local folder, and share it with other people who edit it with you in real time. It is end-to-end encrypted: everything is encrypted on your device before it is sent, and the server stores what it cannot read.
You need a Sync Server. EtherPK's managed service runs one for Sync+ subscribers, tied to an EtherPK Account; or you can run your own (Managed Sync Or Your Own Server). The Client is the same either way.
What the server can and cannot see
Everything content-derived is encrypted under a key only your devices hold: the notes, their titles, the graph's name, its settings, quick notes, favourites, images and files, and the cursors of people editing together. The server sees accounts, which accounts belong to which graphs, opaque ids, and ciphertext. It enforces storage limits by counting encrypted bytes it cannot read.
That protects your notes from the server and from whoever runs it. It does not protect them from your own unlocked device, or from the other members of a shared graph, who hold the same key. For those, see Protected Documents.
Connect a device
With EtherPK Managed Sync, opening the hosted Client while you are signed in to your EtherPK Account signs the Client in as well, selects the managed server and shows your account in the header. If you are not signed in, open Graphs > Sync settings, choose Managed Sync and select Continue to secure sign in. There is no address to type and no token to copy.
With a custom server:
- Sign in to that server's account portal and open Access tokens. Create a Personal Access Token, name it after the device ("My laptop"), and copy it. It is shown once.
- In EtherPK, open Graphs > Sync settings and choose Custom server.
- Enter the server's address (with its
https://or, for a server on your own machine,http://) and the token, then select Save custom server.
In both cases the credential lets the app sync and cannot decrypt anything. Once the server has confirmed it, the header shows your account's email, with a menu that reaches Graphs, Account, Access tokens and Disconnect this device.
Create a synced graph
On the Knowledge graphs page select New synced graph, give it a name and select Create graph. Every member you later invite sees the same name, and you can rename it at any time.
The first synced graph you create on an account also creates your encryption keys, and EtherPK shows you your Recovery Code before anything is uploaded. Save it and confirm; the graph is created once you have. See Recovery Code And Device Approval.
On the managed service, creating a synced graph needs Sync+. A Free account can still join graphs a subscriber shares with it (Your EtherPK Account).
The Synced graphs panel
Beneath the graphs on this device, the Knowledge graphs page lists every graph your account belongs to on the server, one card each:
- Its name, your role (Owner or Player), its id, and its storage in notes and assets. For a graph you own, the members and their roles.
- Not on this device when the graph has not been set up in this browser yet, with Add to this device. Names sync encrypted, and the server keeps a sealed copy of each name it cannot read, so a graph shows its real name here even before you open it, as long as your keys are unlocked. While they are locked the card says so instead.
- For an owner, Invite, Transfer ownership and Delete; for a player, Leave (Sharing A Graph).
Only graphs belonging to the signed-in account appear. Switching accounts on the same browser hides the previous account's graphs and unlocked keys until you switch back; local folder graphs stay visible.
Forget or delete
The cross on a graph's row under Graphs on this device forgets the graph on this device
only: its cached copy is removed, its notes stay on the server, and Add to this device brings
it back. Delete on the Synced graphs panel is different: it removes the graph from the
server for every member, permanently. You type DELETE to confirm, and the dialog says how many
other people lose access. A Local Mirror folder is not deleted with it.
Every device, live
Edits made on one device appear on the others as you type, and when someone else has the same document open you see their cursor. Each browser keeps a working copy of the graph so it opens quickly and keeps working when the connection drops: edits are saved to that copy and queued in an encrypted outbox, then delivered and merged, in the order you made them, when the connection returns.
Whether a device is "online" changes nothing about where your notes are: the server is always the master copy, and the browser's copy is a cache that can be rebuilt from it. Clearing the browser's site data can lose queued edits that have not reached the server yet, so check the graph is caught up before clearing data or retiring a device (Where Your Data Lives).
Disconnect this device, in the account menu or Sync settings, ends this Client's sync connection, locks its keys, hides its synced graphs and closes the open workspace. Reconnect and unlock to use them again; queued edits upload after that. Local folder graphs are a separate storage mode and are not affected.
Storage and limits
Each graph's card shows its storage on the server, split into notes and assets, and the panel's header totals the graphs you own. The notes figure counts encrypted data including the edit history that powers sync and co-editing. When enough history has built up, an idle device makes a compact snapshot and the server prunes history the snapshots cover, so the figure can fall after a while but does not shrink on every edit.
On the managed service a plan sets how many graphs you may own, how much storage they may use, how many players each may have and how large one file may be; Billing on the Account site shows the exact figures (Your EtherPK Account). A self-hosted server sets limits or none. Players use the owner's allowance, and joining a graph does not use one of your own slots.
A write that would pass a limit is refused with a message saying which limit and what to do, "You have reached your plan's storage allowance. Delete unused documents or assets, or move to a larger plan." for instance. The edit is not lost: it stays on the device and is retried once there is room.
Images and files
Images and files in a synced graph are encrypted on your device and sent straight to the server's storage bucket, in chunks; the bucket only ever holds ciphertext, and downloads need a signed address that expires. Images And Files has the access rules.
If the bucket is not configured to accept requests from the app's address, uploads fail with "Uploading to the storage bucket was blocked. The bucket's CORS policy must allow this app's origin" while notes keep syncing. That is a one-time setting for whoever runs the server (Self Hosting The Sync Server).
A readable copy on disk
A synced graph can keep a plain markdown copy of itself in a folder on one of your computers, kept up to date while the graph is open there: Keeping A Local Copy Of A Synced Graph.