---
name: quancard-server-install
description: Install, verify, back up and upgrade QuanCard Server, the open-source self-hosted sync service and web vault for the QuanCard iPhone app (zoolapp/quancard-server, Docker Compose with automatic HTTPS). Use when a user asks to self-host QuanCard, deploy QuanCard Server or the QuanCard web vault, pair an iPhone with their own QuanCard server, or back up, restore, upgrade or troubleshoot an existing installation.
compatibility: Runs on a Linux host with shell access, Docker Engine 24+, Docker Compose v2, git, openssl and curl; inspection also uses ss and dig when present. Needs internet access to GitHub and ghcr.io.
metadata:
  publisher: quancard.app
  version: "2026-10-06"
  server-release: "v0.1.1"
  docs: https://quancard.app/server/docs/
---

# Install QuanCard Server

QuanCard Server is one container image that serves the sync API and the browser vault. Vault
data is encrypted on the user's iPhone or in their browser before it reaches the server; the
server stores ciphertext only. Your job is to deploy it safely, prove it works, and hand the
first-run steps back to the user. A good install takes about 15 minutes.

Official sources, in order of authority: the pinned release in
https://github.com/zoolapp/quancard-server (README, `docs/deployment.md`, `scripts/`), then
https://quancard.app/server/docs/ (English: https://quancard.app/en/server/docs/). If anything here
disagrees with the pinned release's own files, follow the release and tell the user.

## Ground rules

1. **Never ask for or handle vault data.** Card numbers, CVCs, account numbers, vault passwords,
   recovery codes and backup passwords are never needed for installation. Refuse to collect them.
2. **Secrets stay on the host.** `.env` holds `QC_SECRET` and the one-time `QC_SETUP_TOKEN`. Never
   commit, upload, paste into tickets, or send them to any external service. Show the setup token
   to the user once, in their terminal, when they need it for first run.
3. **Read before you run.** Download scripts to a file and read them before executing. Never pipe
   a remote script straight into a shell.
4. **Ask before anything destructive or shared.** Get explicit confirmation before deleting
   volumes or data, overwriting an existing `.env` or compose file, stopping or reconfiguring
   services that already use ports 80/443, changing firewall rules, or editing DNS.
5. **Keep the hardened defaults.** Do not remove `read_only`, `cap_drop: [ALL]`,
   `no-new-privileges`, the non-root user, or the internal-only network of the app container. Do
   not publish port 8080 to the internet. Do not enable plain HTTP except for a localhost trial.
6. **Pin versions.** Install the latest published release tag, not `main`, unless the user asks
   for unreleased features.
7. **Reply in the user's language** and explain each change in one short sentence.

## Step 1: Inspect first (read-only)

Gather facts without changing anything, then summarise them and recommend a path:

```sh
uname -a; cat /etc/os-release
docker --version; docker compose version; git --version; openssl version
free -m; df -h /
ss -ltnp | grep -E ':(80|443|8080)\b' || echo "80/443/8080 free"
dig +short A <domain>; dig +short AAAA <domain>
ip -brief address    # compare with the DNS answer
```

If the host is behind NAT, ask the user for its public IP rather than querying a third-party
IP-echo service.

Also check whether a reverse proxy already runs (nginx, Caddy, Traefik, cloudflared), and find the
latest release:

```sh
curl -fsSL https://api.github.com/repos/zoolapp/quancard-server/releases/latest | grep '"tag_name"'
```

