Getting Started
Deploy VyXlo CSP from zero to production. The full stack runs as 7 Docker containers with a single command. No passwords are stored in VyXlo — all identity is delegated to ZITADEL via OAuth 2.0 PKCE.
Prerequisites
Container Stack
docker compose up -d starts all 7 containers. No separate orchestration needed for development or small production deployments.
| Container | Image | Port | Role |
|---|---|---|---|
| api | Custom Python 3.12 | 8000 | FastAPI — REST, WebSocket, SSE |
| celery_worker | Same image | — | Async task execution (AI, email, cleanup) |
| celery_beat | Same image | — | Scheduled tasks (expiry, digests, retention) |
| flower | Same image | 5555 | Celery task monitoring dashboard |
| postgres | pgvector/pgvector:pg16 | 5432 | Primary DB — full-text + vector search |
| redis | redis:7-alpine | 6379 | Cache, Celery queue & result backend |
| minio | minio/minio | 9000 / 9001 | S3-compatible object storage |
Quick Start
Clone and Configure
Launch All Services
Run Database Migrations
Verify Health Endpoints
Environment Variables
Full reference available in .env.example. All required variables must be set before launching containers.
| Variable | Description |
|---|---|
| SECRET_KEY | 64-character hex secret for JWT signing |
| DATABASE_URL | PostgreSQL async connection string |
| REDIS_URL | Redis connection string |
| MINIO_ENDPOINT | MinIO host:port |
| MINIO_ACCESS_KEY | MinIO access key |
| MINIO_SECRET_KEY | MinIO secret key |
| MINIO_BUCKET_NAME | Target bucket name |
| ZITADEL_ISSUER | ZITADEL instance URL |
| ZITADEL_AUDIENCE | Expected JWT audience claim |
| ZITADEL_CLIENT_ID | OIDC client application ID |
| ALLOWED_ORIGINS | Comma-separated CORS origins |
| ENABLE_AI_FEATURES | Toggle AI pipeline (true / false) |
| AI_PROCESS_ON_UPLOAD | Auto-process on upload (true / false) |
| OPENAI_API_KEY | OpenAI key (if using OpenAI provider) |
| ANTHROPIC_API_KEY | Anthropic key (if using Anthropic provider) |
| ENABLE_EMAIL_NOTIFICATIONS | Toggle email delivery (true / false) |
Authentication — ZITADEL + PKCE
VyXlo delegates all identity management to ZITADEL using the OAuth 2.0 Authorization Code flow with PKCE. No passwords are stored inside VyXlo. All API calls require an Authorization: Bearer <access_token> header.
SSO Federation
Configure ZITADEL to federate with your existing IdP (SAML 2.0, OIDC, or LDAP/AD). Users log in once — VyXlo accepts federated tokens.
Embedded Auth
Use ZITADEL's hosted login UI in a redirect flow. VyXlo receives and validates the access token against the ZITADEL JWKS endpoint.
Service Account
For backend-to-backend integrations: provision a ZITADEL service account with a JSON key. Exchange the key for a JWT and call VyXlo APIs on behalf of a machine user.
Document Ingestion Pipeline
File upload is a two-step process: first create the metadata record (returns a document ID), then upload the file bytes. This pattern allows metadata to be created and queued before large files are transferred.
Kubernetes Deployment
Each component maps to a standard Kubernetes workload. The API and Celery worker tiers are fully stateless and horizontally scalable.
| Component | Workload | Notes |
|---|---|---|
| FastAPI API | Deployment | Stateless — scale horizontally |
| Celery Worker | Deployment | Scale by concurrency requirements |
| Celery Beat | Deployment (replicas: 1) | Single scheduler instance only |
| PostgreSQL | StatefulSet | Persistent volume required |
| Redis | StatefulSet or managed | Can use ElastiCache, Upstash, etc. |
| MinIO | StatefulSet or replace | Can replace with AWS S3 or GCS |
In This Section
/api/v1/