nullcart/deploy/DEPLOYMENT_GUIDE.md

Deployment guide

1. Requirements

• Ubuntu 22.04+ (or similar Linux)
• Docker Engine and Compose plugin — follow Install Docker Engine on Ubuntu
• A domain name pointing at your server (A record for clearnet HTTPS)

2. Server setup

Deploy as root on the VPS. Docker Engine and Compose plugin must be installed — Install Docker Engine on Ubuntu.

Verify:

docker compose version

3. Clone the repository

cd /root
git clone https://github.com/<org>/nullcart.git nullcart
cd nullcart

Replace <org>/nullcart with your actual repository URL once published.

4. Configure environment

cd /root/nullcart
cp .env.example .env.prod
chmod 600 .env.prod

Edit .env.prod. Mandatory configuration:

Variable	Production value
COMPOSE_PROJECT_NAME	nullcart_prod
POSTGRES_PASSWORD	strong random password
POSTGRES_MIGRATIONS_RUN	true
PGADMIN_DEFAULT_PASSWORD	strong random password
NODE_ENV	production
CORS_ORIGINS	https://your-domain.com
CLEARNET_DOMAIN	your-domain.com
JWT_SECRET	strong random secret
CMS_PASSWORD	strong admin password
SHOP_NAME	your shop name
SHOP_FIAT_CURRENCY	USD, EUR, GBP, CAD, AUD, or CHF
SIGNED_COOKIE_JWT_SECRET	strong random secret
BASE64_ENCRYPTION_KEY	generate with openssl rand -base64 32
MONERO_NETWORK	mainnet
MONERO_DAEMON_ADDRESS	mainnet node host:port
MONERO_WALLET_RPC_USERNAME	strong random username
MONERO_WALLET_RPC_PASSWORD	strong random password
MONERO_WALLET_PASSWORD	strong wallet password
VITE_API_BASE_URL	/api
VITE_SHOP_FIAT_CURRENCY	same as SHOP_FIAT_CURRENCY

Optional — adjust Monero payment confirmation rules:

MONERO_CONFIRMATION_TIERS — JSON array. For each order, the shop uses minConfirmations from the first tier where the order total (in SHOP_FIAT_CURRENCY) is <= upToTotalFiat. The last tier is a catch-all and must omit upToTotalFiat. At most one tier may use minConfirmations: 0 (accept on mempool); that tier cannot be the catch-all.

Example (default in .env.example):

[
    { "upToTotalFiat": "30", "minConfirmations": 0 },
    { "upToTotalFiat": "100", "minConfirmations": 3 },
    { "upToTotalFiat": "300", "minConfirmations": 5 },
    { "minConfirmations": 10 }
]

Orders up to 30 → 0 confirmations; up to 100 → 3; up to 300 → 5; above 300 → 10. Tiers are shown read-only in CMS shop settings.

5. Create the Monero wallet

./monero-wallet-rpc/setup-monero-wallet.sh --env-file .env.prod

6. Bootstrap TLS certificates

Nginx needs certificate files before it can start on port 443. For the first deploy, create a temporary self-signed pair (replaced after Let's Encrypt):

./deploy/scripts/bootstrap-certs.sh

After the stack is running, obtain real certificates (step 8).

7. Start the stack

./deploy/scripts/deploy.sh

Wait until backend and nginx are healthy:

docker compose --env-file .env.prod -f docker-compose.prod.yml ps

8. Issue Let's Encrypt certificates

Remove the temporary bootstrap certificates under deploy/certs/live/ (Certbot cannot issue into the layout created by bootstrap-certs.sh):

rm -rf deploy/certs/live/*

Request the real certificate:

./deploy/scripts/issue-certs.sh --email you@example.com

Reload nginx:

docker compose --env-file .env.prod -f docker-compose.prod.yml exec nginx nginx -s reload

Automatic renewal

Open root's crontab:

crontab -e

Add a weekly job (/root/nullcart is the standard deploy path):

0 3 * * 0 /root/nullcart/deploy/scripts/renew-certs.sh >> /var/log/nullcart-cert-renew.log 2>&1

Save and exit the editor. Optional — run once manually to verify:

/root/nullcart/deploy/scripts/renew-certs.sh

9. Tor onion address

./deploy/scripts/show-onion.sh

10. Complete shop setup

1. Open the CMS on clearnet or onion (/cms).
2. Log in with CMS_PASSWORD from .env.prod.
3. Finish the setup checklist in settings.
4. Connect SimpleX notifications in shop settings.

11. Updates

./deploy/scripts/update.sh

This pulls the latest code and rebuilds the stack (deploy.sh).