Minimums: Linux with Docker Engine 24+ and Compose v2, 1 vCPU and 512 MB RAM (Argon2id runs in the
browser, not on the server), a domain whose A/AAAA record points at this host, and ports 80 and 443
reachable from the internet (Let's Encrypt validation and HTTP to HTTPS redirect).

If Docker is missing, propose the official instructions at https://docs.docker.com/engine/install/
and wait for approval before installing system packages.

## Step 2: Choose a path

| Situation | Path |
| --- | --- |
| Ports 80/443 free, DNS points here | **A. Bundled Caddy** (recommended) |
| nginx, Traefik, Caddy or another proxy already owns 80/443 | **B. Own reverse proxy** |
| No public IP or inbound ports, Cloudflare in use | **B** with Cloudflare Tunnel |
| User only wants to look around on this machine | **C. Localhost trial** |

Present the recommendation with the reason and wait for the user to confirm.

## Step 3A: Bundled Caddy

```sh
TAG=v0.1.1   # replace with the latest tag found in Step 1
git clone --depth 1 --branch "$TAG" https://github.com/zoolapp/quancard-server.git ~/quancard
cd ~/quancard
./scripts/init-env.sh vault.example.com      # writes .env (mode 600) with random secrets; never overwrites
grep -q '^QC_IMAGE_TAG=' .env || echo "QC_IMAGE_TAG=${TAG#v}" >> .env
docker compose pull quancard || docker compose build quancard   # build from the same tag if the image is unavailable
docker compose up -d --wait                   # Caddy obtains and renews certificates
```

The repository's `scripts/install.sh` does the same for a pinned tag. If you use it, download it,
read it, then run `sh install.sh <domain>`.

## Step 3B: Own reverse proxy or Cloudflare Tunnel

Run only the `quancard` service and bind it to loopback. Save this as a separate file such as
`compose.proxy.yaml` next to `.env`, and pass `-f compose.proxy.yaml` to every `docker compose`
command so the repository's bundled Caddy compose file is not used:

```yaml
services:
  quancard:
    image: ghcr.io/zoolapp/quancard-server:0.1.1   # pin the release
    environment:
      QC_SECRET: ${QC_SECRET}
      QC_SETUP_TOKEN: ${QC_SETUP_TOKEN}
      QC_PUBLIC_ORIGIN: https://vault.example.com
      QC_TRUST_PROXY: "1"
    ports: ["127.0.0.1:8080:8080"]
    volumes: [quancard-data:/data]
    read_only: true
    tmpfs: ["/tmp:size=16m"]
    cap_drop: [ALL]
    security_opt: ["no-new-privileges:true"]
volumes: { quancard-data: {} }
```

Work from a checkout of the same tag (as in 3A) and generate secrets with
`./scripts/init-env.sh <domain>`. If `docker compose pull` is denied or the tag is missing on
ghcr.io, build the identical image from the checkout instead:
`docker build --build-arg QC_VERSION=0.1.1 -t ghcr.io/zoolapp/quancard-server:0.1.1 .` The proxy
must terminate TLS, pass `Host` unchanged, set `X-Forwarded-Proto: https` and `X-Forwarded-For`,
and allow request bodies up to 17 MB. nginx:

```nginx
location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto https;
    proxy_set_header X-Forwarded-For $remote_addr;
    client_max_body_size 17m;
}
```

`QC_TRUST_PROXY=1` trusts exactly one proxy hop, so port 8080 must never be reachable from outside.
For Cloudflare Tunnel use `service: http://localhost:8080`; Cloudflare then terminates TLS and sees
traffic metadata, while vault contents stay end-to-end encrypted. Show the user the proxy change
before reloading a proxy that serves other sites.

## Step 3C: Localhost trial

```sh
./scripts/init-env.sh localhost
docker compose -f compose.local.yaml up -d
```

Open http://localhost:8080 in Chrome, Edge or Firefox (Safari may reject the `Secure` session
cookie on plain localhost). Tell the user not to store real cards in a trial on a shared computer.

## Configuration reference

