Deployer FAQ
Architecture
Section titled “Architecture”What services make up Prodgy?
Section titled “What services make up Prodgy?”| Service | Technology | Port | Function |
|---|---|---|---|
| API | Node.js / Express | 4000 | Core backend (auth, workflows, data) |
| Web | React / Vite | 3000 | Frontend SPA |
| Service | Node.js / BullMQ | 5000 | Async queue processing |
| Engine | Python / FastAPI / LangGraph | 8001 | AI orchestration |
| Studio | React / Vite | 5173 | Visual workflow editor |
| Gateway | Node.js / Express / MCP SDK | 3100 | MCP server for external clients |
| Agentic | Node.js / Express / AI SDK | 3200 | AI agent orchestrator |
| Assistant | C# / .NET 8 | 443/8445 | Microsoft Teams integration |
| Docs | Astro / Starlight | 4321 | Documentation |
How do services communicate?
Section titled “How do services communicate?”Via HTTP between each other, with Redis for queues and cache, and PostgreSQL (Supabase) for persistence. Inter-service authentication uses tokens via the X-Api-Key header.
What databases are used?
Section titled “What databases are used?”- PostgreSQL 15+ (Supabase) with pgvector extension for vector embeddings
- Redis 7+ with AOF persistence for queues, cache and temporary data
Requirements
Section titled “Requirements”What are the software requirements?
Section titled “What are the software requirements?”| Component | Version |
|---|---|
| Node.js | 18.0.0 or higher |
| pnpm | 8.0.0 or higher |
| Turbo | 2.0.0 or higher |
| Python | 3.13.x (Engine only) |
| Poetry | 1.8.0 or higher (Engine only) |
| .NET SDK | 8.0.x (Assistant only) |
| Docker | Latest stable version |
What are the hardware requirements?
Section titled “What are the hardware requirements?”- Dev/Staging: 4 vCPU, 8 GB RAM, 50 GB SSD
- Production: 8+ vCPU, 16+ GB RAM, 100+ GB SSD, dedicated Redis and PostgreSQL
What external dependencies are required?
Section titled “What external dependencies are required?”- AI Provider (mandatory, at least one): OpenAI, Anthropic or Google
- Email service (mandatory): SendGrid, Resend, SMTP, Microsoft 365 Graph or Google Workspace
- Teams integration (optional): Azure AD, Bot Framework, SSL certificate, Windows Server
- S3 storage: Supabase Storage or compatible
What ports are used?
Section titled “What ports are used?”- Internal: Service (5000), Gateway (3100), Agentic (3200), Engine (8001), Redis (6379), Redis Commander (8081)
- External: API (4000), Web (3000), Studio (5173), Assistant (443/8445), Docs (4321)
Environment Configuration
Section titled “Environment Configuration”What environment variables are shared?
Section titled “What environment variables are shared?”Shared variables (root level) include Supabase credentials (URL, anon key, service role key), service URLs, inter-service communication tokens, Redis connection and frontend URLs.
Does each service have its own configuration?
Section titled “Does each service have its own configuration?”Yes. Each service has specific variables:
- API: Supabase, CORS, encryption key (minimum 32 characters)
- Web: Frontend URLs, Google Tag Manager, OAuth (
VITE_prefix for public variables) - Service: Redis, queue concurrency, max retries, Engine communication
- Engine: Supabase and API credentials
- Gateway: API URL and token, MCP server port
- Agentic: API URL and token, service authentication token
- Studio: Frontend URLs, analytics, OAuth
- Assistant: JSON config file (
appsettings.Production.json) with Azure AD, Teams Bot, Redis
How do I manage secrets securely?
Section titled “How do I manage secrets securely?”- Never commit
.envorappsettings.Production.jsonto the repository - Use a secrets manager (Azure Key Vault, HashiCorp Vault)
- Generate high-entropy tokens (minimum 32 characters)
- Keep tokens unique per environment
- Rotate secrets periodically
Why are VITE_ variables public?
Section titled “Why are VITE_ variables public?”Variables with the VITE_ prefix are embedded in the frontend bundle during build and are visible in the browser. Never put secrets in these variables.
Deployment
Section titled “Deployment”How do I deploy the services?
Section titled “How do I deploy the services?”Most services use container-based deployment (Azure Container Apps, ECS, Kubernetes). Exception: the Assistant runs on a dedicated Windows VM.
What Dockerfiles are available?
Section titled “What Dockerfiles are available?”Each service has its Dockerfile in the root of its respective directory. Node.js services use node:18-alpine and the Engine uses python:3.13-slim. TypeScript must be compiled before the Docker build.
How does the CI/CD pipeline work?
Section titled “How does the CI/CD pipeline work?”The Azure DevOps pipeline supports 3 environments:
| Environment | Trigger |
|---|---|
| Development | Branch main |
| Staging | Branch staging |
| Production | Git tags v* |
The pipeline detects changes and builds only affected services.
How do I deploy the Assistant (Teams)?
Section titled “How do I deploy the Assistant (Teams)?”The Assistant requires special deployment on a Windows VM using WinRM, NSSM as service manager and deployment of compiled .NET artifacts.
What should I check after deployment?
Section titled “What should I check after deployment?”Pre-deploy:
- Environment variables configured
- Inter-service communication tokens
- Database accessible
Post-deploy:
- Health checks for each service
- Inter-service communication working
- Logs without critical errors
- Operational dashboards
Gateway and Agentic
Section titled “Gateway and Agentic”What is the Gateway?
Section titled “What is the Gateway?”The Gateway is Prodgy’s MCP (Model Context Protocol) server. It allows external MCP clients — such as Claude Code, Cursor, and Windsurf — to access Prodgy’s tools, integrations, and knowledge base via the MCP protocol over HTTP.
What is the Agentic?
Section titled “What is the Agentic?”The Agentic is Prodgy’s AI agent orchestration service. It executes agents with support for multiple LLM providers (OpenAI, Azure OpenAI, Anthropic, Google) using the Vercel AI SDK, with streaming (SSE) and direct execution endpoints.
What ports do the Gateway and Agentic use?
Section titled “What ports do the Gateway and Agentic use?”- Gateway: port 3100 (
PRODGY_GATEWAY_PORTvariable) - Agentic: port 3200 (
PRODGY_AGENTIC_PORTvariable)
Both are internal services and don’t need to be publicly exposed — communication is done via the API.
How does the Gateway authenticate with the API?
Section titled “How does the Gateway authenticate with the API?”The Gateway uses the PRODGY_API_TOKEN token via the X-Api-Key header for service calls. Additionally, each MCP request from a user carries the user’s token in the Authorization: Bearer prodgy_xxx header, allowing the API to resolve per-user permissions.
How does the Agentic authenticate?
Section titled “How does the Agentic authenticate?”The Agentic uses PRODGY_API_TOKEN to communicate with the API, and receives authenticated requests via PRODGY_AGENTIC_TOKEN in the X-API-Key header.
Does the Agentic need LLM credentials?
Section titled “Does the Agentic need LLM credentials?”Not directly. LLM providers are configured at the organization level within Prodgy. The Agentic resolves credentials automatically by querying the internal API.
Does the Gateway need Redis or a database?
Section titled “Does the Gateway need Redis or a database?”No. The Gateway is stateless — it communicates exclusively with the Prodgy API via HTTP. It requires no Redis, database, or local storage.
How do I monitor Gateway and Agentic health?
Section titled “How do I monitor Gateway and Agentic health?”Both expose a /health endpoint that can be used for health checks. Include them in the post-deploy checklist alongside the other services.
Do I need to expose the Gateway publicly?
Section titled “Do I need to expose the Gateway publicly?”The Gateway needs to be accessible by developers’ MCP clients. If developers are outside the internal network, the Gateway must be exposed via HTTPS. If they’re on the same network, it can remain internal.
Troubleshooting
Section titled “Troubleshooting”A service is not responding. What should I check?
Section titled “A service is not responding. What should I check?”- Verify the container is running
- Check environment variables (especially URLs and tokens)
- Test connectivity with Redis and PostgreSQL
- Review the service logs
Inter-service communication is failing. What should I do?
Section titled “Inter-service communication is failing. What should I do?”Verify that X-Api-Key tokens are correct and identical on both services. Confirm that service URLs are accessible on the internal network.
The Engine (AI) is slow or erroring. What should I check?
Section titled “The Engine (AI) is slow or erroring. What should I check?”Confirm AI provider credentials (OpenAI, Anthropic, Google). Check the provider’s rate limits and Supabase connectivity.
I need to scale the infrastructure. What should I consider?
Section titled “I need to scale the infrastructure. What should I consider?”- Dedicated Redis and PostgreSQL in production
- Horizontally scale stateless services (API, Web, Engine)
- Monitor CPU/RAM consumption per service
- Consider separate queues for heavy workloads on the Service