Skip to main content

Configure your installation

Compose reads .env for backend runtime settings and Compose substitutions. The frontend reads web/.env.frontend when its container starts. Use the templates matching your published release; never copy NuSaaS production credentials or the managed-cloud environment.

Keep private environment files and tunnel tokens outside images, restrict them to the operator and back them up encrypted. VITE_* values are public browser configuration: never put API secrets, gateway keys or database passwords there.

Required backend settings​

  • NUSAAS_VERSION: an explicitly published version for both application images.
  • APP_DEPLOYMENT=self-hosted, APP_ENV=production, APP_DEBUG=false, BILLING_ENABLED=false, PLATFORM_ADMIN_ENABLED=false. The public image also seals cloud-only features against runtime flag overrides.
  • APP_URL: public API HTTPS origin; FRONTEND_URL: public application HTTPS origin. No trailing slash or /api suffix.
  • A unique APP_KEY, JWT_SECRET, MEILISEARCH_KEY, database passwords and REVERB_APP_ID, REVERB_APP_KEY, REVERB_APP_SECRET.
  • DB_CONNECTION=mysql, DB_HOST=db, REDIS_HOST=cache, CACHE_STORE=redis, QUEUE_CONNECTION=redis, SESSION_DRIVER=redis, MEILISEARCH_HOST=http://search:7700.
  • SMTP using your provider's documented TLS settings. MAIL_MAILER=log records mail locally and will not deliver verification messages.
  • The exact frontend HTTPS origin in your CORS configuration. If using CORS_ALLOWED_ORIGIN_PATTERNS, quote the regex so a leading # is not treated as a comment.
  • TRUSTED_PROXIES: the actual trusted ingress path. Do not blindly trust arbitrary public forwarded headers.

Generate a different random value for every secret, for example:

printf 'base64:'; openssl rand -base64 32 # APP_KEY
openssl rand -hex 32                    # JWT or search secret: generate separately
openssl rand -hex 8                     # REVERB_APP_ID
openssl rand -hex 10                    # REVERB_APP_KEY
openssl rand -hex 32                    # REVERB_APP_SECRET
chmod 600 .env web/.env.frontend

Changing MySQL environment passwords after its volume initializes does not change its stored users. Preserve APP_KEY: encrypted saved credentials cannot be recovered simply by generating a new one.

Do not add INITIAL_ADMIN_* credentials to the self-hosted environment. Register the business owner through ERP onboarding. Leave SEED_DEFAULT_SUBSCRIPTION_DATA=false; no NuSaaS plans are needed.

Browser and WebSocket settings​

Set VITE_API_URL and VITE_API_BASE_URL to the API origin without /api. Keep VITE_DEPLOYMENT=self-hosted, VITE_BILLING_ENABLED=false and VITE_APP_ENV=production. Keep VITE_DOCS_URL=https://docs.nusaas.com unless you operate a different guide.

Match VITE_REVERB_APP_KEY to the backend key. Browser WebSockets use VITE_REVERB_PORT=443 and VITE_REVERB_SCHEME=wss:

  • Guided Caddy installer: VITE_REVERB_HOST=api.yourdomain.com; /app/* routes to ws:8083. Its backend REVERB_HOST=ws, port 8083, scheme http addresses Reverb internally.
  • Separate public WebSocket hostname: use VITE_REVERB_HOST=ws.yourdomain.com. Match backend REVERB_HOST, port and scheme to a reachable publishing endpoint; the base template publishes internally to ws:8083, so it does not need the public hostname to publish. Reverb itself still listens on 0.0.0.0:8083.

Update branding/support contacts. Google login, Firebase and error reporting are optional and require explicit configuration. SMS/Africa's Talking are retired; see WhatsApp for messaging.

Optional services​

Set WHATSAPP_SELF_HOSTED_URL, gateway flags and callback origin only for your own Evolution gateway. Hosted services are excluded from the public image; no hosted-service settings are needed. Cloudflare R2 and Tunnel settings use your own account and scoped credentials; D1 is not the ERP database.

Apply changes​

docker compose config --quiet
docker compose up -d --force-recreate api worker cron ws web

Use the same optional overlay arguments as your original installation. A plain restart does not reload env_file. Configuration validation does not prove that external credentials, callbacks, payments or mail work.

Customer-owned payments and KRA OSCU​

M-Pesa secrets, taxpayer identity and device credentials are entered in the ERP, not in VITE_* variables. The only KRA runtime controls are operator production authorization, disabled by default. See Business integrations and its image-version prerequisites before changing them. The distributed templates contain no NuSaaS merchant, gateway or staff credentials. Cloud-only services are sealed off by the public image and Compose configuration.