Table of Contents

Neos deployment guide

This article is a step-by-step guide to deploy a Neos application in a Kubernetes cluster using Helm.

Prerequisites

  • A Kubernetes cluster with INGRESS Nginx as its ingress controller.
  • Dapr deployed in the Kubernetes cluster.
  • Helm installed on your local machine.
  • Access to a container registry to push the Neos images (e.g., Docker Hub, Azure Container Registry, etc.).
  • A Neos application ready to be deployed.
  • An OpenID Connect provider for authentication (e.g., Azure AD B2C, IdentityServer, etc.) if you want to use Neos authentication features. (See the authentication documentation for more details).
  • (Optional) A domain name and TLS certificate if you want to expose the application securely.
Note

To deploy a Neos application in a Hexanet cluster, please check the Hexanet wiki for the prerequisites and instructions.

Steps

  1. Build and push the Neos cluster images to your container registry.
  2. Create secrets in your Kubernetes cluster for the Neos application (e.g., database connection string, OpenID Connect provider configuration, etc.).
  3. Configure the Helm chart values according to your environment and requirements.
  4. Deploy the Neos application using Helm.
  5. (Optional - Only for multitenant clusters) Upgrade multitenant clusters with the tenant manager if you want to host multiple tenants in the same cluster. Please check the multitenancy documentation for more details.
  6. Verify the deployment and access the application.

1 - Build and push the cluster images

Depending on your application role, you will need to build and push one or more of the following images:

  • a frontend image : the frontend is the web application that will be accessed by the users. It is responsible for rendering the user interface and handling user interactions.
  • a backend image : the backend is the application server that will handle the business logic, data processing, and communication with other services. It is responsible for processing the requests from the frontend and returning the appropriate responses. It can also be consumed by other applications or services through its API.
  • a task runner image : the task runner is a worker application that will handle background tasks, such as sending emails, processing data, etc. It is responsible for executing tasks that are not time-sensitive and can be processed asynchronously.

Please follow the instructions in the prerequisite article to build and the images.

Then push the images to your container registry and make sure to note the image names and tags, as you will need them later to configure the Helm chart values.

2 - Create secrets

Neos applications require some secrets to be stored in the Kubernetes cluster, such as database connection strings, OpenID Connect provider configuration, etc.

Please follow the instructions in the prerequisite article to create the necessary secrets in your Kubernetes cluster.

3 - Configure Helm chart values

The Neos Helm chart comes with a set of default values that you can override to customize the deployment according to your environment and requirements.

Please follow the instructions in the Helm configuration article to configure the Helm chart values.

4 - Deploy the Neos application

Please follow the instructions in the install/upgrade article to deploy the Neos application using Helm.

5 - Upgrade multitenant clusters with the tenant manager (Optional - Only for multitenant clusters)

If you are deploying a multitenant cluster, you can use the tenant manager to manage your tenants and upgrade your cluster with new tenants. Please follow the instructions in the multitenancy article for more details.

For tenant database migration and cluster version switching workflows in Tenant Management, see Tenant migration.

Note

Please consider deploying both the old and new versions of the cluster in parallel and switch the traffic to the new version once it's ready. You can use the tenant manager to manage the traffic routing between the two versions of the cluster. When every tenant is upgraded, you can decommission the old version of the cluster with a new Helm release command.

6 - Verify the deployment

After the deployment is complete, you can verify that the Neos application is running correctly by checking the status of the pods, services, and ingress in your Kubernetes cluster. You can also access the application through the configured ingress URL and verify that it is working as expected.

Please see the troubleshooting article for common issues and their solutions.

Rolling back

If you encounter any issues with the new deployment, you can roll back to the previous version using Helm rollback command. Please see the install/upgrade article for more details on how to perform a rollback.