# Deployment guide

## 1. Requirements

- Ubuntu 22.04+ (or similar Linux)
- Docker Engine and Compose plugin — follow [Install Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository)
- 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](https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository).

Verify:

```bash
docker compose version
```

## 3. Clone the repository

```bash
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

```bash
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`):

```json
[
    { "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

```bash
./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):

```bash
./deploy/scripts/bootstrap-certs.sh
```

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

## 7. Start the stack

```bash
./deploy/scripts/deploy.sh
```

Wait until `backend` and `nginx` are healthy:

```bash
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`):

```bash
rm -rf deploy/certs/live/*
```

Request the real certificate:

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

Reload nginx:

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

### Automatic renewal

Open root's crontab:

```bash
crontab -e
```

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

```cron
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:

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

## 9. Tor onion address

```bash
./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

```bash
./deploy/scripts/update.sh
```

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