Moving an install to a new server

The wallet encryption keys. ENCRYPTED_ENCRYPTION_KEY and ENCRYPTION_KEY_PASSPHRASE live only in .env — they are not in .env.example, and nothing else on the server can derive them. Restore the database onto a box with a different pair and every custodial and master wallet the platform ever generated becomes an address you can watch and never spend from.

The cutover. Once DNS points at the new box, deposits, withdrawals and trades land there. Everything written on the old box after your dump is stranded. Verify the new host completely before you move DNS.

1. Lower the DNS TTL. Drop the A record's TTL to 300 seconds at least 48 hours ahead — a record served at 24 hours cannot be pulled back inside a maintenance window, and the rollback below depends on being able to.

2. Build the new box to the same spec. Same Node major (22, 24 or 26 — the range is fixed by the prebuilt WebSocket binaries), MySQL, Redis, and a reverse proxy. See Server requirements.

3. Take a throwaway rehearsal copy if you can. The checks that fail are almost never the database.

4. Collect the purchase codes for the core product and every installed addon. You will re-activate all of them on the new host, and you cannot do it from the panel until the platform is running there.

5. Pick a quiet window. Redis is not migrated (see below), so every user is logged out the moment you cut over.

1. Drain and stop the old host.

   node backend/scripts/graceful-stop.mjs

   This polls the transaction table for withdrawals in PENDING or PROCESSING and waits for the count to reach zero before entering maintenance mode. The cap is GRACEFUL_STOP_TIMEOUT_MS, default 120 000 ms; when the count is not observable it falls back to a 10-second grace window. It then runs pnpm stop itself, which proves the ports are free and parks a 503 page on 3000 and the backend port. Do not run pnpm stop afterwards.

2. Dump MySQL, from the shell rather than the admin screen — the built-in backup takes no lock, ignores DB_PORT and connects as three-byte utf8:

   mysqldump -h "$DB_HOST" -P "$DB_PORT" -u "$DB_USER" -p \
     --single-transaction --quick --routines --triggers --events \
     --default-character-set=utf8mb4 \
     "$DB_NAME" | gzip > /var/backups/bicrypto-move.sql.gz

3. Snapshot ScyllaDB, if Ecosystem or Futures is live. nodetool snapshot trading and nodetool snapshot futures — see below.

4. Copy the tree to the new host, with the exclusions in the next section.

5. Restore MySQL on the new host into a utf8mb4 database, and restore the Scylla keyspaces from the snapshots taken in step 3.

6. Fix .env for the new host: NEXT_PUBLIC_SITE_URL, DB_HOST, REDIS_HOST, SCYLLA_CONNECT_POINTS, and every callback URL listed below.

7. Rebuild and start.

   pnpm install
   pnpm build:frontend
   pnpm start

8. Re-activate every licence on the new hardware.

9. Verify against the checklist further down, reaching the new box by its IP or through a hosts-file entry rather than through DNS.

10. Cut over DNS, then re-issue or move the TLS certificate and watch the first hour.

rsync -az --delete \
  --exclude 'node_modules/' \
  --exclude 'frontend/.next/' \
  --exclude 'lic/' \
  --exclude 'backup/' \
  --exclude 'updates/' \
  --exclude '.update-backup-*' \
  /path/to/v5/ newhost:/path/to/v5/

Each lic/<productId>.lic is an AES-256-GCM envelope whose key is derived partly from the hardware fingerprint of the machine that wrote it. On different hardware it does not decrypt. It does not fail over — it fails shut.

Worse, the extension manager's licenseVerified flag is not a stored column — there is no such column on the extension row. The listing route computes it per product from a single directory read of lic/, so it is nothing more than an existence check on the file: is lic/<productId>.lic there? Nothing decrypts it, so a carried-over .lic shows as verified on the new box while every route the product owns answers 403. That is the exact shape of "the panel says it is licensed but the feature is dead".

Leave lic/ behind and re-activate. Set the final NEXT_PUBLIC_SITE_URL in .env before you activate: activation sends the domain from that value plus the new host's fingerprint to the licence service, and that is the pair it records.

pnpm activate-product <productId> <purchaseCode> [clientName]

nodetool snapshot trading
nodetool snapshot futures

pnpm install          # rebuilds node_modules against this box's store
pnpm build:frontend   # mandatory — see below
pnpm start

In production the auth cookies are issued Secure with SameSite=None, and browsers discard those over plain HTTP. A new host reachable only over HTTP looks healthy and cannot sign anyone in. Get the certificate working before you judge the login.

pm2 startup     # installs the boot hook (the installer does run this)
pnpm start
pm2 save        # the installer NEVER runs this

1. Three PM2 apps online. pm2 list shows backend, frontend and cron — two if you run CRON_MODE=inline. A missing cron means nothing scheduled runs, and no screen in the panel will tell you.

2. The API answers. This is the same readiness probe the update tooling uses, and it needs the backend, MySQL and Redis all healthy.

   curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:4000/api/settings

3. The licence reads active. GET /api/admin/system/license/status returns licenseStatus — you want active, not not_found or invalid. Check every addon, not just core.

4. Platform health is green. The admin dashboard at /admin polls /api/admin/system/health/batch, which probes the real services and returns overall.score out of 100 with a status of healthy, warning or critical. A critical service costs 40 points on its own, so anything below healthy names a service that is genuinely down.

5. A custodial wallet decrypts. Open one in the admin panel. If you copied the wrong .env, "Invalid encryption data or wrong encryption key" appears here and nowhere else — every other screen looks fine. This is the single check that proves the keys came across.

6. Uploads resolve. Open a KYC application with a document attached. A broken image means frontend/public/uploads did not make the trip.

7. You can log in, over HTTPS, on the new certificate.

8. The order books are populated, if you run Ecosystem or Futures. An empty book while users hold inOrder balances means Scylla did not come back.

9. Scheduled tasks have recent run times at /admin/system/cron.

10. Nothing is listening publicly on 4000 or 4001. From another machine, curl -m 5 http://NEW_IP:4000/api/settings should time out or be refused. The installer's firewall step never touches 4000, and the backend binds every interface.