WhiteLabelBridge Docs
Deploy on One Server, Then Launch via Wizard
This guide is for token teams deploying WhiteLabelBridge on their own infrastructure. Frontend and backend run on the same server by design.
1. Prerequisites
- Linux server (Ubuntu or Debian recommended).
node >= 18(Node 20 LTS recommended) and npm.- Internet access for package download.
- Recommended for production: PostgreSQL + Redis + stable RPC endpoints.
- Optional but recommended: domain pointed to server before finalize.
2. One-Command Install
npm run setup:serverInstaller actions:
- Installs frontend/backend dependencies.
- Generates bootstrap defaults (including wizard API key default).
- Builds frontend output.
- Initializes DB schema when
PG_CONNECTION_STRINGis present. - Starts or reloads PM2 processes.
- Prints wizard URL and setup status URL.
Useful variants:
SKIP_PM2=1 npm run setup:server
AUTO_INSTALL_SYSTEM_DEPS=0 npm run setup:server
FRONTEND_PORT=8080 BACKEND_PORT=4000 npm run setup:server3. Complete the Setup Wizard
- Open the wizard URL printed by the installer.
- Enter branding, chain settings, token addresses, signer, and decimals.
- Pick mode per side:
vaultormint. - Confirm decimals exactly match deployed contracts/mints.
- Save configuration and verify success status.
Field-level definitions are documented in Wizard Input Reference.
4. Finalize Runtime
npm run setup:finalizeFinalize actions:
- Ensures database schema is initialized.
- Reloads PM2 with generated runtime environment.
- Optionally configures nginx from wizard domain/backend URL.
- Optionally provisions SSL with certbot.
Variants:
CERTBOT_EMAIL=ops@yourdomain.com npm run setup:finalize
CONFIGURE_NGINX=0 npm run setup:finalize5. Validate Service Health
npm run pm2:status
curl -s http://127.0.0.1:3000/setup/status
Confirm setup status returns "configured": true, then verify UI loads and wallet connect works.
6. Gas + Decimal Rules
| Area | Rule |
|---|---|
| BESC release queue gas | 1000 gwei fixed. |
| External EVM gas | Chain-native estimate and runtime gas behavior. |
| Solana fees | Native Solana fee model. |
| Cross-decimal conversion | Non-exact conversion is rejected to prevent over/under mint and drift. |
7. Common Failure Recovery
- Wizard save fails check required fields Validate URLs, addresses, and decimals format.
-
PM2 start fails
dependency/runtime mismatch
Re-run install and inspect
npm run pm2:logs. -
Unauthorized API
API key mismatch
Re-save wizard API key then run
npm run setup:finalize. - Bridge amount rejected decimal mismatch Correct decimals in wizard, save, finalize, then retest.
8. Launch Gate
Do not launch before completing the full production checklist: