Skip to main content

Quick Start

Want to see Cryptomator Hub in action before rolling it out to your team? This guide gets a test instance running on your own machine in about 10 minutes. No domain, no TLS certificates, no reverse proxy.

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, continue with Going to Production below.

Before You Start​

You need:

  • A machine with Docker installed, including Docker Compose (docker compose version should print a version number).
  • Ports 8080 and 8180 free on that machine.
  • About 1 GB of free RAM for the three containers (Hub, Keycloak, and Postgres).

Start Hub​

We provide a ready-made Compose file that runs Hub locally. Nothing to configure.

Open a terminal in an empty directory, download the file, and start the stack:

curl -fsSLO https://raw.githubusercontent.com/cryptomator/hub/refs/tags/2.0.0/deploy/compose/local/compose.yaml
docker compose up -d

Docker now pulls the images and starts the containers. Keycloak takes a minute or two to initialize on first start, so grab a coffee. Once Docker reports the hub container as started and healthy, you are good to go.

Log In​

Open http://localhost:8080 in your browser and log in with admin / admin.

note

Keycloak's admin console is available at http://localhost:8180, also with admin / admin. You don't need it for this tutorial, but it's where user federation and identity providers are configured later on. See Identity Provider for details.

Start Using​

Hub greets you with a short onboarding on your first login:

  1. Complete the admin profile. Hub needs a name and email address for the admin account.
  2. 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.
  3. Save your Account Key. Hub generates an 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, adding a user, or unlocking the vault from the Cryptomator desktop app. The User Guide and Admin Guide walk you through these tasks using complete worked examples.

Clean Up​

To stop Hub but keep your data:

docker compose stop

To remove everything, including the database:

docker compose down -v

Going to Production​

When you are ready to run Hub for real, this section sequences the Deployment Cookbook and Operations 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 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 with uptime guarantee and regular backups.

Plan Your Deployment​

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 for larger teams.

For more details, read Before You Begin — including why the public URLs must be final before the first start.

Choose a Recipe​

The Deployment Cookbook offers three recipes:

  • Docker Compose — a single Docker host behind a Traefik reverse proxy with Let's Encrypt. The simplest production setup.
  • Kubernetes — the Helm chart via the Helm CLI, for teams that already operate a cluster.
  • Rancher — 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​

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, Deploy, and Configuration — including which ports must never be published.

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 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 and Restore.

Keep It Healthy​

Running Hub is low-maintenance; these are the recurring and occasional tasks:

Next Steps​

  • Set up your organization — the Admin Guide walks through users, groups, identity providers, and more.
  • Bookmark Operations as the reference for everything maintenance.