| Variable | Required | Meaning |
| --- | --- | --- |
| `QC_DOMAIN` | compose | Host name for Caddy; also sets `QC_PUBLIC_ORIGIN` |
| `QC_SECRET` | yes | ≥ 32 random bytes, hex. Encrypts TOTP secrets and keys HMACs. Losing it disables everyone's two-step verification; back it up with the data |
| `QC_SETUP_TOKEN` | first run | One-time owner setup token (≥ 24 characters); without it setup is closed |
| `QC_PUBLIC_ORIGIN` | yes | The `https://` origin users open |
| `QC_TRUST_PROXY` | behind a proxy | `1` trusts one proxy hop |
| `QC_ALLOW_INSECURE_LOCALHOST` | development | `1` allows plain HTTP on localhost only |
| `QC_IMAGE_TAG` | optional | Image tag used by compose; keep it pinned |

## Step 4: Verify (all must pass)

```sh
docker compose ps                                    # quancard (and caddy) running and healthy
curl -fsS https://vault.example.com/healthz          # {"ok":true}
curl -fsS https://vault.example.com/api/v1/status    # version and capabilities
curl -sI http://vault.example.com/ | head -1         # redirect to https (path A)
stat -c '%a' .env                                    # 600
ss -ltnp | grep ':8080' || true                      # nothing, or 127.0.0.1:8080 only
```

From outside the host, confirm port 8080 is closed (for example `nc -vz <public-ip> 8080` from
another machine). Plain HTTP requests to the app are answered with `426 Upgrade Required`; the
iPhone app connects only over HTTPS with a valid certificate.

## Step 5: Backups (propose, then schedule with consent)

```sh
./scripts/backup.sh                               # consistent online snapshot in backups/
./scripts/restore.sh backups/quancard-<UTC>.sqlite # verify, stop, replace, restart
```

Suggest a nightly cron such as `0 3 * * * cd ~/quancard && ./scripts/backup.sh`. Backups hold
ciphertext and checksums only, but `.env` (with `QC_SECRET`) must be kept with them. For off-site
copies add another encryption layer (restic, age) and rehearse a restore once.

## Step 6: Hand over first run (the user does this)

1. Open `https://<domain>` and paste the setup token. Show it with `grep QC_SETUP_TOKEN .env` in the
   user's own terminal; do not copy it anywhere else.
2. Create the owner account with a passphrase of at least 15 characters and turn on two-step
   verification (Settings → Security). There is no password reset: the server never knows it.
3. Pair the iPhone: web Settings → Devices → Pair iPhone, then in the iPhone app Settings → Sync →
   Self-hosted Sync, scan the pairing code (labels may vary by app version; per quancard.app,
   self-hosted sync on iPhone opens with the App Store release, so the web vault works on its own
   until then). The QR code contains the vault key, works once and expires after 10 minutes; only
   the user's own phone should see it.
4. Invite family members from Settings → Members (one-time links, valid 7 days).

## Upgrades

Back up first, read the release notes in `CHANGELOG.md`, then raise `QC_IMAGE_TAG` in `.env` and
run `docker compose pull && docker compose up -d --wait`. Migrations run automatically at start. The
server refuses to start on a database written by a newer version; to roll back, restore the backup
that matches the older version.

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| Certificate not issued | DNS must point at this host and ports 80/443 must be reachable; read `docker compose logs caddy` |
| Only a sign-in page, no setup | The owner already exists; sign in or ask the owner for an invitation |
| Setup token rejected | Copy `QC_SETUP_TOKEN` from `.env` exactly; each token works once |
| Browser says HTTPS is required | Open the `QC_PUBLIC_ORIGIN` address; behind a proxy set `QC_TRUST_PROXY=1` |
| iPhone cannot connect | Open `https://<domain>/healthz` in the phone's browser; the certificate must be valid |
| Pairing code expired | Codes last 10 minutes; close and create a new one |
| Forgotten password | Cannot be reset; a paired iPhone keeps its local copy |

## Final report to the user

End with: chosen path and why, installed release tag, install directory, each Step 4 check with its
result, backup status (scheduled or not), what the user must do next (Step 6), and anything you
skipped or could not verify. Note that QuanCard Server is a development preview without an
independent security audit, and point to the threat model:
https://github.com/zoolapp/quancard-server/blob/main/THREAT_MODEL.md
