Running the Crusade Vault service on a NAS

What you need

• A NAS with an Intel or AMD processor (x86-64) that runs containers: Synology (Container Manager), QNAP (Container Station), UGREEN (the Docker app) or any Linux server with Docker. NASes with an ARM processor aren't supported yet. The maker's spec sheet names the processor.
• The image file and the settings file from your Crusade download page: crusade-vault-<version>-amd64.tar.gz and docker-compose.yml. The .sha256 file beside the image says what the download should be, if you want to check it.
• A way to type commands on the NAS (SSH), for two steps: setting the folders' owner, and a restore. On a Synology it's Control Panel > Terminal & SNMP > Enable SSH; on a QNAP, Control Panel > Network & File Services > Telnet/SSH. Turn it off again afterwards if you don't use it.
• A fixed address for the NAS on your local network, so Crusade finds it every day: set it on the NAS, or reserve its address in your router.

1. The image

Load the image file into the NAS's container app:

• Synology Container Manager: Image > Add > Add From File.
• QNAP Container Station: Images > Import.
• UGREEN Docker: Image > Add > Import (local image).
• Docker on the command line: docker load -i crusade-vault-<version>-amd64.tar.gz

The image is called crusade-vault-amd64:<version>. It's the same name in docker-compose.yml.

2. The three folders

Make one folder for the service, on the NAS's disk where your containers usually go (on a Synology, the docker shared folder: /volume1/docker/crusade-vault). Put docker-compose.yml in it, and make three folders beside it. Make them yourself first: neither the NAS nor the service makes them for you. In the NAS's file manager, or over SSH:

mkdir -p /volume1/docker/crusade-vault
cd /volume1/docker/crusade-vault
mkdir vault keys backups

They start empty: the service fills them the first time it starts.

• **Don't share vault or keys on the network**, and don't give the team access to them. Crusade reaches the vault through the service, never through the folders.
• **backups can be on another disk** of the NAS: change the ./backups line in docker-compose.yml to that folder's path. Not inside vault or keys: the service refuses that, and the other way round.

The folders' owner: 7429

The service runs as its own user, number 7429, never as an administrator. The three folders must belong to that user, or the service can't write in them. The NAS's file manager can't set a number as an owner, so do it over SSH, in the service's folder:

cd /volume1/docker/crusade-vault
sudo chown -R 7429:7429 vault keys backups
sudo chmod 700 vault keys backups

(Use your folder's path: on a QNAP it's usually under /share/Container/.) If you skip this, the service doesn't start, and its log says the vault service can't start: it can't write in /keys. The vault, keys and backups folders must belong to the service's user, 7429 …. Do it again if you ever copy the folders somewhere new.

3. The time zone

Open docker-compose.yml and find the line - TZ=UTC. Set it to your time zone, by its name in the time zone list: America/New_York, America/Chicago, America/Los_Angeles, Europe/London, Europe/Berlin, Australia/Sydney and so on (the "TZ identifier" column of Wikipedia's "List of tz database time zones").

The backups' schedule is in this time: "every day at 2:00 AM" means 2:00 AM where the NAS is only when it's right. Left at UTC, a backup set for 2:00 AM runs at 2:00 AM UTC, which may be the middle of your working day. Crusade's Backups window shows the zone next to the time ("In the NAS's time zone (America/New_York, UTC-4)."), so a wrong one is easy to spot. Changed later, it takes effect when the service is started again.

4. Start it, and read its codes

Start the service from docker-compose.yml:

• Synology Container Manager: Project > Create: pick the service's folder; it finds docker-compose.yml.
• QNAP Container Station: Applications > Create: paste in docker-compose.yml, and change the three folders' ./ paths to the full paths of the folders you made.
• UGREEN Docker: Project > Create, then:
  1. Name it crusade-vault.
  2. Storage path: the service's folder, /volume1/docker/crusade-vault, the one holding docker-compose.yml. Not the vault, keys or backups folder inside it.
  3. Import ▾ > the docker-compose.yml file. Its text shows in the box.
  4. In the box, change - TZ=UTC to your time zone (step 3), if you haven't already.
  5. Deploy.

Don't start the image straight from the Image list: that makes a container with a stray folder of its own (named after the image, like crusade-vault-1), not tied to the three folders, so nothing is kept where step 2 says. Ignore UGREEN's "PUID=1000 PGID=10" hint too: the service runs as its own user, 7429 (step 2).

• Docker on the command line: docker compose up -d in the service's folder.

Then open the container's log (in the container app: the container crusade-vault > Log; or docker logs crusade-vault). When it starts it prints a block like this:

Crusade Vault service
  Listening on: 0.0.0.0:7429
  Join code:    VAULT-UA44-3HV2-G338-DWQ2
  Setup code:   SETUP-GC9B-CGUJ-YKY4-USXN
  This vault isn't made yet. ...

• The join code is what everyone types once to join the vault, with the NAS's address. It proves to Crusade that it's your vault service before anything is sent. Once the vault is made, the log (and Crusade) show it with the vault's name in front, TESTSHOP-UA44-3HV2-G338-DWQ2; the letters after the name never change, and either form works.
• The setup code is only there while the vault isn't made yet. It works once. If the service restarts before the vault is made, it prints a new one.

Now, in Crusade, either:

• Make a new vault there: Vault… > Create Vault… > On a Crusade Vault service: the NAS's address, the join code, the setup code, the vault's name, your own name and password (you're its first admin), and whether to encrypt it. Write down the recovery code Crusade shows you once.
• Or move a folder vault into it: signed in to the folder vault as an admin, Vault > Move Vault to a Service…: the address, join code and setup code, and whether to encrypt it. Crusade copies every file across, the service checks the copy, then it opens. Everyone then joins with the join code Crusade shows at the end. The old folder is kept as it was; delete it by hand later, when you're sure.

Encrypt the vault (recommended) keeps every file, record and backup unreadable without the vault's master key (step 5). Don't encrypt is picked by default: the files are as readable as the NAS's disk. To encrypt, type the sentence Crusade shows, "I understand the risk, I accept": if the master key is lost, the vault's files and any encrypted backups are scrambled, unusable data forever, and not even Crusade support can get them back. Either way, every connection is encrypted and passwords are never stored readable. Step 8 changes it later.

If the move stops partway (the connection drops, the NAS restarts), nothing is lost: Move Vault to a Service… again shows Carry On, which sends only what's missing. A restarted service prints a new setup code; use that one. If it stops at the very end, after the copy was checked but before the service opened, Sign In to Another Vault says "This move didn't finish": an admin of the old vault clicks Finish the Move…, signs in once, and types the setup code from the log.

Everyone else: Sign In to Another Vault… > A Crusade Vault service: the NAS's address and the join code, then their name and password.

5. Back up the keys folder, once, now

If you chose to encrypt the vault (recommended), every file in it, and every backup of it, is encrypted. The key that opens them, the vault's master key, is the file master.key in the keys folder. Only the master key decrypts the vault.

• The recovery code doesn't. Crusade shows it once, when the vault is made, and it only sets a new password for an admin who forgot theirs. It can't decrypt a file, and it can't restore a backup.
• If the master key is lost, the vault is lost. No one can open its files or its backups: not you, not Crusade, not the recovery code. There is no way around this. It's what makes a copied vault folder or a stolen backup useless. The master key is on the NAS too, so whoever takes the NAS or its disks has both: keep the NAS itself where only people you trust can reach it.
• **Copy the whole keys folder somewhere else, once, right after the service first starts:** all three files, master.key, service.key and service.pem. A USB stick kept in a drawer, or a password manager that holds files. They never change after that, so one copy is enough. service.key and service.pem are the service's certificate: with them, a rebuilt service is the same service to everyone's Crusade. Without them it makes a new one, and every computer has to join again with its new join code: Sign In says the service's certificate changed, and Join with a New Code… there takes the new code.
• Never keep it with the vault's backups. Someone who gets a backup and its key together can open every file in it. The service never puts the master key in a backup.
• For example, the NAS dies. On a new NAS (or a PC running Docker), you put back the keys folder from its copy and restore the newest backup zip from your copy of the backups (step 7). That's all it takes: the zip and the keys copy. The recovery code isn't part of it.
• To move the vault to a new NAS, bring the vault folder and the keys folder (and set their owner again, step 2). The service checks the key is the vault's own and won't start with another one.

If you chose not to encrypt it, the files in vault and every backup are readable by anyone who can open them (a pulled disk, a copied folder, a backup zip). There's no master key to lose. Copy the keys folder anyway: it holds the service's certificate, and without it a rebuilt service is a new one that every computer joins again. Keep the NAS, its backups folder and every copy of them where only people you trust can reach them. To encrypt it later, see step 8.

6. Backups

The service backs the whole vault up into its backups folder by itself: every day at 2:00 AM (in the time zone of step 3), keeping the last 14. An admin changes this in Crusade: Vault > Backups… (daily at a time, every few hours, or off; how many to keep; Back Up Now). People can keep working while a backup is made. A backup the NAS missed because it was off is made as soon as it's back.

• Each backup is one dated zip. In an encrypted vault it's sealed with the master key: only the service, with that keys folder, can put it back. A vault that isn't encrypted makes plain zips that anyone with the file can read. A file RESTORE.txt inside says how to put it back.
• Before each one the service checks there's room on the disk. If there isn't, it doesn't make one, and admins are told when they next sign in. They're also told when the newest backup is more than 2 days old.
• An admin can also save a backup on their own computer: Vault > Back Up Vault… downloads one. The master key stays on the NAS.

Copies away from the NAS

A backup on the same NAS isn't off-site. If the NAS is stolen, burns, or its disks fail together, its backups go with it. Copy the backups folder somewhere else as well, on a schedule: the NAS's own backup app does it (Hyper Backup on a Synology, Hybrid Backup Sync on a QNAP), to a USB drive you take home, another NAS, or a cloud storage account. An encrypted vault's backups are encrypted, so a copy in the cloud can't be read without the master key, which stays apart (step 5). A vault that isn't encrypted has readable backups: copy them only to a place you trust, or turn on the backup app's own encryption.

If the master key is ever exposed

Crusade can't replace a vault's master key yet. Anyone who has the key and a copy of the vault's data (the NAS's folders, a backup, or an anchor's copies) could read the files in that copy. Copies already taken somewhere else can't be called back. Until a new key can be made:

1. Turn off every anchor (Vault ▸ Backups… ▸ Anchors ▸ Turn Off…). Each one's copies are removed the next time that computer reaches the vault.
2. Keep the NAS and every backup copy where only people you trust can reach them, and delete the copies you no longer need.
3. To protect the files from whoever has the key, set up a new vault service (it makes a new master key) and add the files to it. The old vault keeps the version history: keep it, and its backups, somewhere safe.
4. Questions: crusadecad.com/support.

7. Putting a backup back (restore)

A restore replaces the vault with the vault as it was in a backup. Work checked in after that backup isn't in it: whoever did it still has those files in their working folder, and checks them in again.

1. Stop the service (the container app: stop crusade-vault; or docker compose stop).
2. If the keys folder is lost too (a new NAS), put the whole folder back from its copy (step 5) and set its owner (step 2). An encrypted backup can't be restored without it: the recovery code can't stand in for it.
3. Put the backup file in the backups folder, if it isn't there.
4. Over SSH, in the service's folder, run the restore with the backup's file name:

   sudo docker compose run --rm crusade-vault --restore "/backups/Test Shop vault 2026-10-24 214142.zip"

• **Into an empty vault folder,** it restores.
• Over the vault that's there now, it refuses, unless you add --replace "<the vault's exact name>". Then it first saves a backup of the vault as it is now (named "… before restore", beside the others), then puts the old one back.
• It checks the backup is whole, is this kind of vault's, and, if it's encrypted, that the keys folder has the master key it was sealed with, before it changes anything. A refusal says why, in plain words, and changes nothing.
• It puts the vault back as the backup has it, encrypted or not, even if encryption was turned on or off since.
• If it stops partway (the NAS lost power), run the same command again: it carries on.

1. Start the service again. Everyone signs in with the accounts and passwords they had at the time of the backup.

8. Turning encryption on or off

Whether the vault is encrypted is chosen when it's made (Create Vault, or Move Vault to a Service…). To change it later, an admin runs one command on the NAS. Crusade can't change it.

1. Make a backup first (Vault > Backups… > Back Up Now), then stop the service, as for a restore.
2. Over SSH, in the service's folder, run:

   sudo docker compose run --rm crusade-vault --encryption off

or --encryption on. It asks for an admin's name and password (typed at the prompt, never on the command line), says what the change means, then asks for the vault's name, typed exactly. Nothing is written before that.

1. Start the service again. Everyone in the vault sees a note, once, that encryption was turned on or off, and the Vault Log records who did it.
2. Turning it off rewrites every file, version and record readable on the NAS's disk. Old backups and Anchor copies stay encrypted, and new ones are plain. master.key stays in the keys folder: keep it and its copy, since only it opens those old backups.
3. Turning it on encrypts everything with the vault's master key. It uses the master.key already there, or makes one. When it's done, copy the whole keys folder somewhere off the NAS (step 5). If the master key is lost, the vault's files and its encrypted backups are scrambled, unusable data forever. Not even Crusade support can get them back. Old plain backups and Anchor copies stay readable.
4. If it stops partway (the NAS lost power), run the same command again: it carries on. After a stop while turning it off, the service won't start until it's done. After a stop while turning it on, the service's next start finishes it.
5. TLS on every connection, and passwords kept only as hashes, stay on either way.

9. Keep me signed in

Crusade's Sign In has Keep me signed in on this computer, ticked to start: Crusade then signs that person in when it starts. It ends when they sign out, when their password is changed (except on the computer that changed it) or reset, when their account is turned off, or after 30 days unused. Each use renews it.

To change the 30 days, or turn it off for everyone, remove the # in front of this line under environment: in docker-compose.yml, set the number, then start the service again: - CRUSADE_VAULT_KEEP_DAYS=30 (any number of days; 0 turns it off, and Sign In stops offering it).

The network

• The service listens on port 7429, on your local network. If the NAS has a firewall, allow 7429 from that network only.
• Never forward that port from the internet. To work away from that network, use the NAS's own VPN. The vault then works as it does there.

Updating the service

When a new version comes out: load its image (step 1), change the version in docker-compose.yml's image: line, and start the project again (Container Manager: Project > Action > Build; or docker compose up -d). The vault, keys and backups folders stay as they are. Make a backup with Back Up Now first.