Installation guide

This guide covers the full path from purchasing an on-premise license on the Veilio SaaS to running a self-hosted instance with Docker and a license.jwt file.

Two separate planes

• Control plane = the Veilio SaaS (app.veilio.xyz). You sign up here, pay via Stripe, and download your license and deployment kit. Veilio never sees your tokenized data.
• Your on-premise instance = what you deploy on your own servers. It contains only the public key and validates the license offline. No business data leaves your infrastructure.

---

1. Prerequisites (your server)

Before deploying on your infrastructure, make sure you have:

• Docker ≥ 24 and Docker Compose ≥ 2.20
• 2 CPUs, 2 GB RAM minimum
• A Linux host (or VM) with outbound HTTPS access only if you want automatic license renewal or the in-app update banner (optional)
• No Docker registry login — the application image is public on Docker Hub (veilio/app:latest)

You will obtain license.jwt and the deployment kit from the Veilio SaaS — see section 2.

---

2. Purchase workflow (Veilio SaaS)

Everything in this section happens on the control plane (the Veilio web app), not on your on-premise server.

2.1 Create your account

1. Open app.veilio.xyz and click Sign up.
2. Register with your work email and set a password.
3. Confirm your email if prompted, then sign in.

You do not need a cloud (SaaS) subscription to buy an on-premise license. On-premise is a separate product, purchased from Billing.

2.2 Buy an on-premise license

1. Go to Dashboard → Billing (/dashboard/billing).
2. Scroll to the Veilio On-Premise block.
3. Choose an annual license:

Plan	Price (excl. tax)	Best for
On-Premise Standard	€1,690 / year	Teams with annual quotas (users, tokens, API requests)
On-Premise Pro	€2,990 / year	High-volume deployments with no token or request caps

1. Click Start 1-month free trial on the plan you want.
2. Enter your company name (embedded in the signed license).
3. Complete Stripe checkout. A card is required, but you are not charged during the 1-month trial.

2.3 What you receive after purchase

Source	Content
Email	license.jwt attached to the delivery email
Email (optional)	vlr_... refresh token for automatic license renewal (shown once — save it)
Billing page	Download deployment kit and Download my license buttons

The first delivery is a trial license (30 days). When the trial ends and Stripe confirms payment, you receive a full annual license by email.

2.4 Download the deployment kit and license

1. Download deployment kit → veilio-onpremise-kit.zip containing docker-compose.yml, .env.onpremise.example, README.md
2. Download my license → license.jwt

license.jwt is not inside the zip. Place it in the veilio/ folder next to docker-compose.yml on your server.

2.5 Prepare files on your server

unzip veilio-onpremise-kit.zip && cd veilio-onpremise
mkdir -p veilio
cp ~/Downloads/license.jwt veilio/license.jwt

---

3. Configure the environment

cp .env.onpremise.example .env

Edit .env and set at least:

