huly-platform/docs/guides/backup-restore.en.md

Backup & Restore Guide

Download a workspace backup and restore it into another Huly instance — whether that's a self-hosted deployment or one of the hosted options. This is the recommended way to move your data off a hosted workspace before it becomes unavailable.

Tip

Don't want to run your own server? You can also move to one of the existing hosted Huly forks instead of self-hosting. We're glad to help with the data migration either way — just keep in mind that none of these hosting options are free, since keeping servers running costs real money. See Need help? below to get in touch.

Overview

1. Download — from Settings → Backup in the workspace you want to move, grab a full copy of your data.
2. Restore — replay that backup into the destination workspace — either with the ready-made huly-selfhost scripts (restore-workspace.sh) or with the platform's admin tool (dev/tool) directly.

Step 1. Download your backup

Open the workspace and go to:

<your-workspace-url>/setting/setting/backup

(Settings → Backup in the left sidebar.) The page shows when the backup was last taken, how many snapshots and files it contains, and its total size.

Note

Backups are taken periodically, not continuously, so the latest backup can lag behind your live data by some time. Check Last backup on the page before you rely on it, and give it time to catch up if you just made important changes.

You have two ways to get the files:

• Download full backup — bundles every backup file into a single .zip you can keep on your computer. A RESTORE.md with restore instructions is included inside the archive.
• Copy download script (+ Copy token) — copies a small shell script that downloads every file with curl. The script is safe to save or share: it does not contain your token — it reads it from the HULY_BACKUP_TOKEN environment variable, or prompts for it when you run it.

Either option produces a folder that the restore tool can consume directly (see Step 2).

Tip

Large workspace? Prefer the download script over the button. "Download full backup" assembles the whole archive in your browser's memory before saving it, which can be slow or fail outright once a workspace has a lot of data. The script downloads files one by one with curl, so it handles large backups more reliably.

You can also expand Backup Snapshots or Backup Files to download individual files, e.g. to verify access or fetch a single snapshot.

Important

The Not backed up section lists blobs that are intentionally excluded from the regular backup (video, audio, and any file larger than the server's blob-size limit). Their content isn't in the archive or script above — if you need them on the destination, download each one individually from that list before you migrate.

Step 2. Restore into a Huly instance

You'll need a Huly platform you control to restore into — either huly-selfhost, a self-hosted deployment built from this monorepo, or another hosted instance where you have admin access.

Option A: huly-selfhost scripts (recommended)

The huly-selfhost repository ships helper scripts that wrap the admin tool with the right connection settings read from your huly_v7.conf (created by ./setup.sh). Make sure the stack is running (docker compose up -d), then from the huly-selfhost folder:

• restore-workspace.sh — one-shot migration: creates the admin account, creates and assigns the workspace, then restores the backup into it.

  ./restore-workspace.sh <backup-dir> <workspace> [options] [-- <extra args>]
  

  Useful options: -e/--email and -p/--password for the admin account (password is generated and printed if omitted), --skip-account / --skip-workspace if they already exist, --date <ms> to pick a snapshot. Anything after -- is passed to the underlying restore (e.g. -- --merge).

• backup-restore.sh — restore into an existing workspace:

  ./backup-restore.sh <backup-dir> <workspace> [date] [--no-accounts] [--no-upgrade]
  

  Accounts restore and the post-restore workspace upgrade are on by default (disable with --no-accounts / --no-upgrade), so there's no need to pass --accounts or configure ACCOUNT_DB_URL manually.

• run-tool.sh — general-purpose wrapper that runs any admin tool command (or an interactive shell) against your deployment, e.g. ./run-tool.sh create-account user@example.com -p pass -f First -l Last.

Example — full migration in one command:

./restore-workspace.sh ./backups/myws myws -e me@example.com

Option B: run the admin tool manually

For other deployments, restoring is done with the backup-restore command of the platform admin tool (@hcengineering/tool, dev/tool in this repo). Create the destination workspace first if it doesn't exist yet. Exactly how you invoke the tool depends on how the destination platform is run:

• huly-selfhost deployment — use run-tool.sh: it starts the hardcoreeng/tool container with all connection settings taken from your huly_v7.conf. Mount the backup folder into the container via RUN_TOOL_DOCKER_ARGS:

  RUN_TOOL_DOCKER_ARGS="-v /abs/path/to/backup:/backup" \
    ./run-tool.sh backup-restore /backup <target-workspace> --accounts
  

• Other Docker setups — run the hardcoreeng/tool image on your stack's network with the same environment variables your services use (SERVER_SECRET, DB_URL, ACCOUNT_DB_URL, STORAGE_CONFIG, ACCOUNTS_URL, TRANSACTOR_URL, ...) and the backup folder mounted — run-tool.sh is a good reference for the full invocation.

• Monorepo checkout with Rush — from dev/tool, run it against your configured environment, e.g. rushx run-local backup-restore ... for a local dev stack, or your own script that sets the same environment variables against your real databases.

In all cases the command and its arguments are the same:

backup-restore <path-to-backup-folder> <target-workspace> [date] --accounts

• <path-to-backup-folder> — the folder you downloaded/unzipped in Step 1.
• <target-workspace> — the destination workspace's identifier.
• --accounts — also restores the original users (their profile and social identities) into the target workspace. Without this flag only documents are restored, and every member has to be invited again by email.
• --upgrade — add this if the destination runs a newer model version than the backup.
• -m/--merge — don't delete documents that are missing from the backup (useful when merging into a workspace that already has data).

Note

Restoring accounts (--accounts) needs its own connection to the account database, configured via the ACCOUNT_DB_URL (and optional ACCOUNT_DB_NS) environment variables. See server/backup/README.md for the full reference of flags and per-entry-point environment variables.

Once the restore finishes, users sign in with their original email via a one-time code (OTP) — make sure the destination platform can send mail.

Need help?

Our team is happy to help with migration. Join the Huly community to ask questions and get updates, or email us directly at artem@hardcoreeng.com.

Troubleshooting

• 401 Unauthorized while downloading — your token expired, or you're not an owner/admin of the workspace. Get a fresh token from the Backup page.
• Members are missing after restore — re-run with --accounts and a valid ACCOUNT_DB_URL; without both, only documents are restored. (The huly-selfhost scripts do this by default — check you didn't pass --no-accounts.)
• A file/video is missing on the destination — check the Not backed up list on the Backup page and download it individually; it isn't part of the regular backup.
• Restore fails with a model/version error — add --upgrade if the destination runs a newer platform version than the source. (The huly-selfhost backup-restore.sh upgrades the workspace after restore by default.)
• Config not found: huly_v7.conf — the huly-selfhost scripts read connection settings from the config created by ./setup.sh; run it first.
• Network ... not found — the huly-selfhost scripts need the stack running; start it with docker compose up -d.
• Warning about blobs/blobs.json — the backup came from a datalake-based deployment and contains extra blobs the minio-based self-host stack can't ingest automatically; those blobs were not uploaded.

See also

• huly-selfhost — official self-hosted distribution, including restore-workspace.sh, backup-restore.sh and run-tool.sh.