Documentation

Installing Kovarra

Target: a fresh Ubuntu 22.04+ VPS → live, TLS-secured checkout in under 30 minutes.

What you need

A VPS (1 vCPU / 1 GB RAM is enough to start) with ports 80 and 443 open
A domain you control
10 minutes of DNS propagation time (do step 1 first)

1. Point your DNS (do this first)

At your DNS provider (e.g. Namecheap → Domain List → Manage → Advanced DNS), create two A records pointing at your VPS IP:

Type	Host	Value
A	`@`	YOUR-VPS-IP
A	`demo`	YOUR-VPS-IP

(@ serves your landing page; demo serves the payment app. You can rename the subdomain in deploy/.env later.)

2. Install Docker on the VPS

curl -fsSL https://get.docker.com | sh

3. Get the code onto the VPS

git clone <your-repo-url> payserver && cd payserver
# or: upload the folder with scp/rsync

4. Run the installer

bash deploy/install.sh

It asks for your domain, whether to run on testnets, and your TronGrid API key (free at trongrid.io — needed for USDT-on-Tron detection). It generates all secrets into deploy/.env (never committed), builds the containers, and starts:

app — API + checkout + admin
watchers — blockchain watchers, invoice expiry, webhook delivery
postgres, redis — storage
caddy — automatic HTTPS (certificates issue within ~1 minute of DNS resolving)

5. First run (2 minutes)

Open https://demo.<your-domain>/admin → set your admin password (first visit only).
Wallets → add your receiving wallet (see the wallet-setup guide). Without a wallet, invoices cannot offer that asset.
Settings → store name, brand color, logo.
Payment links → create one and open it: that is your live checkout.

Operating

cd payserver/deploy
docker compose ps                  # status
docker compose logs -f app         # follow app logs
docker compose logs -f watchers    # follow chain watchers
docker compose up -d --build       # redeploy after an update
docker compose down                # stop (data persists in volumes)

Backups: all state lives in the pgdata Docker volume. docker exec payserver-postgres-1 pg_dump -U payserver payserver > backup.sql on a cron covers you.

Switching to mainnet: edit deploy/.env → TESTNET=false, then docker compose up -d. Do a $1 real-money test first.

Troubleshooting

TLS not issuing — DNS not propagated yet, or port 80/443 blocked. docker compose logs caddy.
Invoices never confirm — check docker compose logs watchers (missing/invalid TronGrid key is the usual cause for Tron).
Rate errors on checkout — CoinGecko rate API briefly unavailable; it retries on the next asset selection.

API reference → Wallet setup → ← Back to home