Variable	Description
DB_PASSWORD	Strong PostgreSQL password
ENCRYPTION_KEY	openssl rand -base64 32 — back it up: without it, tokens cannot be recovered
NEXTAUTH_SECRET	openssl rand -base64 32
APP_URL	Public URL (e.g. https://veilio.acme.internal)
VEILIO_IMAGE	Docker image (default: veilio/app:latest)
SMTP_HOST / SMTP_PORT / SMTP_FROM	Outbound email
BOOTSTRAP_EMAIL / BOOTSTRAP_PASSWORD	First admin on empty database
VEILIO_LICENSE_FILE	Default: /veilio/license.jwt (file mode)
VEILIO_LICENSE_KEY	Full JWT inline (Coolify / secret managers) — overrides file
VEILIO_CRON_SECRET	Bearer secret for internal jobs (auto-shred). Required if you use retention / TTL. Generate with openssl rand -base64 32

Automatic renewal (optional):

Variable	Description
VEILIO_LICENSE_AUTO_REFRESH	true to enable
VEILIO_LICENSE_CONTROL_PLANE_URL	https://app.veilio.xyz
VEILIO_LICENSE_REFRESH_TOKEN	vlr_... from delivery email
VEILIO_LICENSE_REFRESH_THRESHOLD_DAYS	Default 45

---

4. Configure the license

Option A — File (default)

VEILIO_LICENSE_FILE=/veilio/license.jwt
mkdir -p veilio && cp ~/Downloads/license.jwt veilio/license.jwt

For auto-refresh persistence, mount ./veilio read-write (remove :ro in docker-compose.yml).

Option B — Environment variable (Coolify, PaaS)

VEILIO_LICENSE_KEY=eyJ...full_jwt_content...
# do not set VEILIO_LICENSE_FILE

---

5. Start

docker compose up -d

On startup the instance: applies migrations, verifies the license, creates bootstrap admin if configured, and optionally refreshes the license.

---

6. Check status

curl -s http://localhost:3000/api/health?db=1 | jq

For license details, send header X-Metrics-Secret with your METRICS_SECRET value.

SDK / API base URL for your instance: https://your-domain.com/api

---

7. Retention & auto-shred (required if you use TTL)

If your apps pass retention.ttlDays or retention.retentionUntil when tokenizing, you must schedule the auto-shred job yourself. Setting retention alone does not destroy data.

1. Set VEILIO_CRON_SECRET in .env and restart the app if needed.
2. Schedule an hourly call (crontab, systemd timer, or your orchestrator):

curl -fsS -X POST "https://your-domain.com/api/internal/tokens/auto-shred?limit=500" \
  -H "Authorization: Bearer $VEILIO_CRON_SECRET"

1. Confirm a 200 JSON response with a processed field.

Full details: Data Lifecycle: Retention and Crypto Shredding.

---

8. Update the application

docker compose pull && docker compose up -d

PostgreSQL volumes and license.jwt are preserved.

---

9. Create an admin manually (alternative)

docker compose exec veilio-app pnpm onpremise:seed-admin -- \
  --email [e-mail] --password 'ChangeMe123!' --company "Acme"

---

10. Coolify deployment

1. New Resource → Docker Compose (image on Docker Hub, do not build from Git).
2. Deploy the kit's docker-compose.yml.
3. Set environment variables (section 3), including VEILIO_CRON_SECRET if you use retention.
4. Set VEILIO_LICENSE_KEY as a secret (option B, section 4).
5. Assign domain to veilio-app, port 3000.
6. APP_URL = Coolify HTTPS URL.
7. Configure an external cron / Coolify scheduled job for auto-shred (section 7).

Verify: curl -s https://your-domain/api/health?db=1

---

License lifecycle

State	Behavior
Valid	Everything works
30 days before expiry	Warning banner + health: expiring_soon
Expired (0–30 days)	Grace period: read-only, no new tokens
Expired > 30 days	Instance refuses to start

Automatic renewal — add to .env:

VEILIO_LICENSE_AUTO_REFRESH=true
VEILIO_LICENSE_CONTROL_PLANE_URL=https://app.veilio.xyz
VEILIO_LICENSE_REFRESH_TOKEN=vlr_...

Manual swap (air-gap):

cp ~/Downloads/license.jwt veilio/license.jwt
docker compose restart veilio-app

Re-download anytime from Dashboard → Billing → Download my license.

---

Backups

You must back up:

• Both PostgreSQL volumes (veilio-data, clients-data)
• The ENCRYPTION_KEY variable (off-server, in a secrets vault)
• VEILIO_CRON_SECRET (same vault — rotating it without updating the cron job breaks auto-shred)

---

TLS / reverse proxy (recommended)

Terminate HTTPS in front of the container:

# nginx example
location / {
  proxy_pass http://127.0.0.1:3000;
  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-Proto https;
}

Set APP_URL to your public HTTPS URL.