Self-Host the Tracking Ingestion API
Plan and validate a customer-operated Vendo ingestion deployment on supported Node.js infrastructure.
Last reviewed September 15, 2026
Managed setup: Most workspaces should use the tracking host and snippet generated in Vendo. Self-host only when your agreement includes the ingestion package and your team can own its security, uptime, upgrades, and data routing.
The ingestion service runs as a Node.js container on the infrastructure of your choice, behind your own HTTPS reverse proxy. Vendo does not require a specific platform, concurrency, memory, scaling, or timeout value. (Vendo’s managed deployment runs on Hetzner behind Caddy at track.vendodata.com / track-staging.vendodata.com.)
Responsibilities
The operating team owns:
- TLS, DNS, capacity, availability, and incident response
- Secret storage and write-key rotation
- Authentication-provider configuration
- Warehouse permissions, schemas, retention, and cost controls
- Redis-backed features when enabled
- Logs, metrics, alerts, backups, and upgrades
- Privacy, consent, deletion, and regional requirements
Required Configuration Families
| Family | Purpose |
|---|---|
| Write-key resolution | Static key or Supabase |
| Warehouse | Project, dataset, table names, and service identity |
| Runtime | Port and deployment-specific process configuration |
| Optional Redis | Rate limiting, live events, sessions, and rules where enabled |
| Pipeline stages | Rules, schema discovery, and live-event switches |
| Admin/demo | Disabled in production unless explicitly required and separately protected |
In Supabase auth mode (SUPABASE_AUTH_ENABLED=true), the API does not start if one of these variables is missing or not correct:
| Variable | Required when | Rule |
|---|---|---|
APP_CREDENTIALS_ENCRYPTION_SECRET | Supabase auth mode | Must be set |
INGEST_ALERT_WEBHOOK_URL | Supabase auth mode and NODE_ENV=production | Must be a valid URL. In production, it must use HTTPS |
INGEST_OPS_TOKEN | Supabase auth mode and NODE_ENV=production | Must have at least 32 characters |
Use the environment-variable names and release notes shipped with the exact ingestion package version you deploy. Do not copy a production configuration from an example document.
Deployment Checklist
- Confirm the licensed package version and its release notes.
- Provision a dedicated runtime identity and minimum warehouse permissions.
- Create the required warehouse tables from the package schemas or approved setup utility.
- Store secrets in the deployment platform’s secret manager.
- Deploy a versioned, immutable image to a non-production environment.
- Configure HTTPS and the approved tracking domain.
- Test
/health, SDK serving if enabled, authentication, consent, and/collect. - Verify accepted and rejected events in the final warehouse or destination.
- Load-test the expected peak and confirm rate-limit behavior.
- Document rollback, key rotation, incident response, and upgrade ownership before production.
Authentication Modes
The API has exactly two auth modes:
- Static is appropriate only for a deliberately single-tenant deployment.
- Supabase resolves tenant write keys through Supabase, the sole write-key control plane. (The former Firebase and dual modes were retired.)
Provider service credentials stay on the server. Never expose them in the browser snippet.
Verify Every Release
For each upgrade, test these cases:
- A page, track, identify, group, and alias payload
- Malformed input
- An invalid key
- Consent denied
- A retry
- A duplicate event
Compare results with the previous version before shifting production traffic.