diff --git a/docs/hub/access-vault.mdx b/docs/hub/access-vault.mdx
index e3ee6448..89bfa27e 100644
--- a/docs/hub/access-vault.mdx
+++ b/docs/hub/access-vault.mdx
@@ -1,7 +1,7 @@
---
id: access-vault
title: Working with Vaults
-sidebar_position: 6
+sidebar_position: 7
---
# Working with Vaults
@@ -21,29 +21,25 @@ As described in [open an existing vault](/docs/desktop/adding-vaults.mdx#open-an
To unlock the vault, click on the large `Unlock` button in the center of Cryptomator's main window.
-
+
### 2. Authenticate {/* #authenticate */}
Cryptomator should open your default browser for authentication. If you're not already logged in, you need to provide your user credentials, e.g., by entering your username and password or by inserting your key when WebAuthn is enabled.
-
+
### 3. Register Device {/* #register-device */}
-If you just setup your account, a vault owner needs to grant you access for the requested vault as described [here](vault-management.mdx#update-permissions). Retry unlocking the vault after the vault owner granted you access.
-
-
-
If you connect to Hub with this device for the first time, you need to register it.
Desktop
-
+
Hub
-
+
Enter a name for the device to identify it later on and the [Account Key](your-account.mdx#account-key) which was generated during the account setup. You can also find it in the [account settings](your-account.mdx#profile-page).
@@ -55,7 +51,7 @@ You are all set up and an unlock should be successful from now on. You can then
Desktop
-
+
Hub
diff --git a/docs/hub/admin.mdx b/docs/hub/admin.mdx
index 153e754b..b893147e 100644
--- a/docs/hub/admin.mdx
+++ b/docs/hub/admin.mdx
@@ -1,7 +1,7 @@
---
id: admin
title: Admin
-sidebar_position: 8
+sidebar_position: 9
---
# Admin
@@ -13,7 +13,7 @@ The license is bound to the instance and cannot be transferred to another instan
Every license has a number of seats and a validity period.
As an Hub administrator, you can view license information in the administration area.
-
+
### What Is a Seat? {/* #what-is-a-seat */}
@@ -106,7 +106,7 @@ The logs are displayed in a structured table containing the following columns:
- **Event** – The type of event that occurred.
- **Details** – Additional information about the event.
-
+
### Filtering Audit Logs {/* #filtering-audit-logs */}
@@ -149,17 +149,13 @@ Additionally, any existing trust chains that included the user will be broken, r
## Emergency Access {/* #emergency-access */}
-:::info[Early Access]
-Emergency Access is currently in **early access** and will be fully available in version 2.0.0.
-:::
-
:::info[Enterprise Feature]
Visit [cryptomator.org](https://cryptomator.org/hub/) for more information about Enterprise features.
:::
This configuration defines default [Emergency Access](emergency-access.mdx) values for new or updated vaults.
-
+
Activate `Enable Emergency Access` and configure:
diff --git a/docs/hub/deployment/_category_.json b/docs/hub/deployment/_category_.json
index 936ae645..40f66e57 100644
--- a/docs/hub/deployment/_category_.json
+++ b/docs/hub/deployment/_category_.json
@@ -1,6 +1,6 @@
{
"label": "Deployment Cookbook",
- "position": 12,
+ "position": 13,
"link": {
"type": "doc",
"id": "hub/deployment/index"
diff --git a/docs/hub/deployment/index.mdx b/docs/hub/deployment/index.mdx
index 2d75a68b..a1383745 100644
--- a/docs/hub/deployment/index.mdx
+++ b/docs/hub/deployment/index.mdx
@@ -6,7 +6,7 @@ import DocCardList from '@theme/DocCardList';
# Deployment Cookbook
-This section collects recipes for running Cryptomator Hub in production. If you just want to try Hub, start with the [Quick Start](../quick-start.mdx) instead.
+This section collects recipes for running Cryptomator Hub in production. If you just want to try Hub, start with the [Quick Start](../quick-start.mdx) instead. For an end-to-end walkthrough from deployment to backups, see the [Self-Hosting Guide](../guides/self-hosting-guide.mdx).
:::tip
Cryptomator Hub is also offered as a hosted solution, including 99.5%-uptime guarantee and regular backups! Visit [cryptomator.org](https://cryptomator.org/for-teams/) for more information.
diff --git a/docs/hub/early-access.mdx b/docs/hub/early-access.mdx
deleted file mode 100644
index 4f7406f8..00000000
--- a/docs/hub/early-access.mdx
+++ /dev/null
@@ -1,12 +0,0 @@
----
-id: early-access
-title: Early Access
-sidebar_position: 10
----
-
-# Early Access
-
-These features are currently in **early access** and will be fully available in **Cryptomator Hub 2.0.0**.
-
-- [User & Group Management](/hub/user-group-management) — Manage users, groups, roles, and permissions directly in Hub
-- [Emergency Access](/hub/emergency-access) — Restore access to a vault in case of account loss or ownership issues
diff --git a/docs/hub/emergency-access.mdx b/docs/hub/emergency-access.mdx
index 8dbd63a5..98b35597 100644
--- a/docs/hub/emergency-access.mdx
+++ b/docs/hub/emergency-access.mdx
@@ -1,15 +1,11 @@
---
id: emergency-access
title: Emergency Access
-sidebar_position: 9
+sidebar_position: 10
---
# Emergency Access
-:::info[Early Access]
-This feature is currently in **early access** and will be fully available in version 2.0.0.
-:::
-
:::info[Enterprise Feature]
Visit [cryptomator.org](https://cryptomator.org/hub/) for more information about Enterprise features.
:::
@@ -19,7 +15,7 @@ Its process requires a group of trusted users (the "council") to approve the rec
When enough approvals are collected, the emergency change is completed and vault management access is restored.
Technically, this is implemented using key splitting based on **[Shamir's Secret Sharing](https://en.wikipedia.org/wiki/Shamir%27s_secret_sharing)**.
-## Set Up Emergency Access
+## Set Up Emergency Access {/* #set-up-emergency-access */}
The feature can be activated for new and existing vaults:
@@ -27,11 +23,11 @@ The feature can be activated for new and existing vaults:
For the full workflow, see [Vault Management](vault-management.mdx#create-a-vault).
* **Existing vaults:** Open `Vault Details` and [configure Emergency Access](vault-management.mdx#emergency-access-council).
-## Starting a Recovery Process
+## Starting a Recovery Process {/* #starting-a-recovery-process */}
To start, open the `Emergency Access` page, select the vault, and start the desired process.
-
+
There are two process types:
@@ -56,30 +52,30 @@ Starting a process automatically approves the process.
:::
-### Choose Vault Members
+### Choose Vault Members {/* #choose-vault-members */}
The `Choose Vault Members` process allows you to select new vault `Owners` or `Members`.
Users that are no longer part of the vault are shown as `Removed`.
-
+
-### Change Emergency Access Council
+### Change Emergency Access Council {/* #change-emergency-access-council */}
The `Change Emergency Access Council` process allows you to select a new council.
The minimum required number of members is configured in the [Admin settings](admin.mdx#emergency-access).
-
+
-## Approve a Recovery Process
+## Approve a Recovery Process {/* #approve-a-recovery-process */}
To view or approve running Emergency Access processes, open the `Emergency Access` list.
If an Emergency Access process is running for a vault, the vault is displayed with a process button.
If you haven't approved the process, the button includes `Approve now`.
-
+
Approve a running process in three steps:
@@ -87,7 +83,7 @@ Approve a running process in three steps:
2. Click `Approve now` to open the `Approve Emergency Access` dialog.
3. Review the details and click `Approve`.
-
+
After submitting your share, the button shows `Waiting for other approvals`. You can track the ongoing process progress in the same process button and its details popover.
@@ -99,17 +95,17 @@ You can also inspect details before approving. Hover (or click) the segment ring
* process council members
* per-member status (`Added` / `Pending`)
-
+
-## Complete a Recovery Process
+## Complete a Recovery Process {/* #complete-a-recovery-process */}
As soon as enough shares are available, the process button in the `Emergency Access` vault list shows `Complete now`.
-
+
Click `Complete now` to open the `Complete Emergency Access` dialog. In this dialog, review the process details and click `Complete Process` to finalize the recovery process.
-
+
Results by type:
@@ -118,14 +114,14 @@ Results by type:
After successful completion, the process is removed.
-## Abort a Recovery Process
+## Abort a Recovery Process {/* #abort-a-recovery-process */}
Running processes can be canceled in the dialog using `Abort this Process`.
-
+
-## Typical States and Notes
+## Typical States and Notes {/* #typical-states-and-notes */}
The following warning states can appear in the Emergency Access list:
@@ -136,6 +132,6 @@ The following warning states can appear in the Emergency Access list:
* `No Redundancy`: No fault tolerance in the council.
What to do: Increase the number of council members or reduce the required threshold so one unavailable user does not block recovery.
-## Audit Log Events
+## Audit Log Events {/* #audit-log-events */}
See [Emergency Access Audit Log events](admin.mdx#event-type-emergency-access).
diff --git a/docs/hub/guides/_category_.json b/docs/hub/guides/_category_.json
new file mode 100644
index 00000000..4d6588d4
--- /dev/null
+++ b/docs/hub/guides/_category_.json
@@ -0,0 +1,8 @@
+{
+ "label": "Guides",
+ "position": 3,
+ "link": {
+ "type": "doc",
+ "id": "hub/guides/index"
+ }
+}
diff --git a/docs/hub/guides/admin-guide.mdx b/docs/hub/guides/admin-guide.mdx
new file mode 100644
index 00000000..3440d6ca
--- /dev/null
+++ b/docs/hub/guides/admin-guide.mdx
@@ -0,0 +1,96 @@
+---
+id: admin-guide
+title: Admin Guide
+sidebar_position: 2
+description: Your first day as a Hub administrator — add users and groups, connect your identity provider, enable Emergency Access, and keep an eye on audit logs and license seats.
+---
+
+# Admin Guide
+
+This guide walks you through setting up a fresh Cryptomator Hub instance for your organization in about **20 minutes**.
+
+As a worked example, meet Alice: she administers Hub at the design agency Acme.
+Her instance is up and running, and now she adds her first users and a group, connects the company's identity provider, enables Emergency Access, and checks the audit log and license.
+
+## Before You Start {/* #before-you-start */}
+
+You need:
+
+* A running Hub instance — a local test instance from the [Quick Start](../quick-start.mdx) or a server deployment (managed or selfhosted)
+* An account with the `admin` [role](../user-group-management.mdx#roles), such as the initial admin account created during deployment.
+
+:::tip
+Not keen on hosting an instance yourself? Cryptomator Hub is also available as a [managed service](https://cryptomator.org/hub/managed/?utm_source=docs.cryptomator.org&utm_medium=referral&utm_campaign=admin-guide) with a free 30-day trial period — this guide applies there all the same.
+:::
+
+## Add Users and Groups {/* #add-users-and-groups */}
+
+Since version 2.0, users and groups are managed directly in Hub, via the `Users` and `Groups` entries in the sidebar.
+Alice creates accounts for Bob and Carol, each with username, email, and an initial password.
+She then creates the group *Designers* and adds both as members — sharing vaults with a group scales better than managing individual permissions.
+
+
+
+Bob and Carol can now log in and complete their account setup, as described in the [User Guide](user-guide.mdx#set-up-your-account).
+
+For more details, read [Create User](../user-group-management.mdx#create-user), [Create Group](../user-group-management.mdx#create-group), and [Manage Group Members](../user-group-management.mdx#manage-group-members).
+
+## Connect Your Identity Provider {/* #connect-your-identity-provider */}
+
+Creating users by hand is fine for a handful of people.
+Since Acme already manages its staff in a central directory, Alice instead connects Hub's bundled Keycloak to it, so users log in with their existing credentials and accounts stay in sync.
+
+
+
+The `Manage Keycloak` link takes Alice to the Keycloak admin console, where identity providers are configured on the `Identity providers` page:
+
+
+
+Depending on what your organization runs, follow the matching reference section:
+
+* [OpenID Connect](../keycloak.mdx#openid-connect) providers such as Microsoft Entra ID or Google Workspace.
+* [LDAP and Active Directory](../keycloak.mdx#ldap-and-active-directory) for user federation.
+* [Mapping groups to roles](../keycloak.mdx#mapping-groups-to-roles), e.g. to grant an *IT* directory group the `admin` role automatically.
+
+For more details, read [Connecting an External Identity Provider](../keycloak.mdx#connecting-an-external-identity-provider) and [External Identity Management](../user-group-management.mdx#enterprise-external-iam).
+
+## Enable Emergency Access {/* #enable-emergency-access */}
+
+What if Bob leaves Acme and the *Client Projects* vault has no other owner?
+Emergency Access, new in version 2.0, lets a council of trusted users jointly restore access to a vault.
+Alice enables it in the admin area and defines a default council, so every new vault gets Emergency Access conditions during creation.
+For existing vaults, owners set up the council in the vault details.
+
+
+
+:::info[Enterprise Feature]
+Emergency Access is available as an Enterprise feature.
+Visit [cryptomator.org](https://cryptomator.org/hub/) for more information.
+:::
+
+For more details, read [Emergency Access admin settings](../admin.mdx#emergency-access), [Set Up Emergency Access](../emergency-access.mdx#set-up-emergency-access), and the per-vault [Emergency Access Council](../vault-management.mdx#emergency-access-council).
+
+## Review the Audit Log {/* #review-the-audit-log */}
+
+The next morning, Alice verifies that everything went as intended.
+In the audit log, she filters for vault events and sees the creation of *Client Projects* and the access grants for Carol and the *Designers* group, each with actor and timestamp.
+
+
+
+For more details, read [Audit Logs](../admin.mdx#audit-logs), [Filtering Audit Logs](../admin.mdx#filtering-audit-logs), and the list of [Event Types](../admin.mdx#event-types).
+
+## Check Your License {/* #check-your-license */}
+
+Finally, Alice opens the license section of the admin area.
+With Bob and Carol having vault access, two seats are in use — a seat is occupied by every user who is assigned to at least one vault.
+The overview shows the used and licensed seats and where to upgrade before the team grows.
+
+
+
+For more details, read [License](../admin.mdx#license), [What Is a Seat?](../admin.mdx#what-is-a-seat), and [Updating Your License](../admin.mdx#updating-your-license).
+
+## Next Steps {/* #next-steps */}
+
+* Set up [backups](../operations.mdx#backup) before real data accumulates.
+* Harden logins with [session timeouts](../keycloak.mdx#session-timeouts) and [access restrictions](../keycloak.mdx#restricting-access-to-hub).
+* Send your team the [User Guide](user-guide.mdx) so they can get started on their own.
diff --git a/docs/hub/guides/index.mdx b/docs/hub/guides/index.mdx
new file mode 100644
index 00000000..aa38509a
--- /dev/null
+++ b/docs/hub/guides/index.mdx
@@ -0,0 +1,8 @@
+import DocCardList from '@theme/DocCardList';
+
+# Guides
+
+Step-by-step walkthroughs for the most common Cryptomator Hub workflows.
+Each guide follows a worked example from start to finish and links to the reference pages for details.
+
+
diff --git a/docs/hub/guides/self-hosting-guide.mdx b/docs/hub/guides/self-hosting-guide.mdx
new file mode 100644
index 00000000..401f24ce
--- /dev/null
+++ b/docs/hub/guides/self-hosting-guide.mdx
@@ -0,0 +1,70 @@
+---
+id: self-hosting-guide
+title: Self-Hosting Guide
+sidebar_position: 3
+description: Take Hub from a local playground to a production deployment — pick a recipe, deploy, set up backups, and keep the instance healthy.
+---
+
+# Self-Hosting Guide
+
+This guide takes you from trying Cryptomator Hub to running it in production for your organization.
+It sequences the existing [Deployment Cookbook](../deployment/index.mdx) and [Operations](../operations.mdx) references into one path; how long it takes depends mostly on your infrastructure — plan for **an hour** plus DNS.
+
+As a worked example, meet Alice: she liked the [Quick Start](../quick-start.mdx) playground and now deploys Hub for the design agency Acme, a team of about 20 people.
+
+:::tip
+Not keen on running Hub yourself? We also offer Hub as a [managed service](https://cryptomator.org/hub/managed/?utm_source=docs.cryptomator.org&utm_medium=referral&utm_campaign=self-hosting-guide) with uptime guarantee and regular backups.
+:::
+
+## Before You Start {/* #before-you-start */}
+
+Decide on these up front — they are hard to change later:
+
+* Two public URLs, one for Hub and one for Keycloak, with DNS records created before deploying.
+* TLS termination via a reverse proxy or ingress controller — Hub, Keycloak, and PostgreSQL must never be exposed directly.
+* Whether to run the bundled Keycloak and PostgreSQL or connect existing instances.
+
+The defaults are sized for small installations like Acme's; see [Sizing](../deployment/index.mdx#sizing) for larger teams.
+
+For more details, read [Before You Begin](../deployment/index.mdx#before-you-begin) — including why the public URLs must be final before the first start.
+
+## Choose a Recipe {/* #choose-a-recipe */}
+
+The [Deployment Cookbook](../deployment/index.mdx#recipes) offers three recipes:
+
+* [Docker Compose](../deployment/compose.mdx) — a single Docker host behind a Traefik reverse proxy with Let's Encrypt. The simplest production setup.
+* [Kubernetes](../deployment/kubernetes.mdx) — the Helm chart via the Helm CLI, for teams that already operate a cluster.
+* [Rancher](../deployment/rancher.mdx) — the same Helm chart installed through the Rancher UI.
+
+Acme has no Kubernetes cluster and 20 users fit comfortably on one virtual machine, so Alice picks Docker Compose.
+The rest of this guide follows that path.
+
+## Deploy with Docker Compose {/* #deploy-with-docker-compose */}
+
+Alice provisions a VM with Docker, points the two DNS records at it, and opens ports 80 and 443.
+She downloads the production Compose example, replaces the placeholders — hostnames, Let's Encrypt email, and freshly generated passwords and secrets — and starts the stack with `docker compose up -d`.
+Once all services are healthy, she signs in as `admin`, enters the license, and Hub is live at Acme's own domain.
+
+For more details, read [Prerequisites](../deployment/compose.mdx#compose-prerequisites), [Deploy](../deployment/compose.mdx#compose-deploy), and [Configuration](../deployment/compose.mdx#compose-configuration) — including which ports must never be published.
+
+## Set Up Backups {/* #set-up-backups */}
+
+All of Hub's state lives in PostgreSQL: vaults, encrypted keys, and the audit log in the `hub` database, users and credentials in the `keycloak` database.
+Alice schedules a nightly `pg_dumpall` via cron and moves the dumps off the VM.
+Then she does what most people skip: she [restores](../operations.mdx#restore) one dump onto a scratch instance to confirm the backup actually works — a backup that has never been restored is a hope, not a backup.
+
+For more details, read [Backup](../operations.mdx#backup) and [Restore](../operations.mdx#restore).
+
+## Keep It Healthy {/* #keep-it-healthy */}
+
+Running Hub is low-maintenance; these are the recurring and occasional tasks:
+
+* [Upgrading](../deployment/compose.mdx#compose-upgrading) — back up first, bump the pinned image tags, `docker compose up -d`.
+* [Verifying container images](../operations.mdx#verifying-container-images) before deploying new versions.
+* [Trusting a private certificate authority](../operations.mdx#trusting-a-private-certificate-authority) if your organization uses one.
+* [Changing the database password](../operations.mdx#changing-the-database-password) as part of credential rotation.
+
+## Next Steps {/* #next-steps */}
+
+* The instance is running, but empty — continue with the [Admin Guide](admin-guide.mdx) to add users, groups, and your identity provider.
+* Bookmark [Operations](../operations.mdx) as the reference for everything maintenance.
diff --git a/docs/hub/guides/user-guide.mdx b/docs/hub/guides/user-guide.mdx
new file mode 100644
index 00000000..2cba7752
--- /dev/null
+++ b/docs/hub/guides/user-guide.mdx
@@ -0,0 +1,79 @@
+---
+id: user-guide
+title: User Guide
+sidebar_position: 1
+description: From your first login to an unlocked vault — set up your account, create a vault, invite teammates, and unlock it with Cryptomator.
+---
+
+# User Guide
+
+This guide walks you through your first steps in Cryptomator Hub, from logging in for the first time to working with an unlocked vault, in about **15 minutes**.
+
+As a worked example, meet Bob: he just joined the design agency Acme, and his administrator Alice sent him the Hub URL and his login credentials.
+Bob will set up his account, create a vault called *Client Projects*, share it with his colleague Carol and the *Designers* group, and unlock it with the Cryptomator desktop app.
+
+## Before You Start {/* #before-you-start */}
+
+You need:
+
+* The URL of your organization's Hub instance and login credentials, both provided by your administrator.
+* The [Cryptomator app](https://cryptomator.org/downloads/?utm_source=docs.cryptomator.org&utm_medium=referral&utm_campaign=user-guide) for your OS. This guide uses the desktop app; Android and iOS work analogously, see [Working with Vaults](../access-vault.mdx).
+* The `create-vaults` role to create a vault yourself. If the `Add` button in the vault list stays grayed out for you, ask your administrator for the [role](../user-group-management.mdx#roles) — or skip that section and continue with a vault someone shared with you.
+
+## Set Up Your Account {/* #set-up-your-account */}
+
+Bob opens the Hub URL, logs in with his credentials, and Hub greets him with a one-time account setup.
+
+
+
+The setup generates his personal *Account Key*.
+It is what links further browsers and Cryptomator apps to his account later, so he copies it into his password manager before finishing the setup.
+
+After finishing the setup, Bob lands on the vault list — Acme's is still empty.
+The `Add` button in the top right corner is the starting point for the next section: `Create New` opens the vault creation wizard.
+
+
+
+For more details, read [Account Setup](../your-account.mdx#account-setup) and [Account Key](../your-account.mdx#account-key).
+
+## Create a Vault {/* #create-a-vault */}
+
+Time for the first vault:
+
+1. In the vault list, Bob clicks `Add` → `Create New` and names the vault *Client Projects*.
+2. He follows the creation wizard and stores the displayed recovery key in his password manager — it restores access to the vault data if Hub is ever unavailable.
+3. In the last step, he downloads the vault template (a zip file, exactly once) and unzips it into the cloud storage folder the team already shares.
+
+
+
+For more details, read [Create a Vault](../vault-management.mdx#create-a-vault), [Show Recovery Key](../vault-management.mdx#show-recovery-key), and [Download Vault Template](../vault-management.mdx#download-vault-template).
+
+## Add Members {/* #add-members */}
+
+The vault is Bob's alone so far.
+In the vault details, he clicks into the search field of the `Shared with` section, picks Carol, and clicks `Add`.
+He then adds the *Designers* group the same way, so future team members get access automatically through their group membership.
+
+
+
+:::note
+When a member completes their account setup (or resets their account), a vault owner has to confirm the access once via the `Update Permissions` button before that member can unlock the vault.
+:::
+
+For more details, read [Share a Vault](../vault-management.mdx#share-a-vault), [Update Permissions](../vault-management.mdx#update-permissions), and [Web of Trust](../vault-management.mdx#web-of-trust) for verifying the identity of vault members.
+
+## Unlock the Vault {/* #unlock-the-vault */}
+
+To work with the encrypted data, Bob opens the Cryptomator desktop app, adds the vault by selecting the `vault.cryptomator` file from the shared cloud folder, and clicks `Unlock`.
+His browser opens for authentication, and since this is the first unlock from this device, Hub asks him to register it with a device name and his Account Key.
+After that, the vault unlocks, and Bob can reveal and edit the *Client Projects* files as usual.
+
+
+
+For more details, read [Unlocking a Vault](../access-vault.mdx#unlocking-a-vault), in particular [Register Device](../access-vault.mdx#register-device).
+
+## Next Steps {/* #next-steps */}
+
+* Lost access to a vault or Hub itself? See [Vault Recovery](../vault-recovery.mdx).
+* Review and revoke your registered browsers and apps under [Authorized Devices](../your-account.mdx#authorized-devices).
+* Curious how the zero-knowledge key management works? Read the [security architecture](/docs/security/hub.mdx).
diff --git a/docs/hub/introduction.mdx b/docs/hub/introduction.mdx
index 143f292c..041f79c1 100644
--- a/docs/hub/introduction.mdx
+++ b/docs/hub/introduction.mdx
@@ -18,6 +18,8 @@ If you are…
…an **administrator**:
* [Quick Start](quick-start.mdx) - how to try Cryptomator Hub on your machine.
+* [Admin Guide](guides/admin-guide.mdx) - a walkthrough of your first day as a Hub administrator.
+* [Self-Hosting Guide](guides/self-hosting-guide.mdx) - a walkthrough from playground to production deployment.
* [User & Group management](user-group-management.mdx) - how to manage users and groups.
* [License](admin.mdx#license) - how to manage your Hub license.
* [Deployment Cookbook](deployment/index.mdx) - how to deploy Cryptomator Hub for your team.
@@ -25,6 +27,7 @@ If you are…
…a **user**:
+* [User Guide](guides/user-guide.mdx) - a walkthrough from your first login to an unlocked vault.
* [Your Account](your-account.mdx) - how to manage your own account.
* [Managing Vaults](vault-management.mdx) - how to manage vaults.
* [Working with Vaults](access-vault.mdx) - how to use Hub vaults with Cryptomator apps to encrypt your data.
diff --git a/docs/hub/keycloak.mdx b/docs/hub/keycloak.mdx
index ebbb677e..e2dc0538 100644
--- a/docs/hub/keycloak.mdx
+++ b/docs/hub/keycloak.mdx
@@ -1,7 +1,7 @@
---
id: keycloak
title: Keycloak
-sidebar_position: 11
+sidebar_position: 12
---
# Keycloak
@@ -10,12 +10,6 @@ Cryptomator Hub delegates authentication and user management to [Keycloak](https
This page describes the Keycloak configuration tasks that are specific to running Hub. For everything else, refer to the [Keycloak documentation](https://www.keycloak.org/documentation).
-:::info[Enterprise Feature]
-Connecting external identity and access management (IAM) solutions is available as an Enterprise feature.
-
-Visit [cryptomator.org](https://cryptomator.org/hub/) for more information about Enterprise features.
-:::
-
## Connecting an External Identity Provider {/* #connecting-an-external-identity-provider */}
You can connect Hub to your existing identity provider so that users authenticate with the credentials they already have. Keycloak supports two fundamentally different approaches, and the choice affects when users become visible in Hub.
diff --git a/docs/hub/new-features.mdx b/docs/hub/new-features.mdx
new file mode 100644
index 00000000..a39b929a
--- /dev/null
+++ b/docs/hub/new-features.mdx
@@ -0,0 +1,14 @@
+---
+id: new-features
+title: New Features
+sidebar_position: 11
+---
+
+# New Features
+
+**Cryptomator Hub 2.0.0** introduces the following new features:
+
+- [User & Group Management](/hub/user-group-management) — Manage users, groups, roles, and permissions directly in Hub
+- [Emergency Access](/hub/emergency-access) — Restore access to a vault in case of account loss or ownership issues
+
+The [Admin Guide](guides/admin-guide.mdx) walks through both features in a worked example: see [Add Users and Groups](guides/admin-guide.mdx#add-users-and-groups) and [Enable Emergency Access](guides/admin-guide.mdx#enable-emergency-access).
diff --git a/docs/hub/operations.mdx b/docs/hub/operations.mdx
index 0e8d36e8..459950cc 100644
--- a/docs/hub/operations.mdx
+++ b/docs/hub/operations.mdx
@@ -1,11 +1,11 @@
---
title: Operations
-sidebar_position: 13
+sidebar_position: 14
---
# Operations
-All state of Cryptomator Hub lives in the PostgreSQL database: the `hub` database holds vaults, keys, and the audit log, the `keycloak` database holds users, groups, and credentials. Back up both, and always do so before upgrading.
+All state of Cryptomator Hub lives in the PostgreSQL database: the `hub` database holds vaults, keys, and the audit log, the `keycloak` database holds users, groups, and credentials. Back up both, and always do so before upgrading. For an end-to-end walkthrough from deployment to backups, see the [Self-Hosting Guide](guides/self-hosting-guide.mdx).
## Backup {/* #backup */}
diff --git a/docs/hub/quick-start.mdx b/docs/hub/quick-start.mdx
index ce6031d8..63d3c454 100644
--- a/docs/hub/quick-start.mdx
+++ b/docs/hub/quick-start.mdx
@@ -10,10 +10,6 @@ Want to see Cryptomator Hub in action before rolling it out to your team? This g
What you end up with is a playground, not a production system. It only listens on `localhost`, uses plain HTTP, and comes with default passwords. When you are ready for the real thing, head over to the [Deployment Cookbook](deployment/index.mdx).
-:::tip
-Not keen on running Hub yourself at all? We also offer Hub as a [managed service](https://cryptomator.org/for-teams/).
-:::
-
## Before You Start {/* #before-you-start */}
You need:
@@ -51,7 +47,7 @@ Hub greets you with a short onboarding on your first login:
1. **Choose a license.** For a local test, the *free trial* is what you want. You can claim it as often as you like. There are further free options for perpetual use on production installations as well.
1. **Save your Account Key.** Hub generates an [Account Key](your-account.mdx#account-key) in your browser. It's what you use to link further devices (browsers and Cryptomator apps) to your account, so keep it somewhere safe.
-That's it, you are in. Try [creating a vault](vault-management.mdx#create-a-vault), [adding a user](user-group-management.mdx#create-user), or [unlocking the vault](access-vault.mdx) from the Cryptomator desktop app with `http://localhost:8080` as the Hub address.
+That's it, you are in. Try [creating a vault](vault-management.mdx#create-a-vault), [adding a user](user-group-management.mdx#create-user), or [unlocking the vault](access-vault.mdx) from the Cryptomator desktop app. The [User Guide](guides/user-guide.mdx) and [Admin Guide](guides/admin-guide.mdx) walk you through these tasks using complete worked examples.
## Clean Up {/* #clean-up */}
@@ -69,4 +65,11 @@ docker compose down -v
## Next Steps {/* #next-steps */}
-Liked what you saw? Deploying Hub for your team requires a public address, TLS, and a plan for backups. The [Deployment Cookbook](deployment/index.mdx) guide covers all of that.
+Liked what you saw? Here is where to go next:
+
+* Deploy Hub for real — the [Self-Hosting Guide](guides/self-hosting-guide.mdx) takes you from this playground to a production deployment, and the [Deployment Cookbook](deployment/index.mdx) has the detailed recipes.
+:::tip
+Not keen on running Hub yourself at all? We also offer Hub as a [managed service](https://cryptomator.org/hub/managed/?utm_source=docs.cryptomator.org&utm_medium=referral&utm_campaign=quick-start) — including custom domain name, a 99.5%-uptime guarantee and regular backups.
+:::
+* Set up your organization — the [Admin Guide](guides/admin-guide.mdx) walks through users, groups, identity providers, and more.
+
diff --git a/docs/hub/user-group-management.mdx b/docs/hub/user-group-management.mdx
index 590d1514..ae9c94d9 100644
--- a/docs/hub/user-group-management.mdx
+++ b/docs/hub/user-group-management.mdx
@@ -1,15 +1,11 @@
---
id: user-group-management
title: User & Group Management
-sidebar_position: 3
+sidebar_position: 4
---
# User & Group Management
-:::info[Early Access]
-This feature is currently in **early access** and will be fully available in version 2.0.0.
-:::
-
Users and groups are managed directly in the Cryptomator Hub admin interface. As an administrator, you can create, edit, and delete users and groups, assign roles, and manage group memberships.
Access the user and group management from the navigation bar in the admin area.
@@ -24,7 +20,10 @@ The user list displays all users in your Hub instance. You can search for users
- Number of **group** memberships
- Number of registered **devices**
-
+
+
+
+
### Create User {/* #create-user */}
@@ -38,10 +37,23 @@ To create a new user, click the "Create User" button in the user list. Fill in t
- **Roles**: Assign roles to the user (see [Roles](#roles))
- **Password**: Set an initial password for the user
-
+
After creation, the user can log in with their credentials and complete the [account setup](your-account.mdx#account-setup).
+### User Details {/* #user-details */}
+
+The user detail page shows comprehensive information about a user:
+
+- **Groups**: All groups the user is a member of
+- **Accessible Vaults**: Vaults the user has access to (directly or through group membership)
+- **Devices**: All registered devices of the user
+- **Legacy Devices**: Devices registered with older Hub versions (see [Legacy Devices](your-account.mdx#legacy-devices))
+
+
+
+
+
### Edit User {/* #edit-user */}
To edit a user, navigate to the user's detail page and click "Edit". You can modify:
@@ -69,17 +81,6 @@ To delete a user, you can either click the delete button in the user list or nav
This action cannot be undone.
:::
-### User Details {/* #user-details */}
-
-The user detail page shows comprehensive information about a user:
-
-- **Groups**: All groups the user is a member of
-- **Accessible Vaults**: Vaults the user has access to (directly or through group membership)
-- **Devices**: All registered devices of the user
-- **Legacy Devices**: Devices registered with older Hub versions (see [Legacy Devices](your-account.mdx#legacy-devices))
-
-
-
## Group Management {/* #group-management */}
Groups allow you to organize users and grant vault access to multiple users at once.
@@ -91,7 +92,9 @@ The group list displays all groups with:
- Number of **members**
- Number of accessible **vaults**
-
+
+
+
### Create Group {/* #create-group */}
@@ -100,7 +103,8 @@ To create a new group, click the "Create Group" button. Fill in:
- **Profile Picture URL**: Optional URL to a group picture
- **Name**: A descriptive name for the group
-
+
+
### Edit Group {/* #edit-group */}
@@ -124,7 +128,8 @@ The group detail page shows:
- **Members**: All users who are members of this group
- **Accessible Vaults**: Vaults the group has access to
-
+
+
### Manage Group Members {/* #manage-group-members */}
@@ -133,10 +138,11 @@ From the group detail page, you can:
- **Add Members**: Click "Add Member" to search for and add users to the group
- **Remove Members**: Click the remove button next to a member to remove them from the group
-
+
+
:::note
-Subgroups are not supported at this time.
+Subgroups are not supported.
:::
## Roles {/* #roles */}
@@ -146,15 +152,11 @@ There are three roles in Cryptomator Hub:
| Role | Description |
|------|-------------|
| **user** | Default role. Can open vaults and manage their own account. |
-| **admin** | Can manage users and groups, view audit logs, and create vaults. |
-| **create-vault** | Allows users to create new vaults. Inherited by the admin role. |
+| **admin** | Can manage users and groups and view audit logs. |
+| **create-vault** | Allows users to create new vaults. |
Roles are assigned when creating or editing a user. The `user` role is assigned by default to all users.
-### Create Vault Role {/* #create-vault-role */}
-
-By default, only users with the `admin` role can create vaults. To allow other users to create vaults, assign the `create-vault` role to them when creating or editing the user.
-
## User Avatars {/* #user-avatars */}
Users can have profile pictures displayed throughout Hub (e.g., in vault member lists). As an administrator, you can set the profile picture URL when creating or editing a user.
@@ -165,14 +167,6 @@ If no profile picture is set, a generated avatar based on the user's name will b
## External Identity Management {/* #enterprise-external-iam */}
-:::info[Enterprise Feature]
-Connecting external identity and access management (IAM) solutions is available as an Enterprise feature.
-
-Visit [cryptomator.org](https://cryptomator.org/hub/) for more information about Enterprise features.
-:::
-
-
-
Connecting Cryptomator Hub to an external identity manager allows you to:
- Synchronize users and groups from LDAP or Active Directory
@@ -184,6 +178,8 @@ You can access the Keycloak management interface from the admin section of Hub.
[deleting users](https://www.keycloak.org/docs/latest/server_admin/index.html#proc-deleting-user_server_administration_guide) or
[managing groups](https://www.keycloak.org/docs/latest/server_admin/index.html#proc-managing-groups_server_administration_guide).
+
+
Setting up LDAP synchronization is described in the [Keycloak documentation](https://www.keycloak.org/docs/latest/server_admin/#_ldap).
For OpenID Connect and SAML, the Keycloak documentation provides [general information](https://www.keycloak.org/docs/latest/server_admin/#_identity_broker).
diff --git a/docs/hub/vault-management.mdx b/docs/hub/vault-management.mdx
index 12a8568d..8ad1dcec 100644
--- a/docs/hub/vault-management.mdx
+++ b/docs/hub/vault-management.mdx
@@ -1,7 +1,7 @@
---
id: vault-management
title: Vault Management
-sidebar_position: 5
+sidebar_position: 6
---
# Vault Management
@@ -18,14 +18,14 @@ Here, all vaults which are shared with you, are listed.
After signing in, Hub redirects you to this list.
Alternatively, you can also access the list by clicking on the `Vaults` tab in the navigation bar.
-
+
:::note
* As a user, you will only see the vaults that you have access to.
* As an admin of the Hub instance, you can see all vaults, but you can only access those that you have been granted access to.
:::
-:::note[Emergency Access Status in Vault List (Enterprise only, early access)]
+:::note[Emergency Access Status in Vault List (Enterprise only)]
In the `Vault List`, owners can see the Emergency Access status directly via badges:
* `Council missing`: No council is configured for the vault
@@ -39,11 +39,11 @@ In the `Vault List`, owners can see the Emergency Access status directly via bad
Creating vaults require the `create-vault` role. [Here](user-group-management.mdx#roles) you can read more about roles.
:::
-To create a vault in Hub, navigate to the vault list and click on the `Create Vault` button in the top right corner.
+To create a vault in Hub, navigate to the vault list and click `Add` → `Create New` in the top right corner.
Every vault has a name and optionally a description.
Fill out the form and continue the process by clicking the `Next` button in the right corner.
-
+
If the [Emergency Access](emergency-access.mdx) feature is enabled, the following step appears:
@@ -52,23 +52,19 @@ If the administrator allows custom council selection, you can adjust the default
Select the council members who should participate in emergency recovery and review the example recovery scenario.
Click `Next` to continue to the recovery key step.
-:::info[Early Access]
-Emergency Access is currently in **early access** and will be fully available in version 2.0.0.
-:::
-
:::info[Enterprise Feature]
Visit [cryptomator.org](https://cryptomator.org/hub/) for more information about Enterprise features.
:::
-
+
In the next step, the vault *recovery key* is displayed.
It can [restore access to the vault data](vault-recovery.mdx) in case of an emergency, e.g. if Cryptomator Hub is down.
Store it at a safe location, tick the checkbox and complete the setup by clicking the `Create Vault` button at the bottom
-
+
:::warning
The recovery key is **highly confidential**.
@@ -79,7 +75,7 @@ When the setup is finished, you have the opportunity to download the initial vau
You can unlock the vault and place data inside with [Cryptomator](https://cryptomator.org/downloads/).
If you skip this step, you can download the template [later](#download-vault-template).
-
+
## Vault Details {/* #vault-details */}
@@ -89,11 +85,11 @@ The details are displayed on the right side.
With the user role, you have access to the following details:
-
+
With the owner role, you have access to the following sections:
-
+
### Manage Vault {/* #manage-vault */}
@@ -114,7 +110,7 @@ Open the [vault details](#vault-details) page to manage a vault.
If a user should have access to this vault, you need to share it with the user.
Click in the search field of the `Shared with` section, select it from the results list and click the `Add` button.
-
+
### Change Ownership {/* #change-ownership */}
@@ -127,7 +123,7 @@ Only then, the user can unlock the vault with its device.
As a vault owner, you can see that an update is necessary when the `Update Permissions` button is clickable.
-
+
### Edit Vault Metadata {/* #edit-vault-metadata */}
@@ -147,10 +143,6 @@ To show the vault recovery key, click on the `Show Recovery Key` button in the [
### Setup/Fix Emergency Access Council {/* #emergency-access-council */}
-:::info[Early Access]
-Emergency Access is currently in **early access** and will be fully available in version 2.0.0.
-:::
-
:::info[Enterprise Feature]
Visit [cryptomator.org](https://cryptomator.org/hub/) for more information about Enterprise features.
:::
@@ -172,17 +164,17 @@ The WoT state of a user is displayed in the vault details page. The state can be
* **Unverified**: There is no trust chain between you and the specific user. Indicated with a red shield. You can change this by verifying the user.
* **Verified**: There is a trust chain between you and the specific user. Indicated with a green shield. You or a user you trust has verified the user.
-To verify `alice`, click on the red shield icon and select `Check Identity…`
+To verify `carol`, click on the red shield icon and select `Check Identity…`
-
+
-While verifiying a user, you need to enter the first characters of the user's public key fingerprint. This fingerprint is displayed in user coresponding user profile page.
+While verifying a user, you need to enter the first characters of the user's public key fingerprint. This fingerprint is displayed in the user's profile page.
-
+
-`alice` is now verified
+`carol` is now verified
-
+
The verification process is logged in the audit log with event type `Signed Identity`
diff --git a/docs/hub/vault-recovery.mdx b/docs/hub/vault-recovery.mdx
index 9e6bce2b..07fbc70a 100644
--- a/docs/hub/vault-recovery.mdx
+++ b/docs/hub/vault-recovery.mdx
@@ -1,7 +1,7 @@
---
id: vault-recovery
title: Vault Recovery
-sidebar_position: 7
+sidebar_position: 8
---
# Vault Recovery
@@ -10,12 +10,12 @@ This section contains instructions for recovering Cryptomator Hub vaults using t
Cryptomator Hub vaults can be recovered in two different ways:
-1. [Online Recovery](#online-recovery) - Reestablishes Hub controlled access management for a vault in case the vault admin password got lost
+1. [Online Recovery](#online-recovery) - Reestablishes Hub controlled access management for a vault in case it can no longer be managed in Hub
2. [Offline Recovery](#offline-recovery) - Restores vault data access of a hub managed vault in case of a disaster (e.g. Cryptomator Hub is down and immediate data access is needed)
## Online Recovery {/* #online-recovery */}
-This recovery method should be used, if the vault admin password got lost.
+This recovery method should be used if a vault can no longer be managed in Hub, for example because it lost all its owners or was accidentally removed from Hub.
In the process, a new Hub vault with the same key material as the "to-be-recovered" vault is created.
The membership information of the old vault cannot be migrated, hence all users/groups need to be added manually afterwards.
@@ -27,17 +27,18 @@ Requirements:
In Cryptomator Hub navigate to the vault list, click `Add` and `Recover Existing`
-
+
Enter the recovery key for the vault you want to restore. If you enter a recovery key from a different vault, the recovery will not work.
-Proceed with `Restore Vault`.
+Proceed with `Recover Vault`.
-
+
-Enter a new vault name, description and vault admin password. The new vault admin password is required to grant or revoke access to the vault.
+Enter a name and an optional description for the new vault.
+As its creator, you become the owner of the recovered vault and can grant or revoke access to it.
-
+
If successful, a new vault has been created. Proceed as follows:
@@ -69,7 +70,7 @@ Requirements:
Open the Cryptomator desktop app, right-click on the vault you want to restore in the vault list, click `Show vault options` in the opened context menu.
In the opening window, select the `Recovery`, read the label description and click the `Convert to Password-Based Vault` button.
-
+
Enter the recovery key for the vault you want to restore. If you enter a recovery key from a different vault, the recovery will not work. Proceed with `Next`.
@@ -79,17 +80,11 @@ In the next step choose a [good password](/docs/security/best-practices.mdx#good
Cryptomator requires at least 8 characters but we recommend you to use a longer phrases such as pass-sentences.
The bar below the password field estimates the strength of your password.
-
+
If the conversion was successful, a success message is shown.
You can close the dialog box.
-This vault is now converted to a password-based vault.
-
-
-
-After the conversion, when unlocking the vault, you are prompted for a password and only the one chosen in the previous step leads to a successful unlock.
-
-
+This vault is now converted to a password-based vault and can be unlocked with the above chosen password.
## Reversing Offline Conversion {/* #reversing-offline-conversion */}
diff --git a/docs/hub/your-account.mdx b/docs/hub/your-account.mdx
index f274bc9e..78378a0d 100644
--- a/docs/hub/your-account.mdx
+++ b/docs/hub/your-account.mdx
@@ -1,7 +1,7 @@
---
id: your-account
title: Your Account
-sidebar_position: 4
+sidebar_position: 5
---
# Your Account
@@ -28,7 +28,7 @@ If you lose your account key, you have two options: If you have access to an aut
The very first time you log in to Cryptomator Hub, you're asked to set up your account.
This is a one-time process that takes just a minute.
-
+
In the setup your [Account Key](#account-key) is generated and displayed.
We recommend to copy your Account Key to a secure place (e.g. password manager), but you can always view it later in your profile from any trusted browser.
@@ -46,7 +46,7 @@ It shows your account key and fingerprint, lists your trusted devices and more.
You can open it by clicking on your profile icon in the top right corner and select *Your Profile*.
-
+
### Change Language {/* #change-language */}
@@ -108,4 +108,4 @@ If you lose your account key and can't access any trusted browser, you can reset
All already authorized devices will be removed and access to shared vaults will be revoked.
After the reset, you can log in to Hub from a new browser and set up your account again.
-
+
diff --git a/src/pages/index.tsx b/src/pages/index.tsx
index a527d9cb..a2ca45d5 100644
--- a/src/pages/index.tsx
+++ b/src/pages/index.tsx
@@ -16,8 +16,8 @@ function HomepageHeader() {
-
- ✨ Upcoming Hub Features →
+
+ ✨ New Hub Features →