Deployment
To deploy a Neos application in production, you need a containerized environnement such as Docker.
Warning
Deployment is currently only maintained for use in a Kubernetes cluster using Helm. The kubernetes cluster must use INGRESS Nginx as its ingress controller. The kubernetes cluster must have Dapr deployed.
Getting started
To get started with Neos deployment, you can follow the deployment guide to deploy a Neos application in a Kubernetes cluster using Helm.
Architecture
The diagram below groups every component of a deployed Neos environment by zone: Entry (the HTTPS traffic coming from outside the namespace), Clusters (one frontend/backend/task runner pattern per cluster), Shared infra (inter-cluster communication and observability) and Data (the database server, outside the Kubernetes cluster). Each card represents a deployable component or Kubernetes resource. An application workload (a Deployment or StatefulSet) creates one or more pods depending on its replica configuration; the tags on each card list its associated Kubernetes resources. The Dapr sidecar is a container added to specific application pods, not a resource of its own, and the database server sits outside the Kubernetes cluster entirely — both are called out explicitly where they appear below. Detailed flows (service invocation, pub/sub, state store, notifications) are not repeated here — they already have their own dedicated articles, linked from the Components section below.
Ingress
Rules for the ingress controller (a separate cluster dependency, deployed and managed outside this Helm chart) — it is the controller, not these rules, that terminates TLS and routes traffic.
Authentication, tenant resolution, CORS, redirection to services.
Generates reports for every cluster (Stimulsoft license).
Tenant administration for the namespace.
License administration.
Scheduling and execution of background tasks.
Monitoring of the AI agents.
Lets support staff review errors reported by users.
Application code written by the team. 1 to N instances depending on the deployed business clusters.
Gateway handshake cache, Dapr state store and lock store, SignalR backplane.
Dapr pub/sub broker for inter-cluster communication.
Dapr sidecar
Injected into gateway, report server, backend and task runner pods — service invocation, pub/sub, state store. Frontend pods do not have it.
Not a standalone deployment: one extra container per pod.
Inter-cluster traces exported to an external backend. The collector deployment is enabled, disabled or automatic depending on the Helm configuration.
One possible backend among several (Jaeger, Application Insights, an external OTLP collector, ...) — shown here as the example backend, enabled only when configured.
Database server
Configured per tenant from Tenant Management (SQL Server, PostgreSQL or Oracle). Not a Kubernetes resource — workloads connect directly to the host and port set in the tenant's connection string.
Shared database
All tenants read and write the same tables by default. A table can be marked "multi-tenant in shared base" to get an automatic TenantId column and isolate its rows per tenant, while a table left unmarked (e.g. a shared Country list) stays visible to every tenant.
Separate database per tenant
Each tenant gets its own connection string, configured per tenant in Tenant Management (host, credentials, pooling). Full data isolation at the database level, at the cost of one connection — and one schema to migrate — per tenant.
Report storage (S3)
Optional persistence mode for generated reports, configured on the reporting server via report.S3.configurationSecret. When active, reports are uploaded as objects (reports/<TenantId>/<GenerationId>) to an AWS S3 bucket, or an S3-compatible endpoint such as MinIO. Not a Kubernetes resource.
One of three persistence modes for reports (S3, a shared filesystem volume, or a legacy fallback) — see the reporting overview for the others.
Components
Neos ecosystem consist of several components working together to provides all the functionalities of the framework.
Gateway
The gateway is the main entry point for every HTTP request coming from the outside (Web browser, API call, ...).
This component is responsible of :
- the authentication process
- the tenant resolution process for multitenant clusters
- the CORS policy configuration for cross-origin browser and mobile calls (see Gateway CORS configuration)
- redirecting the http traffic to the other components
The gateway needs a Redis instance as its distributed cache for handshake requests.
Reporting
This is the reporting server, handling neos report generation / viewer using Stimulsoft. See this article for more details.
Tenant Management
Tenant Management is a Neos cluster for tenant administration of a Kubernetes namespace. See this article for more details.
License Management
License Management is a Neos cluster handling licensing. See this article for more details.
Task Scheduler
Task Scheduler is a Neos cluster that you can use to manage tasks, schedule jobs, and ensure that tasks are executed at the right time. See this article for more details.
Neos AI
Neos AI is a Neos cluster that you can use to monitor the artificial intelligence agents. See this article for more details.
Support Center
Support Center is a Neos cluster that you can use to view errors reported by users.
Neos cluster
In a kubernetes namespace, you can deploy several Neos clusters. A Neos cluster can run the following components.
Frontend
This is a webserver serving all the frontend application (Html, Javascript, CSS, ...) to the client. See this article for more details.
Backend
This is a webserver handling most of the API calls made from the client or other clusters. See this article for more details.
Task runner
This is a webserver handling background server methods. See this article for more details.
Redis
Redis is a key-value database that Neos ecosystem use for :
- distributed cache for gateway handshake requests
- dapr workflow actor for orchestrating Neos background tasks (see this article)
- distributed cache for SignalR notification hub
- SignalR backplane for notification hub replicas (see SignalR with a Redis backplane)
- dapr state store (see this article)
RabbitMQ
RabbitMQ is a message broker which is used by Neos for pub/sub communication (see this article).
Tracing
Inter cluster communication traces can be sent external tools (see this article).
Thus, it will potentially create the following kubernetes pods :
Open telemetry collector
This pod is responsible to collect Dapr traces and send them to the external tracing server (ex: Application Insights) with the right format.
Jaeger
This pod is a Jaeger client server that can be used to see inter cluster communication traces on a web interface (see this article).
Zipkin
Warning
Zipkin is deprecated. Prefer Jaeger.
This pod is a Zipkin client server that can be used to see inter cluster communication traces on a web interface (see this article).