From bcbe3fa1124ec3c05b280a2dcc4185480bf8f867 Mon Sep 17 00:00:00 2001 From: Wyatt Walter Date: Thu, 14 May 2026 16:54:12 -0500 Subject: [PATCH 01/11] docs: add Helm chart reference, MongoDB Operator guide, and rework Kubernetes install page Add two new documentation pages and significantly rework the Kubernetes installation guide to reflect current best practices. New pages: - Helm Chart reference covering deployment planning decisions (storage, workload type, MongoDB, Redis, PostgreSQL) and community edition config - MongoDB Kubernetes Operator guide with install, configuration, migration from Bitnami, and troubleshooting Kubernetes install guide changes: - Rewrite intro with deployment planning link and HA guidance - Replace vague system requirements with specific resource breakdown - Remove outdated video embed - Add MongoDB Operator and ingress config to default values.yaml - Pin image version instead of using latest tag - Remove separate Community edition section (moved to Helm Chart page) - Rename "Post-installation configuration" to "Next steps" - Add TLS and uninstall cards to next steps Co-Authored-By: Claude Opus 4.6 --- .../installation-guides/kubernetes/README.mdx | 149 ++++---- .../instance-configuration/helm-chart.md | 85 +++++ .../mongodb-kubernetes-operator.md | 349 ++++++++++++++++++ website/sidebars.js | 2 + 4 files changed, 521 insertions(+), 64 deletions(-) create mode 100644 website/docs/getting-started/setup/instance-configuration/helm-chart.md create mode 100644 website/docs/getting-started/setup/instance-configuration/mongodb-kubernetes-operator.md diff --git a/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx b/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx index 1c34e24c06..296cd82246 100644 --- a/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx +++ b/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx @@ -8,107 +8,128 @@ import TabItem from "@theme/TabItem"; # Kubernetes (k8s) -This page provides steps to install Appsmith on a Kubernetes cluster using the [Helm](https://helm.sh) package manager. +This page provides steps to install Appsmith on a Kubernetes cluster using the [Helm](https://helm.sh) package manager. The default installation runs a single replica and is a good starting point for getting Appsmith running. If you need high availability with multiple replicas, review the [deployment planning guide](/getting-started/setup/instance-configuration/helm-chart#planning-your-deployment) before installing — some decisions require a migration to change later. - +## Requirements -## System requirements +### Kubernetes cluster -- At least 15 GB of free storage space. -- 8 GB of RAM. +- A running Kubernetes cluster (1.33+). +- Appsmith application pods need at least **6 GB of memory** and benefit from **2 vCPUs**. MongoDB, Redis, PostgreSQL, and other chart dependencies consume additional resources, and the cluster itself has overhead for system components (kube-proxy, monitoring agents, ingress controllers, etc.). Plan for a minimum of **2 nodes with 2 vCPUs and 8 GB of memory each**. +- A default `StorageClass` capable of provisioning persistent volumes. Most managed Kubernetes services (EKS, GKE, AKS) provide this out of the box. +- An Ingress controller (such as [Traefik](https://doc.traefik.io/traefik/providers/kubernetes-ingress/) or an AWS/GCP load balancer controller) or a `LoadBalancer`-type Service to expose Appsmith to users. +- Outbound network access to `cs.appsmith.com` for license validation and updates. -## Prerequisites +If you are setting up a new cluster on AWS, see [Set up Kubernetes cluster on AWS-EKS](/getting-started/setup/installation-guides/kubernetes/setup-kubernetes-cluster-aws-eks). -1. Install Helm package manager on your local machine. See the official Helm documentation for your [operating system](https://helm.sh/docs/intro/install/#through-package-managers). -2. Install and configure `kubectl` to interact with your Kubernetes cluster. Follow the below guides available on the official Kubernetes documentation for instructions on how to install `kubectl` on your specific operating system: - - [MacOS using Homebrew](https://kubernetes.io/docs/tasks/tools/install-kubectl-macos/#install-with-homebrew-on-macos) - - [Linux using native package management](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/#install-using-native-package-management) - - [Windows using Chocolatey, Scoop, or winget](https://kubernetes.io/docs/tasks/tools/install-kubectl-windows/#install-nonstandard-package-tools). -3. Set up a Kubernetes cluster and persistent volume on your preferred platform for hosting the Kubernetes cluster. If you are hosting the Kubernetes cluster on AWS-EKS, see [Set up Kubernetes cluster on AWS-EKS](/getting-started/setup/installation-guides/kubernetes/setup-kubernetes-cluster-aws-eks) -4. Whitelist `cs.appsmith.com` in your firewall or security group’s outbound rules to ensure proper connectivity to required services. +### Client machine -:::caution -A persistent volume configuration is required on the Kubernetes cluster before proceeding with the Appsmith installation. -::: +- [Helm 3.14+](https://helm.sh/docs/intro/install/) — the Helm package manager. +- [`kubectl`](https://kubernetes.io/docs/tasks/tools/) — configured to connect to your cluster. ## Install Appsmith Follow these steps to install Appsmith: -1. Create a folder named `appsmith` on your machine for deployment and data storage. Then, navigate to this folder using the `cd` command. - -2. Add the Appsmith chart repository with: +1. Add the Appsmith chart repository: ```bash helm repo add appsmith-ee https://helm-ee.appsmith.com + helm repo update ``` -3. Load the Appsmith chart repository with: +2. Look up the latest Appsmith release version: ```bash - helm repo update + APPSMITH_VERSION=$(curl -s https://api.github.com/repos/appsmithorg/appsmith/releases/latest | jq -r '.tag_name') + echo $APPSMITH_VERSION ``` -4. Generate the `values.yaml` file with: +3. Create a `values.yaml` file with the following content: - ```bash - helm show values appsmith-ee/appsmith > values.yaml + ```yaml + image: + tag: # paste the version from step 2 (e.g. v1.99) + + mongodb: + enabled: false + + mongodbCommunity: + enabled: true + + mongodbOperator: + enabled: true + + ingress: + enabled: true + className: "" # leave blank for the cluster default, or set to your controller (e.g. traefik, alb) + hosts: + - host: appsmith.example.com ``` -5. Run the below command to deploy Appsmith: + Replace `appsmith.example.com` with your domain and set `className` to match your Ingress controller. This configures the chart to use the [MongoDB Kubernetes Operator](/getting-started/setup/instance-configuration/mongodb-kubernetes-operator) instead of the legacy Bitnami MongoDB subchart. For TLS configuration, see [Configure TLS](/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online). + +4. Deploy Appsmith: ```bash - helm install appsmith-ee appsmith-ee/appsmith -n appsmith-ee --create-namespace -f values.yaml + helm install appsmith-ee appsmith-ee/appsmith \ + -n appsmith-ee --create-namespace \ + -f values.yaml ``` -6. Get pod name with: +5. Wait for the pods to be ready: ```bash kubectl get pods -n appsmith-ee ``` - The above command displays the status of the pods. Proceed to the next step once the pod status is shown as _RUNNING_. + Proceed once all pods show `Running`. -7. To access and verify the installation locally, use the below command that forwards the port 8080 to port 80: +6. If your ingress and DNS are already configured, open `https://appsmith.example.com`. Otherwise, use port-forward to verify the installation locally: ```bash - kubectl --namespace appsmith-ee port-forward appsmith-ee-0 8080:80 + kubectl -n appsmith-ee port-forward appsmith-ee-0 8080:80 ``` - In the above command, `appsmith-ee-0` is the Appsmith pod name. + Open [http://localhost:8080](http://localhost:8080) and wait for the server to come up. This can take up to 5 minutes. -8. Open [http://localhost:8080](http://localhost:8080) and wait for the server to come up. This can take up to 5 minutes. Once the server is up and running, you can access Appsmith at [http://localhost:8080](http://localhost:8080). +7. Fill in your details to create an administrator account. -9. Fill in your details to create an administrator account. +8. Once you've created an account, you can either start with the free plan or activate your instance with a license key. If you want to generate a license key, sign up on [customer.appsmith.com](https://customer.appsmith.com) to create one, and then proceed to activate your instance using the newly generated license key. -10. Once you've created an account, you can either start with the free plan or activate your instance with a license key. If you want to generate a license key, sign up on [customer.appsmith.com](https://customer.appsmith.com) to create one, and then proceed to activate your instance using the newly generated license key. +## Next steps -For high availability and scalability configuration, see the [Configure High Availability and Scalability](/getting-started/setup/installation-guides/kubernetes/configure-high-availability) guide. If you are migrating an existing single-pod installation to HA, see [Migrate Helm deployment from non-HA to HA](/getting-started/setup/installation-guides/kubernetes/migrate-non-ha-to-ha-helm). To expose Appsmith installation on the internet, see the [Expose K8s to Internet](/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online) guide. +Appsmith is running and accessible via your ingress. Explore other guides below to secure and customize your deployment. -## Install Appsmith Community - -To install the Appsmith open source edition (Appsmith Community): - -1. Use the open source helm chart by running the below command which adds the Appsmith chart repository: - -```bash -helm repo add appsmith https://helm.appsmith.com -``` - -2. Replace `appsmith-ee` with `appsmith` in the commands on this page. +
+ +
+
+ Configure TLS +
+
+
+
+ Set up TLS certificates for your Appsmith ingress using cert-manager or your own certificates. +
+ -## Post-installation configuration + +
+
+ Helm Chart Reference +
+
+
+
+ Deployment planning, database options, and chart configuration reference. +
+ +
-Once you have completed the installation process, consider performing the tasks below to configure and manage your Appsmith instance, enhancing its security and performance, specifically if it's intended for production use. -
@@ -118,45 +139,45 @@ Once you have completed the installation process, consider performing the tasks
- Configure high availability and scalability for your Appsmith deployment on Kubernetes to ensure uninterrupted access to your applications. + Configure multiple replicas and shared storage for high availability.
- +
- Expose K8s to Internet + Configure Single Sign-on (SSO)
- Configure your Appsmith Kubernetes installation to be accessible from the internet, enabling remote access and usage. + Enable SSO to allow users to log in using your identity provider.
- +
- Configure Single Sign-on (SSO) + Configure Email Service
- Enable SSO to allow users to log in using your identity provider. Appsmith supports multiple SSO providers through SAML and OpenID protocols. + Set up an email service to enable notifications and alerts.
- +
- Configure Email Service + Uninstall Appsmith
- Set up an email service to enable Appsmith to send notifications and alerts. You can use providers such as AWS SES, Gmail, or others. + Learn how to remove Appsmith resources from your cluster and start fresh.
diff --git a/website/docs/getting-started/setup/instance-configuration/helm-chart.md b/website/docs/getting-started/setup/instance-configuration/helm-chart.md new file mode 100644 index 0000000000..c7eb7e03a7 --- /dev/null +++ b/website/docs/getting-started/setup/instance-configuration/helm-chart.md @@ -0,0 +1,85 @@ +--- +description: Helm chart architecture decisions, features, and configuration reference for Appsmith on Kubernetes. +toc_max_heading_level: 3 +--- + +# Helm Chart + +The Appsmith Helm chart is the recommended way to deploy and manage Appsmith on Kubernetes. For an overview of Appsmith's components and how they fit together, see [Deployment Architecture](/getting-started/setup/deployment-architecture). For the full list of configurable values, see the [chart README](https://github.com/appsmithorg/appsmith/tree/release/deploy/helm#parameters). + +## Planning your deployment + +Some choices are easy to change after installation — resource limits and environment variables are a `helm upgrade` away. Others require a migration to change because they affect where data is stored. + +Review the decisions below before your first `helm install`. + +| Decision | Default | Migration required to change? | +|---|---|---| +| [Storage and workload type](#storage-and-workload-type) | StatefulSet with a single replica | **Yes** — volume migration and workload recreation | +| [MongoDB](#mongodb) | Bitnami subchart | **Yes** — data export/import between MongoDB deployments | +| [Redis](#redis) | Bitnami subchart | No — Redis data is ephemeral | +| [PostgreSQL](#postgresql) | Bitnami subchart | Yes — Keycloak data migration needed | + +### Storage and workload type + +In addition to its databases, Appsmith persists data to files on disk — logs and other runtime state. The workload type and storage configuration are tightly coupled, and together they determine how volumes are provisioned and whether you can run multiple replicas. + +The chart supports two workload modes, each with different storage behavior: + +**StatefulSet (default)** — runs a single replica with its own persistent volume. The pod is replaced in place during upgrades and configuration changes, preserving the same volume. This is the simplest option and works out of the box with most clusters' default block storage `StorageClass` (EBS `gp3`, GCE PD, Azure Disk), but is restricted to a single replica. + +**Deployment** — use this when you need high availability with multiple replicas. Set `workload.kind: Deployment` or enable `autoscaling.enabled`. In this mode, all pods mount the same volume, so you need shared storage (`ReadWriteMany`) backed by AWS EFS, GCP Filestore, Azure Files, or NFS. + +| Configuration | Workload | Storage | Replicas | Values | +|---|---|---|---|---| +| **Single replica** (recommended starting point) | StatefulSet | Block storage (`ReadWriteOnce`) — typically the cluster default | 1 | Defaults work out of the box | +| **Multi-replica / HA** | Deployment | Shared filesystem (`ReadWriteMany`) — [AWS EFS](https://docs.aws.amazon.com/eks/latest/userguide/efs-csi.html), [GCP Filestore](https://cloud.google.com/filestore/docs/csi-driver), Azure Files, NFS | 2+ | `workload.kind: Deployment`, `persistence.storageClass: ` | +| **Existing claim** | Deployment | Pre-provisioned PVC | 1+ | `workload.kind: Deployment`, `persistence.existingClaim.enabled: true`, `persistence.existingClaim.claimName: ` | + +Changing the storage backend or switching between StatefulSet and Deployment on an existing release requires a migration — recreating volumes and the workload resource. See [Migrate to High Availability](/getting-started/setup/installation-guides/kubernetes/migrate-non-ha-to-ha-helm) for the procedure. Plan this before your first install. + +### MongoDB + +MongoDB is Appsmith's primary data store. The chart supports three approaches, and **new installations should use the MongoDB Kubernetes Operator**: + +| Option | Status | When to use | +|---|---|---| +| **MongoDB Kubernetes Operator** (recommended) | Available since chart 3.7.0 | **New installations.** Uses the official [MongoDB Kubernetes Operator](https://github.com/mongodb/mongodb-kubernetes) for operator-managed lifecycle, credential management, and version upgrades. | +| **Bitnami subchart** (default) | Being phased out | Existing installations that haven't migrated yet. The upstream Bitnami MongoDB images have been deprecated by their publisher. | +| **External MongoDB** | Stable | Managed services (Atlas) or self-managed MongoDB outside the cluster. | + +For a complete walkthrough of the MongoDB Operator, see the [MongoDB Kubernetes Operator](/getting-started/setup/instance-configuration/mongodb-kubernetes-operator) guide. If you have an existing install using the Bitnami subchart, see [Migrate from Bitnami to MongoDB Operator](/getting-started/setup/instance-configuration/mongodb-kubernetes-operator#migrate-from-bitnami-subchart) for the migration procedure. + +### Redis + +Redis is used for session storage and caching. The chart bundles Redis by default (`redis.enabled: true`) and runs it in the cluster alongside Appsmith. You can also bring your own Redis — for example, a cloud-managed service like AWS ElastiCache — by disabling the bundled instance and setting `APPSMITH_REDIS_URL` in `applicationConfig`. + +Redis data is ephemeral, so switching between bundled and external doesn't require a data migration. + +### PostgreSQL + +PostgreSQL is used by Keycloak for identity management. The chart bundles PostgreSQL by default (`postgresql.enabled: true`) and runs it in the cluster alongside Appsmith. You can also bring your own PostgreSQL — for example, Amazon RDS or Azure Database for PostgreSQL — by disabling the bundled instance and configuring the Keycloak database connection via `applicationConfig`. + +Switching to an external PostgreSQL on an existing install requires migrating Keycloak's data. + +## Community edition + +The community and enterprise editions use the same Helm chart. To install the community edition, set the image repository in your `values.yaml`: + +```yaml +image: + repository: appsmith/appsmith-ce +``` + +The enterprise image (`appsmith/appsmith-ee`) is used by default. You can run the enterprise image on a free plan without a license key — the community image is only needed if you prefer to run the open source edition. + +## Values reference + +The full list of chart parameters is maintained in the [chart README](https://github.com/appsmithorg/appsmith/tree/release/deploy/helm#parameters). The README is auto-generated from annotated comments in `values.yaml` to stay in sync with each chart release. + +## See also + +- [MongoDB Kubernetes Operator](/getting-started/setup/instance-configuration/mongodb-kubernetes-operator) — Install guide, configuration, and migration from Bitnami. +- [Kubernetes Installation Guide](/getting-started/setup/installation-guides/kubernetes) — Step-by-step install for Appsmith on Kubernetes. +- [Environment Variables](/getting-started/setup/environment-variables) — Application-level configuration reference. +- [High Availability Setup](/getting-started/setup/installation-guides/kubernetes/configure-high-availability) — Configure HA on AWS EKS. diff --git a/website/docs/getting-started/setup/instance-configuration/mongodb-kubernetes-operator.md b/website/docs/getting-started/setup/instance-configuration/mongodb-kubernetes-operator.md new file mode 100644 index 0000000000..2384b91a36 --- /dev/null +++ b/website/docs/getting-started/setup/instance-configuration/mongodb-kubernetes-operator.md @@ -0,0 +1,349 @@ +--- +description: Install and configure Appsmith with the MongoDB Kubernetes Operator, or migrate from the Bitnami MongoDB subchart. +toc_max_heading_level: 3 +--- + +# MongoDB Kubernetes Operator + +*Available since chart version 3.7.0* + +The MongoDB Kubernetes Operator is the recommended way to run MongoDB for new Appsmith installations. It replaces the legacy Bitnami MongoDB subchart with an operator-managed replica set backed by the official [MongoDB Kubernetes Operator](https://github.com/mongodb/mongodb-kubernetes). + +## Why use the operator + +- **Actively maintained** — the Bitnami MongoDB images have been deprecated by their publisher. The operator uses official MongoDB images with ongoing support. +- **Operator-managed lifecycle** — a dedicated controller handles replica set membership, SCRAM credential lifecycle, and version upgrades. +- **Automatic connection wiring** — the operator creates and maintains the connection-string Secret that Appsmith consumes. No manual URL assembly required. + +## How the chart integrates the operator + +When `mongodbCommunity.enabled: true`, the chart: + +- Renders a `MongoDBCommunity` custom resource that the operator reconciles into a replica set +- Runs an idempotent pre-install Job that generates a random password and stores it in a Kubernetes Secret (unless you supply your own) +- Wires the Appsmith workload to read MongoDB's connection string from the operator-managed Secret + +When `mongodbOperator.enabled: true` (recommended), the chart also pulls the upstream `mongodb-kubernetes` chart as a subchart, installing the operator pod and required CRDs in the same namespace. + +## Fresh installation + +### Prerequisites + +- Kubernetes 1.28+ +- Helm 3.14+ +- A `StorageClass` available for MongoDB PVCs (uses the cluster default unless overridden via `mongodbCommunity.persistent.storageClass`) + +### Install + +```bash +helm repo add appsmith https://helm.appsmith.com +helm repo update + +kubectl create namespace appsmith + +helm install appsmith appsmith/appsmith -n appsmith --wait --timeout 10m \ + --set mongodb.enabled=false \ + --set mongodbCommunity.enabled=true \ + --set mongodbOperator.enabled=true +``` + +| Flag | Purpose | +|---|---| +| `mongodb.enabled=false` | Disables the legacy Bitnami MongoDB subchart | +| `mongodbCommunity.enabled=true` | Deploys a `MongoDBCommunity` CR for the operator to reconcile | +| `mongodbOperator.enabled=true` | Installs the MongoDB Kubernetes Operator in the same namespace | + +### Verify + +```bash +kubectl get pods -n appsmith +kubectl get mongodbcommunity -n appsmith +``` + +You should see the operator pod, MongoDB pod(s), and the `MongoDBCommunity` resource in a `Running` phase. + +### Access the UI + +```bash +kubectl port-forward -n appsmith svc/appsmith 8080:80 +``` + +Open http://localhost:8080. For production access, configure an Ingress — see [Expose Appsmith](/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online). + +## Configuration + +### Password management + +When `mongodbCommunity.auth.passwordSecretName` is empty (the default), the chart's pre-install Job generates a random password. To manage passwords yourself, create a Secret with a `password` key and reference it: + +```bash +kubectl create secret generic my-mongodb-secret \ + -n appsmith \ + --from-literal=password='your-password' +``` + +```yaml +mongodbCommunity: + auth: + passwordSecretName: my-mongodb-secret +``` + +The chart skips the pre-install Job when a Secret name is provided. + +To retrieve the auto-generated password: + +```bash +kubectl get secret appsmith-mongo-password -n appsmith \ + -o jsonpath='{.data.password}' | base64 -d +``` + +### Production sizing + +The defaults are tuned for evaluation — a single-member replica set with modest storage. For production, scale to three members and pin resources: + +```yaml +mongodbCommunity: + enabled: true + members: 3 + persistent: + storageSize: 100Gi + storageClass: gp3 + resources: + requests: + cpu: 500m + memory: 2Gi + limits: + memory: 4Gi +``` + +Scaling from 1 to 3 members after the initial install is a value change on upgrade — the operator handles adding members to the replica set without downtime. + +### Namespace scope + +Setting `mongodbOperator.enabled: true` installs the operator in the same namespace as Appsmith. If you manage the operator separately (for example, a cluster-wide install), leave this `false` and ensure the operator has RBAC access to the release namespace. + +### Deploying with ArgoCD + +The bundled operator path works with ArgoCD because the CRDs live in the upstream chart's `crds/` directory — Helm and ArgoCD install them before any templates are validated. + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: appsmith + namespace: argocd +spec: + project: default + source: + repoURL: https://helm.appsmith.com + chart: appsmith + targetRevision: "" + helm: + valuesObject: + mongodb: + enabled: false + mongodbCommunity: + enabled: true + mongodbOperator: + enabled: true + destination: + server: https://kubernetes.default.svc + namespace: appsmith + syncPolicy: + automated: {} + syncOptions: + - CreateNamespace=true +``` + +## Uninstall + +Delete the `MongoDBCommunity` resource first so the operator can process its finalizer, then uninstall the release: + +```bash +# 1. Delete the CR and wait for the operator to clear its finalizer +kubectl delete mongodbcommunity -n appsmith --all --wait=true + +# 2. Uninstall Appsmith (and the bundled operator) +helm uninstall appsmith -n appsmith + +# 3. Remove the namespace +kubectl delete namespace appsmith +``` + +:::caution +Skipping step 1 can leave the `MongoDBCommunity` resource stuck with an unresolved finalizer, which blocks namespace deletion. If that happens, clear it manually: + +```bash +kubectl patch mongodbcommunity -n appsmith \ + --type=merge -p '{"metadata":{"finalizers":[]}}' +``` +::: + +The MongoDB CRDs installed by the subchart persist after uninstall (Helm never removes resources from `crds/`). To fully clean up: + +```bash +kubectl delete crd mongodbcommunity.mongodbcommunity.mongodb.com +kubectl delete crd mongodb.mongodb.com +kubectl delete crd mongodbusers.mongodb.com +``` + +:::caution +Deleting these CRDs removes all matching resources across the cluster — only do this if nothing else relies on the operator. +::: + +## Migrate from Bitnami subchart + +If you have an existing Appsmith install using the Bitnami MongoDB subchart, follow this procedure to move to the MongoDB Operator. The migration exports your data from the Bitnami-managed MongoDB and imports it into the operator-managed instance. + +:::caution +Test this procedure on a non-production cluster first. The migration involves a brief downtime window while Appsmith is restarted with the new MongoDB connection. +::: + +### Overview + +1. Scale down Appsmith to stop writes +2. Export data from the Bitnami MongoDB +3. Deploy the MongoDB Operator alongside the existing release +4. Import data into the operator-managed MongoDB +5. Switch Appsmith to the new MongoDB and verify +6. Clean up the Bitnami MongoDB resources + +### Step 1: Scale down Appsmith + +Stop the Appsmith workload to prevent writes during the migration: + +```bash +kubectl scale statefulset appsmith -n appsmith --replicas=0 +``` + +Wait for all Appsmith pods to terminate before proceeding. + +### Step 2: Export data from Bitnami MongoDB + +Identify the Bitnami MongoDB pod and run `mongodump`: + +```bash +# Find the primary MongoDB pod +kubectl get pods -n appsmith -l app.kubernetes.io/name=mongodb + +# Run mongodump inside the pod +kubectl exec -n appsmith appsmith-mongodb-0 -- \ + mongodump --uri="mongodb://root:password@localhost:27017" \ + --archive=/tmp/appsmith-dump.gz --gzip + +# Copy the dump to your local machine +kubectl cp appsmith/appsmith-mongodb-0:/tmp/appsmith-dump.gz ./appsmith-dump.gz +``` + +:::tip +If your Bitnami MongoDB uses a non-default root password, retrieve it from the existing Secret: + +```bash +kubectl get secret appsmith-mongodb -n appsmith \ + -o jsonpath='{.data.mongodb-root-password}' | base64 -d +``` +::: + +### Step 3: Deploy the MongoDB Operator + +Upgrade the release to enable the MongoDB Operator alongside the existing Bitnami instance. Appsmith remains scaled to zero during this step: + +```bash +helm upgrade appsmith appsmith/appsmith -n appsmith --wait --timeout 10m \ + --reuse-values \ + --set mongodbCommunity.enabled=true \ + --set mongodbOperator.enabled=true +``` + +Wait for the operator-managed MongoDB to reach a `Running` phase: + +```bash +kubectl get mongodbcommunity -n appsmith -w +``` + +### Step 4: Import data into operator-managed MongoDB + +Retrieve the operator-managed MongoDB password: + +```bash +MONGO_PASS=$(kubectl get secret appsmith-mongo-password -n appsmith \ + -o jsonpath='{.data.password}' | base64 -d) +``` + +Copy the dump file into the new MongoDB pod and restore: + +```bash +# Copy dump to the operator-managed pod +kubectl cp ./appsmith-dump.gz appsmith/appsmith-mongo-0:/tmp/appsmith-dump.gz + +# Restore into the new instance +kubectl exec -n appsmith appsmith-mongo-0 -- \ + mongorestore --uri="mongodb://appsmith:${MONGO_PASS}@localhost:27017/appsmith?authSource=appsmith" \ + --archive=/tmp/appsmith-dump.gz --gzip --drop +``` + +### Step 5: Switch Appsmith to the new MongoDB + +Upgrade the release to disable the Bitnami subchart. Helm will scale Appsmith back to its configured replica count: + +```bash +helm upgrade appsmith appsmith/appsmith -n appsmith --wait --timeout 10m \ + --reuse-values \ + --set mongodb.enabled=false +``` + +Verify Appsmith starts successfully and you can log in with existing credentials. Check the logs for any database connection errors: + +```bash +kubectl logs -n appsmith appsmith-0 --tail=50 +``` + +### Step 6: Clean up + +Once you've verified the migration is successful, remove the old Bitnami MongoDB PVCs: + +```bash +# List PVCs from the old Bitnami MongoDB +kubectl get pvc -n appsmith -l app.kubernetes.io/name=mongodb + +# Delete them after confirming the new MongoDB is working +kubectl delete pvc -n appsmith -l app.kubernetes.io/name=mongodb +``` + +## Troubleshooting + +### `MongoDBCommunity` CR stays in `Pending` phase + +Check the operator logs: + +```bash +kubectl logs -n appsmith -l app.kubernetes.io/name=mongodb-kubernetes-operator --tail=50 +``` + +Common causes: the password Secret doesn't exist (if you set `passwordSecretName`, verify the Secret is present with a `password` key), or the MongoDB image can't be pulled. + +### Appsmith pod stuck in `Init` + +The init container waits for MongoDB to be reachable. Check MongoDB status first (`kubectl get mongodbcommunity -n appsmith`), then inspect the init container logs: + +```bash +kubectl logs -n appsmith appsmith-0 -c mongo-init-container +``` + +### Password init Job fails with `ImagePullBackOff` + +The cluster can't pull `docker.io/alpine/kubectl`. Override the image to use your own registry: + +```yaml +mongodbCommunity: + passwordInit: + image: + registry: my-registry.example.com + repository: my/kubectl + tag: "1.34.2" +``` + +## See also + +- [Helm Chart](/getting-started/setup/instance-configuration/helm-chart) — Deployment planning and chart feature overview. +- [Kubernetes Installation Guide](/getting-started/setup/installation-guides/kubernetes) — Step-by-step install for Appsmith on Kubernetes. diff --git a/website/sidebars.js b/website/sidebars.js index e784ae9be2..56fcb06de1 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -201,6 +201,8 @@ const sidebars = { }, 'getting-started/setup/environment-variables', + 'getting-started/setup/instance-configuration/helm-chart', + 'getting-started/setup/instance-configuration/mongodb-kubernetes-operator', 'getting-started/setup/instance-management/api-reference', ], }, From 0da97abdc4d80c6c226be5503ecc8950294f1981 Mon Sep 17 00:00:00 2001 From: Wyatt Walter Date: Thu, 14 May 2026 17:00:03 -0500 Subject: [PATCH 02/11] fix: remove spaces around em dashes to satisfy vale linter The Google style guide rule [Google.EmDash] requires em dashes without surrounding spaces. Co-Authored-By: Claude Opus 4.6 --- .../installation-guides/kubernetes/README.mdx | 6 ++-- .../instance-configuration/helm-chart.md | 36 +++++++++---------- .../mongodb-kubernetes-operator.md | 20 +++++------ 3 files changed, 31 insertions(+), 31 deletions(-) diff --git a/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx b/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx index 296cd82246..e8db8748e6 100644 --- a/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx +++ b/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx @@ -8,7 +8,7 @@ import TabItem from "@theme/TabItem"; # Kubernetes (k8s) -This page provides steps to install Appsmith on a Kubernetes cluster using the [Helm](https://helm.sh) package manager. The default installation runs a single replica and is a good starting point for getting Appsmith running. If you need high availability with multiple replicas, review the [deployment planning guide](/getting-started/setup/instance-configuration/helm-chart#planning-your-deployment) before installing — some decisions require a migration to change later. +This page provides steps to install Appsmith on a Kubernetes cluster using the [Helm](https://helm.sh) package manager. The default installation runs a single replica and is a good starting point for getting Appsmith running. If you need high availability with multiple replicas, review the [deployment planning guide](/getting-started/setup/instance-configuration/helm-chart#planning-your-deployment) before installing—some decisions require a migration to change later. ## Requirements @@ -24,8 +24,8 @@ If you are setting up a new cluster on AWS, see [Set up Kubernetes cluster on AW ### Client machine -- [Helm 3.14+](https://helm.sh/docs/intro/install/) — the Helm package manager. -- [`kubectl`](https://kubernetes.io/docs/tasks/tools/) — configured to connect to your cluster. +- [Helm 3.14+](https://helm.sh/docs/intro/install/)—the Helm package manager. +- [`kubectl`](https://kubernetes.io/docs/tasks/tools/)—configured to connect to your cluster. ## Install Appsmith diff --git a/website/docs/getting-started/setup/instance-configuration/helm-chart.md b/website/docs/getting-started/setup/instance-configuration/helm-chart.md index c7eb7e03a7..8c5963017a 100644 --- a/website/docs/getting-started/setup/instance-configuration/helm-chart.md +++ b/website/docs/getting-started/setup/instance-configuration/helm-chart.md @@ -9,34 +9,34 @@ The Appsmith Helm chart is the recommended way to deploy and manage Appsmith on ## Planning your deployment -Some choices are easy to change after installation — resource limits and environment variables are a `helm upgrade` away. Others require a migration to change because they affect where data is stored. +Some choices are easy to change after installation—resource limits and environment variables are a `helm upgrade` away. Others require a migration to change because they affect where data is stored. Review the decisions below before your first `helm install`. | Decision | Default | Migration required to change? | |---|---|---| -| [Storage and workload type](#storage-and-workload-type) | StatefulSet with a single replica | **Yes** — volume migration and workload recreation | -| [MongoDB](#mongodb) | Bitnami subchart | **Yes** — data export/import between MongoDB deployments | -| [Redis](#redis) | Bitnami subchart | No — Redis data is ephemeral | -| [PostgreSQL](#postgresql) | Bitnami subchart | Yes — Keycloak data migration needed | +| [Storage and workload type](#storage-and-workload-type) | StatefulSet with a single replica | **Yes**—volume migration and workload recreation | +| [MongoDB](#mongodb) | Bitnami subchart | **Yes**—data export/import between MongoDB deployments | +| [Redis](#redis) | Bitnami subchart | No—Redis data is ephemeral | +| [PostgreSQL](#postgresql) | Bitnami subchart | Yes—Keycloak data migration needed | ### Storage and workload type -In addition to its databases, Appsmith persists data to files on disk — logs and other runtime state. The workload type and storage configuration are tightly coupled, and together they determine how volumes are provisioned and whether you can run multiple replicas. +In addition to its databases, Appsmith persists data to files on disk—logs and other runtime state. The workload type and storage configuration are tightly coupled, and together they determine how volumes are provisioned and whether you can run multiple replicas. The chart supports two workload modes, each with different storage behavior: -**StatefulSet (default)** — runs a single replica with its own persistent volume. The pod is replaced in place during upgrades and configuration changes, preserving the same volume. This is the simplest option and works out of the box with most clusters' default block storage `StorageClass` (EBS `gp3`, GCE PD, Azure Disk), but is restricted to a single replica. +**StatefulSet (default)**—runs a single replica with its own persistent volume. The pod is replaced in place during upgrades and configuration changes, preserving the same volume. This is the simplest option and works out of the box with most clusters' default block storage `StorageClass` (EBS `gp3`, GCE PD, Azure Disk), but is restricted to a single replica. -**Deployment** — use this when you need high availability with multiple replicas. Set `workload.kind: Deployment` or enable `autoscaling.enabled`. In this mode, all pods mount the same volume, so you need shared storage (`ReadWriteMany`) backed by AWS EFS, GCP Filestore, Azure Files, or NFS. +**Deployment**—use this when you need high availability with multiple replicas. Set `workload.kind: Deployment` or enable `autoscaling.enabled`. In this mode, all pods mount the same volume, so you need shared storage (`ReadWriteMany`) backed by AWS EFS, GCP Filestore, Azure Files, or NFS. | Configuration | Workload | Storage | Replicas | Values | |---|---|---|---|---| -| **Single replica** (recommended starting point) | StatefulSet | Block storage (`ReadWriteOnce`) — typically the cluster default | 1 | Defaults work out of the box | -| **Multi-replica / HA** | Deployment | Shared filesystem (`ReadWriteMany`) — [AWS EFS](https://docs.aws.amazon.com/eks/latest/userguide/efs-csi.html), [GCP Filestore](https://cloud.google.com/filestore/docs/csi-driver), Azure Files, NFS | 2+ | `workload.kind: Deployment`, `persistence.storageClass: ` | +| **Single replica** (recommended starting point) | StatefulSet | Block storage (`ReadWriteOnce`)—typically the cluster default | 1 | Defaults work out of the box | +| **Multi-replica / HA** | Deployment | Shared filesystem (`ReadWriteMany`)—[AWS EFS](https://docs.aws.amazon.com/eks/latest/userguide/efs-csi.html), [GCP Filestore](https://cloud.google.com/filestore/docs/csi-driver), Azure Files, NFS | 2+ | `workload.kind: Deployment`, `persistence.storageClass: ` | | **Existing claim** | Deployment | Pre-provisioned PVC | 1+ | `workload.kind: Deployment`, `persistence.existingClaim.enabled: true`, `persistence.existingClaim.claimName: ` | -Changing the storage backend or switching between StatefulSet and Deployment on an existing release requires a migration — recreating volumes and the workload resource. See [Migrate to High Availability](/getting-started/setup/installation-guides/kubernetes/migrate-non-ha-to-ha-helm) for the procedure. Plan this before your first install. +Changing the storage backend or switching between StatefulSet and Deployment on an existing release requires a migration—recreating volumes and the workload resource. See [Migrate to High Availability](/getting-started/setup/installation-guides/kubernetes/migrate-non-ha-to-ha-helm) for the procedure. Plan this before your first install. ### MongoDB @@ -52,13 +52,13 @@ For a complete walkthrough of the MongoDB Operator, see the [MongoDB Kubernetes ### Redis -Redis is used for session storage and caching. The chart bundles Redis by default (`redis.enabled: true`) and runs it in the cluster alongside Appsmith. You can also bring your own Redis — for example, a cloud-managed service like AWS ElastiCache — by disabling the bundled instance and setting `APPSMITH_REDIS_URL` in `applicationConfig`. +Redis is used for session storage and caching. The chart bundles Redis by default (`redis.enabled: true`) and runs it in the cluster alongside Appsmith. You can also bring your own Redis—for example, a cloud-managed service like AWS ElastiCache—by disabling the bundled instance and setting `APPSMITH_REDIS_URL` in `applicationConfig`. Redis data is ephemeral, so switching between bundled and external doesn't require a data migration. ### PostgreSQL -PostgreSQL is used by Keycloak for identity management. The chart bundles PostgreSQL by default (`postgresql.enabled: true`) and runs it in the cluster alongside Appsmith. You can also bring your own PostgreSQL — for example, Amazon RDS or Azure Database for PostgreSQL — by disabling the bundled instance and configuring the Keycloak database connection via `applicationConfig`. +PostgreSQL is used by Keycloak for identity management. The chart bundles PostgreSQL by default (`postgresql.enabled: true`) and runs it in the cluster alongside Appsmith. You can also bring your own PostgreSQL—for example, Amazon RDS or Azure Database for PostgreSQL—by disabling the bundled instance and configuring the Keycloak database connection via `applicationConfig`. Switching to an external PostgreSQL on an existing install requires migrating Keycloak's data. @@ -71,7 +71,7 @@ image: repository: appsmith/appsmith-ce ``` -The enterprise image (`appsmith/appsmith-ee`) is used by default. You can run the enterprise image on a free plan without a license key — the community image is only needed if you prefer to run the open source edition. +The enterprise image (`appsmith/appsmith-ee`) is used by default. You can run the enterprise image on a free plan without a license key—the community image is only needed if you prefer to run the open source edition. ## Values reference @@ -79,7 +79,7 @@ The full list of chart parameters is maintained in the [chart README](https://gi ## See also -- [MongoDB Kubernetes Operator](/getting-started/setup/instance-configuration/mongodb-kubernetes-operator) — Install guide, configuration, and migration from Bitnami. -- [Kubernetes Installation Guide](/getting-started/setup/installation-guides/kubernetes) — Step-by-step install for Appsmith on Kubernetes. -- [Environment Variables](/getting-started/setup/environment-variables) — Application-level configuration reference. -- [High Availability Setup](/getting-started/setup/installation-guides/kubernetes/configure-high-availability) — Configure HA on AWS EKS. +- [MongoDB Kubernetes Operator](/getting-started/setup/instance-configuration/mongodb-kubernetes-operator)—Install guide, configuration, and migration from Bitnami. +- [Kubernetes Installation Guide](/getting-started/setup/installation-guides/kubernetes)—Step-by-step install for Appsmith on Kubernetes. +- [Environment Variables](/getting-started/setup/environment-variables)—Application-level configuration reference. +- [High Availability Setup](/getting-started/setup/installation-guides/kubernetes/configure-high-availability)—Configure HA on AWS EKS. diff --git a/website/docs/getting-started/setup/instance-configuration/mongodb-kubernetes-operator.md b/website/docs/getting-started/setup/instance-configuration/mongodb-kubernetes-operator.md index 2384b91a36..a6254bb5ef 100644 --- a/website/docs/getting-started/setup/instance-configuration/mongodb-kubernetes-operator.md +++ b/website/docs/getting-started/setup/instance-configuration/mongodb-kubernetes-operator.md @@ -11,9 +11,9 @@ The MongoDB Kubernetes Operator is the recommended way to run MongoDB for new Ap ## Why use the operator -- **Actively maintained** — the Bitnami MongoDB images have been deprecated by their publisher. The operator uses official MongoDB images with ongoing support. -- **Operator-managed lifecycle** — a dedicated controller handles replica set membership, SCRAM credential lifecycle, and version upgrades. -- **Automatic connection wiring** — the operator creates and maintains the connection-string Secret that Appsmith consumes. No manual URL assembly required. +- **Actively maintained**—the Bitnami MongoDB images have been deprecated by their publisher. The operator uses official MongoDB images with ongoing support. +- **Operator-managed lifecycle**—a dedicated controller handles replica set membership, SCRAM credential lifecycle, and version upgrades. +- **Automatic connection wiring**—the operator creates and maintains the connection-string Secret that Appsmith consumes. No manual URL assembly required. ## How the chart integrates the operator @@ -68,7 +68,7 @@ You should see the operator pod, MongoDB pod(s), and the `MongoDBCommunity` reso kubectl port-forward -n appsmith svc/appsmith 8080:80 ``` -Open http://localhost:8080. For production access, configure an Ingress — see [Expose Appsmith](/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online). +Open http://localhost:8080. For production access, configure an Ingress—see [Expose Appsmith](/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online). ## Configuration @@ -99,7 +99,7 @@ kubectl get secret appsmith-mongo-password -n appsmith \ ### Production sizing -The defaults are tuned for evaluation — a single-member replica set with modest storage. For production, scale to three members and pin resources: +The defaults are tuned for evaluation—a single-member replica set with modest storage. For production, scale to three members and pin resources: ```yaml mongodbCommunity: @@ -116,7 +116,7 @@ mongodbCommunity: memory: 4Gi ``` -Scaling from 1 to 3 members after the initial install is a value change on upgrade — the operator handles adding members to the replica set without downtime. +Scaling from 1 to 3 members after the initial install is a value change on upgrade—the operator handles adding members to the replica set without downtime. ### Namespace scope @@ -124,7 +124,7 @@ Setting `mongodbOperator.enabled: true` installs the operator in the same namesp ### Deploying with ArgoCD -The bundled operator path works with ArgoCD because the CRDs live in the upstream chart's `crds/` directory — Helm and ArgoCD install them before any templates are validated. +The bundled operator path works with ArgoCD because the CRDs live in the upstream chart's `crds/` directory—Helm and ArgoCD install them before any templates are validated. ```yaml apiVersion: argoproj.io/v1alpha1 @@ -188,7 +188,7 @@ kubectl delete crd mongodbusers.mongodb.com ``` :::caution -Deleting these CRDs removes all matching resources across the cluster — only do this if nothing else relies on the operator. +Deleting these CRDs removes all matching resources across the cluster—only do this if nothing else relies on the operator. ::: ## Migrate from Bitnami subchart @@ -345,5 +345,5 @@ mongodbCommunity: ## See also -- [Helm Chart](/getting-started/setup/instance-configuration/helm-chart) — Deployment planning and chart feature overview. -- [Kubernetes Installation Guide](/getting-started/setup/installation-guides/kubernetes) — Step-by-step install for Appsmith on Kubernetes. +- [Helm Chart](/getting-started/setup/instance-configuration/helm-chart)—Deployment planning and chart feature overview. +- [Kubernetes Installation Guide](/getting-started/setup/installation-guides/kubernetes)—Step-by-step install for Appsmith on Kubernetes. From defb3286ee25b79679eac21d3022d81f2eefbdd9 Mon Sep 17 00:00:00 2001 From: Wyatt Walter Date: Thu, 14 May 2026 17:25:02 -0500 Subject: [PATCH 03/11] docs: rewrite expose/ingress page as a TLS configuration guide Replace the outdated "Expose K8s to Internet" page with a focused TLS guide. Ingress setup moved into the install guide; this page now covers TLS termination options: wildcard certs, cert-manager, bring your own, and controller-managed TLS. Adds a warning against using APPSMITH_CUSTOM_DOMAIN on Kubernetes and removes references to the dead ingress.selfSigned option. Co-Authored-By: Claude Opus 4.6 --- .../kubernetes/publish-appsmith-online.mdx | 283 ++++++++++-------- 1 file changed, 153 insertions(+), 130 deletions(-) diff --git a/website/docs/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online.mdx b/website/docs/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online.mdx index 65a49adade..5eda9b8c99 100644 --- a/website/docs/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online.mdx +++ b/website/docs/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online.mdx @@ -1,137 +1,160 @@ --- -description: The page provides steps to expose your Appsmith Kubernetes installation to the internet. +description: Configure TLS for your Appsmith Kubernetes deployment. +toc_max_heading_level: 2 --- -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -# Expose K8s to Internet -The page provides steps to expose your Appsmith Kubernetes installation to the internet. - -## Prerequisites -1. A self-hosted Appsmith installation on a Kubernetes cluster. If not installed yet, see the [Kubernetes installation guide](/getting-started/setup/installation-guides/kubernetes) for installing Appsmith. -2. A running Kubernetes cluster with at least one node. - -## Before you begin -1. Install NGINX Ingress controller on your Kubernetes cluster. If not installed yet, follow these steps: - - a. Add ingress chart repository with: - - ```bash - helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx - ``` - - b. Load ingress chart repository with: - - ```bash - helm repo update - ``` - c. Deploy ingress with: - - ```bash - helm upgrade --namespace ingress-nginx -i ingress-nginx ingress-nginx/ingress-nginx --create-namespace --version 4.4.0 - ``` - - d. Verify ingress installation with: - - ```bash - kubectl get pods -n ingress-nginx - ``` - -## Configure instance - - - - - - 1. Go to the Appsmith installation directory, open values.yaml file, and update the `ingress` attribute as shown below: - - ```yaml - ingress: - ## @param ingress.enabled Enable ingress record generation for Ghost - ## - #highlight-next-line - enabled: true - annotations: - nginx.ingress.kubernetes.io/force-ssl-redirect: "true" - nginx.ingress.kubernetes.io/limit-rps: "15" - ## @param ingress.annotations Additional custom annotations for the ingress record - ## NOTE: If `ingress.certManager=true`, annotation `kubernetes.io/tls-acme: "true"` will automatically be added - ## - className: nginx - hosts: - #highlight-next-line - - host: - paths: - - path: "/" - pathType: Prefix - service: - ## @param service.type Kubernetes Service type - ## - type: ClusterIP - ``` - - 2. Run the below command once the parameter values are updated: - - ```bash - helm upgrade -i appsmith appsmith/appsmith --f values.yaml - ``` - 3. It takes a few minutes for the ingress to get a public IP assigned. Once it has been assigned, you should see an IPv4 address or a domain name in the `ADDRESS` column. Run the below command to get this address: - - ```bash - kubectl get ingress -n appsmith - ``` - - - - - 1. Go to the Appsmith installation directory, open values.yaml file, and update `ingress` attribute as shown below: - - ```yaml - ingress: - ## @param ingress.enabled Enable ingress record generation for Ghost - ## - #highlight-next-line - enabled: true - annotations: - nginx.ingress.kubernetes.io/force-ssl-redirect: "true" - nginx.ingress.kubernetes.io/limit-rps: "15" - ## @param ingress.annotations Additional custom annotations for the ingress record - ## NOTE: If `ingress.certManager=true`, annotation `kubernetes.io/tls-acme: "true"` will automatically be added - ## - className: nginx - hosts: - #highlight-next-line - - host: - paths: - - path: "/" - pathType: Prefix - service: - ## @param service.type Kubernetes Service type - ## - type: ClusterIP - ``` - - 2. Run the below command once the parameter values are updated: - - ```bash - helm upgrade -i appsmith-ee appsmith-ee/appsmith -n appsmith-ee -f values.yaml - ``` - - 3. It takes a few minutes for the ingress to get a public IP assigned. Once it has been assigned, you should see an IPv4 address or a domain name in the `ADDRESS` column. Run the below command to get this address: - - ```bash - kubectl get ingress -n appsmith-ee - ``` - - - - + +# Configure TLS + +When running on Kubernetes, TLS should be terminated at the Ingress layer—not inside Appsmith. This page covers the common approaches to adding TLS to your Appsmith ingress. + +:::caution +Avoid setting `APPSMITH_CUSTOM_DOMAIN` in your Helm values. This enables Appsmith's built-in Caddy proxy to handle TLS, which is designed for Docker and single-instance deployments. On Kubernetes it can cause redirect loops if proxy protocol or `X-Forwarded-Proto` headers are not correctly configured between your cloud load balancer, Ingress controller, and Appsmith. +::: + +## Wildcard or pre-existing certificate + +If your cluster already has TLS coverage for your domain—for example, a wildcard certificate managed by your Ingress controller or a cloud load balancer—no additional TLS configuration is needed in the Appsmith chart. Your ingress configuration from the [install guide](/getting-started/setup/installation-guides/kubernetes) is sufficient: + +```yaml +ingress: + enabled: true + className: traefik + hosts: + - host: appsmith.example.com +``` + +The Ingress controller matches the hostname against the existing certificate and terminates TLS automatically. + +## cert-manager + +[cert-manager](https://cert-manager.io/) automates certificate issuance and renewal. This is the most common approach when you don't already have wildcard coverage. The examples below show how to wire cert-manager into the Appsmith Helm chart—for help installing or troubleshooting cert-manager itself, refer to the [cert-manager documentation](https://cert-manager.io/docs/). + +### Prerequisites + +- cert-manager installed in your cluster ([installation guide](https://cert-manager.io/docs/installation/)) +- A `ClusterIssuer` or `Issuer` configured (for example, Let's Encrypt) + +### Values + +Add the following to your `values.yaml`: + +```yaml +ingress: + enabled: true + className: "" # your ingress controller + tls: true + certManager: true + certManagerTls: + - hosts: + - appsmith.example.com + secretName: appsmith-tls + annotations: + cert-manager.io/cluster-issuer: "letsencrypt-prod" + hosts: + - host: appsmith.example.com +``` + +Setting `certManager: true` automatically adds the `kubernetes.io/tls-acme: "true"` annotation. The `cert-manager.io/cluster-issuer` annotation tells cert-manager which issuer to use—adjust this to match your ClusterIssuer name. + +Apply with: + +```bash +helm upgrade appsmith-ee appsmith-ee/appsmith \ + -n appsmith-ee -f values.yaml +``` + +### Verify + +Check that cert-manager issued a certificate: + +```bash +kubectl get certificate -n appsmith-ee +``` + +The certificate should show `Ready: True`. If it stays `False`, check the certificate and order events: + +```bash +kubectl describe certificate appsmith-tls -n appsmith-ee +``` + +## Bring your own certificate + +If you manage certificates outside of Kubernetes (purchased certs, internal CA, etc.), create a TLS Secret and reference it in your values. + +### Create the Secret + +```bash +kubectl create secret tls appsmith-tls \ + -n appsmith-ee \ + --cert=path/to/tls.crt \ + --key=path/to/tls.key +``` + +### Values + +```yaml +ingress: + enabled: true + className: "" # your ingress controller + tls: true + secrets: + - hosts: + - appsmith.example.com + secretName: appsmith-tls + hosts: + - host: appsmith.example.com +``` + +Apply with: + +```bash +helm upgrade appsmith-ee appsmith-ee/appsmith \ + -n appsmith-ee -f values.yaml +``` + +## Controller-managed TLS + +Some Ingress controllers handle certificate provisioning themselves—for example, [Tailscale](https://tailscale.com/kb/1236/kubernetes-operator) or cloud load balancer controllers that provision certificates via AWS ACM or Google-managed certs. In these cases, set `tls: true` but leave `secretName` empty: + +```yaml +ingress: + enabled: true + className: tailscale + tls: true + secrets: + - hosts: + - appsmith + secretName: ~ +``` + +The controller provisions and manages the certificate. No cert-manager or manual Secret required. ## Troubleshooting -If you face issues, contact the support team using the chat widget at the bottom right of this page. +### Redirect loop after enabling TLS + +**Cause:** `APPSMITH_CUSTOM_DOMAIN` is set in your Helm values. This tells Appsmith's built-in Caddy proxy to handle TLS internally, which conflicts with Ingress TLS termination. + +**Fix:** Remove `APPSMITH_CUSTOM_DOMAIN` from your `applicationConfig` and restart the pods: + +```bash +helm upgrade appsmith-ee appsmith-ee/appsmith \ + -n appsmith-ee -f values.yaml +``` + +### Certificate not issued by cert-manager + +Check the cert-manager logs and the Certificate resource events: + +```bash +kubectl logs -n cert-manager -l app=cert-manager --tail=50 +kubectl describe certificate -n appsmith-ee +``` + +Common causes: the ClusterIssuer name doesn't match, DNS isn't pointing to the Ingress yet, or the ACME challenge can't be reached. ## See also -* [Configure TLS](/getting-started/setup/instance-configuration/custom-domain/configure-tls) -* [Configure Appsmith instance](/getting-started/setup/instance-configuration/configure-using-environment-variables) -* [Manage Appsmith instance](/getting-started/setup/instance-management/) \ No newline at end of file + +- [Kubernetes Installation Guide](/getting-started/setup/installation-guides/kubernetes)—Install Appsmith on Kubernetes. +- [Helm Chart Reference](/getting-started/setup/instance-configuration/helm-chart)—Deployment planning and chart configuration. +- [Custom SSL Certificates](/getting-started/setup/instance-configuration/custom-domain/configure-tls)—Configuring TLS for Docker and non-Kubernetes deployments. From e9d5a4bd9d68ba3190737c9f43569a4b567b9eb3 Mon Sep 17 00:00:00 2001 From: Wyatt Walter Date: Mon, 18 May 2026 16:43:32 -0500 Subject: [PATCH 04/11] docs: add uninstall section to Helm Chart reference page Links to the MongoDB Operator page for operator-aware uninstall and provides inline steps for Bitnami/external MongoDB. Updates the uninstall card on the install page to deep-link to the new section. Co-Authored-By: Claude Opus 4.6 --- .../setup/installation-guides/kubernetes/README.mdx | 2 +- .../setup/instance-configuration/helm-chart.md | 11 +++++++++++ 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx b/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx index e8db8748e6..7553401ae4 100644 --- a/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx +++ b/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx @@ -169,7 +169,7 @@ Appsmith is running and accessible via your ingress. Explore other guides below - +
Uninstall Appsmith diff --git a/website/docs/getting-started/setup/instance-configuration/helm-chart.md b/website/docs/getting-started/setup/instance-configuration/helm-chart.md index 8c5963017a..cdc383f32f 100644 --- a/website/docs/getting-started/setup/instance-configuration/helm-chart.md +++ b/website/docs/getting-started/setup/instance-configuration/helm-chart.md @@ -73,6 +73,17 @@ image: The enterprise image (`appsmith/appsmith-ee`) is used by default. You can run the enterprise image on a free plan without a license key—the community image is only needed if you prefer to run the open source edition. +## Uninstall + +If you installed with the MongoDB Kubernetes Operator (as recommended in the [install guide](/getting-started/setup/installation-guides/kubernetes)), the operator's custom resource has a finalizer that must be cleared before uninstalling. See the [MongoDB Operator uninstall procedure](/getting-started/setup/instance-configuration/mongodb-kubernetes-operator#uninstall) for the full steps. + +If you're using the Bitnami subchart or an external MongoDB, a standard uninstall is sufficient: + +```bash +helm uninstall appsmith-ee -n appsmith-ee +kubectl delete namespace appsmith-ee +``` + ## Values reference The full list of chart parameters is maintained in the [chart README](https://github.com/appsmithorg/appsmith/tree/release/deploy/helm#parameters). The README is auto-generated from annotated comments in `values.yaml` to stay in sync with each chart release. From 911ea0eaf5505af5f9e5d4ee1031038b1906685f Mon Sep 17 00:00:00 2001 From: Wyatt Walter Date: Tue, 19 May 2026 07:42:39 -0500 Subject: [PATCH 05/11] docs: review and rework MongoDB Operator page - Replace inline fresh install steps with link to install guide - Remove ArgoCD example (belongs on Helm Chart page if needed) - Reorder migration to expand-move-contract pattern - Add HA scale-down instructions for Deployment workloads - Simplify data migration to dump/restore from single pod - Move Uninstall section after Migration, before Troubleshooting - Update all references to use appsmith-ee namespace and release name - Fix namespace typos in uninstall and troubleshooting sections - Bump minimum K8s version to 1.33+ Co-Authored-By: Claude Opus 4.6 --- .../mongodb-kubernetes-operator.md | 258 ++++++------------ 1 file changed, 88 insertions(+), 170 deletions(-) diff --git a/website/docs/getting-started/setup/instance-configuration/mongodb-kubernetes-operator.md b/website/docs/getting-started/setup/instance-configuration/mongodb-kubernetes-operator.md index a6254bb5ef..c8e8adb86d 100644 --- a/website/docs/getting-started/setup/instance-configuration/mongodb-kubernetes-operator.md +++ b/website/docs/getting-started/setup/instance-configuration/mongodb-kubernetes-operator.md @@ -27,48 +27,7 @@ When `mongodbOperator.enabled: true` (recommended), the chart also pulls the ups ## Fresh installation -### Prerequisites - -- Kubernetes 1.28+ -- Helm 3.14+ -- A `StorageClass` available for MongoDB PVCs (uses the cluster default unless overridden via `mongodbCommunity.persistent.storageClass`) - -### Install - -```bash -helm repo add appsmith https://helm.appsmith.com -helm repo update - -kubectl create namespace appsmith - -helm install appsmith appsmith/appsmith -n appsmith --wait --timeout 10m \ - --set mongodb.enabled=false \ - --set mongodbCommunity.enabled=true \ - --set mongodbOperator.enabled=true -``` - -| Flag | Purpose | -|---|---| -| `mongodb.enabled=false` | Disables the legacy Bitnami MongoDB subchart | -| `mongodbCommunity.enabled=true` | Deploys a `MongoDBCommunity` CR for the operator to reconcile | -| `mongodbOperator.enabled=true` | Installs the MongoDB Kubernetes Operator in the same namespace | - -### Verify - -```bash -kubectl get pods -n appsmith -kubectl get mongodbcommunity -n appsmith -``` - -You should see the operator pod, MongoDB pod(s), and the `MongoDBCommunity` resource in a `Running` phase. - -### Access the UI - -```bash -kubectl port-forward -n appsmith svc/appsmith 8080:80 -``` - -Open http://localhost:8080. For production access, configure an Ingress—see [Expose Appsmith](/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online). +The MongoDB Operator is the recommended MongoDB configuration for new Appsmith installations. The [Kubernetes installation guide](/getting-started/setup/installation-guides/kubernetes) includes the operator in its default `values.yaml`—follow that guide to get started. ## Configuration @@ -78,7 +37,7 @@ When `mongodbCommunity.auth.passwordSecretName` is empty (the default), the char ```bash kubectl create secret generic my-mongodb-secret \ - -n appsmith \ + -n appsmith-ee \ --from-literal=password='your-password' ``` @@ -93,7 +52,7 @@ The chart skips the pre-install Job when a Secret name is provided. To retrieve the auto-generated password: ```bash -kubectl get secret appsmith-mongo-password -n appsmith \ +kubectl get secret appsmith-ee-mongo-password -n appsmith-ee \ -o jsonpath='{.data.password}' | base64 -d ``` @@ -120,196 +79,155 @@ Scaling from 1 to 3 members after the initial install is a value change on upgra ### Namespace scope -Setting `mongodbOperator.enabled: true` installs the operator in the same namespace as Appsmith. If you manage the operator separately (for example, a cluster-wide install), leave this `false` and ensure the operator has RBAC access to the release namespace. +Setting `mongodbOperator.enabled: true` installs the operator in the same namespace as Appsmith. If you intend to manage the operator separately (for example, a cluster-wide install), leave this `false` and ensure the operator has RBAC access to your Appsmith deployment's namespace. -### Deploying with ArgoCD -The bundled operator path works with ArgoCD because the CRDs live in the upstream chart's `crds/` directory—Helm and ArgoCD install them before any templates are validated. +## Migrate from Bitnami subchart -```yaml -apiVersion: argoproj.io/v1alpha1 -kind: Application -metadata: - name: appsmith - namespace: argocd -spec: - project: default - source: - repoURL: https://helm.appsmith.com - chart: appsmith - targetRevision: "" - helm: - valuesObject: - mongodb: - enabled: false - mongodbCommunity: - enabled: true - mongodbOperator: - enabled: true - destination: - server: https://kubernetes.default.svc - namespace: appsmith - syncPolicy: - automated: {} - syncOptions: - - CreateNamespace=true -``` +If you have an existing Appsmith install using the Bitnami MongoDB subchart, follow this procedure to move to the MongoDB Operator. The migration exports your data from the Bitnami-managed MongoDB and imports it into the operator-managed instance. -## Uninstall +:::caution +Test this procedure on a non-production cluster first. The migration requires downtime while Appsmith is scaled down, data is exported and imported, and the deployment is reconfigured. +::: -Delete the `MongoDBCommunity` resource first so the operator can process its finalizer, then uninstall the release: +### Overview -```bash -# 1. Delete the CR and wait for the operator to clear its finalizer -kubectl delete mongodbcommunity -n appsmith --all --wait=true +The migration follows an expand-move-contract pattern. First, deploy the MongoDB Operator alongside your existing Bitnami instance so both are running. Then scale down Appsmith to stop writes, export data from Bitnami, and import it into the operator-managed MongoDB. Finally, reconfigure the release to use the new MongoDB and remove the old Bitnami resources. -# 2. Uninstall Appsmith (and the bundled operator) -helm uninstall appsmith -n appsmith +1. Deploy the MongoDB Operator alongside the existing Bitnami instance +2. Scale down Appsmith to stop writes +3. Export and import data from Bitnami to the operator-managed MongoDB +4. Switch Appsmith to the new MongoDB and verify +5. Clean up the Bitnami MongoDB resources -# 3. Remove the namespace -kubectl delete namespace appsmith -``` +### Step 1: Deploy the MongoDB Operator -:::caution -Skipping step 1 can leave the `MongoDBCommunity` resource stuck with an unresolved finalizer, which blocks namespace deletion. If that happens, clear it manually: +Upgrade the release to enable the MongoDB Operator alongside the existing Bitnami instance. Both MongoDB deployments will run side by side: ```bash -kubectl patch mongodbcommunity -n appsmith \ - --type=merge -p '{"metadata":{"finalizers":[]}}' +helm upgrade appsmith-ee appsmith-ee/appsmith -n appsmith-ee --wait --timeout 10m \ + --reuse-values \ + --set mongodbCommunity.enabled=true \ + --set mongodbOperator.enabled=true ``` -::: -The MongoDB CRDs installed by the subchart persist after uninstall (Helm never removes resources from `crds/`). To fully clean up: +Wait for the operator-managed MongoDB to reach a `Running` phase: ```bash -kubectl delete crd mongodbcommunity.mongodbcommunity.mongodb.com -kubectl delete crd mongodb.mongodb.com -kubectl delete crd mongodbusers.mongodb.com +kubectl get mongodbcommunity -n appsmith-ee -w ``` -:::caution -Deleting these CRDs removes all matching resources across the cluster—only do this if nothing else relies on the operator. -::: - -## Migrate from Bitnami subchart +### Step 2: Scale down Appsmith -If you have an existing Appsmith install using the Bitnami MongoDB subchart, follow this procedure to move to the MongoDB Operator. The migration exports your data from the Bitnami-managed MongoDB and imports it into the operator-managed instance. - -:::caution -Test this procedure on a non-production cluster first. The migration involves a brief downtime window while Appsmith is restarted with the new MongoDB connection. -::: +Once the operator-managed MongoDB is running, stop the Appsmith workload to prevent writes during the data migration. -### Overview +**StatefulSet (default single-replica install):** -1. Scale down Appsmith to stop writes -2. Export data from the Bitnami MongoDB -3. Deploy the MongoDB Operator alongside the existing release -4. Import data into the operator-managed MongoDB -5. Switch Appsmith to the new MongoDB and verify -6. Clean up the Bitnami MongoDB resources +```bash +kubectl scale statefulset appsmith-ee -n appsmith-ee --replicas=0 +``` -### Step 1: Scale down Appsmith +**Deployment (HA install with autoscaling):** -Stop the Appsmith workload to prevent writes during the migration: +First set the HPA minimum to zero, then scale the Deployment: ```bash -kubectl scale statefulset appsmith -n appsmith --replicas=0 +kubectl patch hpa appsmith-ee -n appsmith-ee --patch '{"spec":{"minReplicas":0}}' +kubectl scale deployment appsmith-ee -n appsmith-ee --replicas=0 ``` Wait for all Appsmith pods to terminate before proceeding. -### Step 2: Export data from Bitnami MongoDB +### Step 3: Export and import data -Identify the Bitnami MongoDB pod and run `mongodump`: +Retrieve both connection strings—the existing Bitnami URI from the ConfigMap and the operator-managed URI from its Secret: ```bash -# Find the primary MongoDB pod -kubectl get pods -n appsmith -l app.kubernetes.io/name=mongodb +SOURCE_URI=$(kubectl get cm appsmith-ee -n appsmith-ee -o jsonpath='{.data.APPSMITH_DB_URL}') -# Run mongodump inside the pod -kubectl exec -n appsmith appsmith-mongodb-0 -- \ - mongodump --uri="mongodb://root:password@localhost:27017" \ - --archive=/tmp/appsmith-dump.gz --gzip - -# Copy the dump to your local machine -kubectl cp appsmith/appsmith-mongodb-0:/tmp/appsmith-dump.gz ./appsmith-dump.gz +MONGO_PASS=$(kubectl get secret appsmith-ee-mongo-password -n appsmith-ee \ + -o jsonpath='{.data.password}' | base64 -d) +DEST_URI="mongodb://appsmith:${MONGO_PASS}@appsmith-ee-mongo-0.appsmith-ee-mongo-svc.appsmith-ee.svc.cluster.local:27017/appsmith?authSource=appsmith" ``` -:::tip -If your Bitnami MongoDB uses a non-default root password, retrieve it from the existing Secret: +Dump from the Bitnami MongoDB and restore directly into the operator-managed instance, all from the Bitnami pod: ```bash -kubectl get secret appsmith-mongodb -n appsmith \ - -o jsonpath='{.data.mongodb-root-password}' | base64 -d +# Dump the data +kubectl exec -n appsmith-ee appsmith-ee-mongodb-0 -- \ + mongodump --uri="$SOURCE_URI" \ + --archive=/tmp/appsmith-dump.gz --gzip + +# Restore into the operator-managed MongoDB +kubectl exec -n appsmith-ee appsmith-ee-mongodb-0 -- \ + mongorestore --uri="$DEST_URI" \ + --archive=/tmp/appsmith-dump.gz --gzip --drop ``` -::: -### Step 3: Deploy the MongoDB Operator +### Step 4: Switch Appsmith to the new MongoDB -Upgrade the release to enable the MongoDB Operator alongside the existing Bitnami instance. Appsmith remains scaled to zero during this step: +Upgrade the release to disable the Bitnami subchart. Helm will scale Appsmith back to its configured replica count: ```bash -helm upgrade appsmith appsmith/appsmith -n appsmith --wait --timeout 10m \ +helm upgrade appsmith-ee appsmith-ee/appsmith -n appsmith-ee --wait --timeout 10m \ --reuse-values \ - --set mongodbCommunity.enabled=true \ - --set mongodbOperator.enabled=true + --set mongodb.enabled=false ``` -Wait for the operator-managed MongoDB to reach a `Running` phase: +Verify Appsmith starts successfully and you can log in with existing credentials. Check the logs for any database connection errors: ```bash -kubectl get mongodbcommunity -n appsmith -w +kubectl logs -n appsmith-ee appsmith-ee-0 --tail=50 ``` -### Step 4: Import data into operator-managed MongoDB - -Retrieve the operator-managed MongoDB password: +### Step 5: Clean up -```bash -MONGO_PASS=$(kubectl get secret appsmith-mongo-password -n appsmith \ - -o jsonpath='{.data.password}' | base64 -d) -``` - -Copy the dump file into the new MongoDB pod and restore: +Once you've verified the migration is successful, remove the old Bitnami MongoDB PVCs: ```bash -# Copy dump to the operator-managed pod -kubectl cp ./appsmith-dump.gz appsmith/appsmith-mongo-0:/tmp/appsmith-dump.gz +# List PVCs from the old Bitnami MongoDB +kubectl get pvc -n appsmith-ee -l app.kubernetes.io/name=mongodb -# Restore into the new instance -kubectl exec -n appsmith appsmith-mongo-0 -- \ - mongorestore --uri="mongodb://appsmith:${MONGO_PASS}@localhost:27017/appsmith?authSource=appsmith" \ - --archive=/tmp/appsmith-dump.gz --gzip --drop +# Delete them after confirming the new MongoDB is working +kubectl delete pvc -n appsmith-ee -l app.kubernetes.io/name=mongodb ``` -### Step 5: Switch Appsmith to the new MongoDB +## Uninstall -Upgrade the release to disable the Bitnami subchart. Helm will scale Appsmith back to its configured replica count: +Delete the `MongoDBCommunity` resource first so the operator can process its finalizer, then uninstall the release: ```bash -helm upgrade appsmith appsmith/appsmith -n appsmith --wait --timeout 10m \ - --reuse-values \ - --set mongodb.enabled=false +# 1. Delete the CR and wait for the operator to clear its finalizer +kubectl delete mongodbcommunity -n appsmith-ee --all --wait=true + +# 2. Uninstall Appsmith (and the bundled operator) +helm uninstall appsmith-ee -n appsmith-ee + +# 3. Remove the namespace +kubectl delete namespace appsmith-ee ``` -Verify Appsmith starts successfully and you can log in with existing credentials. Check the logs for any database connection errors: +:::caution +Skipping step 1 can leave the `MongoDBCommunity` resource stuck with an unresolved finalizer, which blocks namespace deletion. If that happens, clear it manually: ```bash -kubectl logs -n appsmith appsmith-0 --tail=50 +kubectl patch mongodbcommunity -n appsmith-ee \ + --type=merge -p '{"metadata":{"finalizers":[]}}' ``` +::: -### Step 6: Clean up - -Once you've verified the migration is successful, remove the old Bitnami MongoDB PVCs: +The MongoDB CRDs installed by the subchart persist after uninstall (Helm never removes resources from `crds/`). To fully clean up: ```bash -# List PVCs from the old Bitnami MongoDB -kubectl get pvc -n appsmith -l app.kubernetes.io/name=mongodb - -# Delete them after confirming the new MongoDB is working -kubectl delete pvc -n appsmith -l app.kubernetes.io/name=mongodb +kubectl delete crd mongodbcommunity.mongodbcommunity.mongodb.com +kubectl delete crd mongodb.mongodb.com +kubectl delete crd mongodbusers.mongodb.com ``` +:::caution +Deleting these CRDs removes all matching resources across the cluster—only do this if nothing else relies on the operator. +::: + ## Troubleshooting ### `MongoDBCommunity` CR stays in `Pending` phase @@ -317,17 +235,17 @@ kubectl delete pvc -n appsmith -l app.kubernetes.io/name=mongodb Check the operator logs: ```bash -kubectl logs -n appsmith -l app.kubernetes.io/name=mongodb-kubernetes-operator --tail=50 +kubectl logs -n appsmith-ee -l app.kubernetes.io/name=mongodb-kubernetes-operator --tail=50 ``` Common causes: the password Secret doesn't exist (if you set `passwordSecretName`, verify the Secret is present with a `password` key), or the MongoDB image can't be pulled. ### Appsmith pod stuck in `Init` -The init container waits for MongoDB to be reachable. Check MongoDB status first (`kubectl get mongodbcommunity -n appsmith`), then inspect the init container logs: +The init container waits for MongoDB to be reachable. Check MongoDB status first (`kubectl get mongodbcommunity -n appsmith-ee`), then inspect the init container logs: ```bash -kubectl logs -n appsmith appsmith-0 -c mongo-init-container +kubectl logs -n appsmith-ee appsmith-ee-0 -c mongo-init-container ``` ### Password init Job fails with `ImagePullBackOff` From f1ee9c32296f1fd36ee8a561fe7a6951cc91bdd6 Mon Sep 17 00:00:00 2001 From: Wyatt Walter Date: Tue, 19 May 2026 15:03:06 -0500 Subject: [PATCH 06/11] docs: reorganize sidebar IA and polish Helm chart pages Move Helm Chart, MongoDB Operator, and Ingress/TLS pages into a dedicated "Helm Chart" category under Manage Installation. Add external database links, storage expansion callout, and update cross-references to use new page titles. Co-Authored-By: Claude Opus 4.6 --- .../installation-guides/kubernetes/README.mdx | 6 +++--- .../kubernetes/publish-appsmith-online.mdx | 6 +++--- .../setup/instance-configuration/README.mdx | 6 +++--- .../custom-domain/README.md | 4 ++-- .../instance-configuration/helm-chart.md | 15 +++++++------- website/sidebars.js | 20 +++++++++++++++---- 6 files changed, 34 insertions(+), 23 deletions(-) diff --git a/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx b/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx index 7553401ae4..ff9d07a71e 100644 --- a/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx +++ b/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx @@ -16,7 +16,7 @@ This page provides steps to install Appsmith on a Kubernetes cluster using the [ - A running Kubernetes cluster (1.33+). - Appsmith application pods need at least **6 GB of memory** and benefit from **2 vCPUs**. MongoDB, Redis, PostgreSQL, and other chart dependencies consume additional resources, and the cluster itself has overhead for system components (kube-proxy, monitoring agents, ingress controllers, etc.). Plan for a minimum of **2 nodes with 2 vCPUs and 8 GB of memory each**. -- A default `StorageClass` capable of provisioning persistent volumes. Most managed Kubernetes services (EKS, GKE, AKS) provide this out of the box. +- A default `StorageClass` capable of provisioning persistent volumes with `allowVolumeExpansion: true` to avoid reprovisioning storage as data grows. - An Ingress controller (such as [Traefik](https://doc.traefik.io/traefik/providers/kubernetes-ingress/) or an AWS/GCP load balancer controller) or a `LoadBalancer`-type Service to expose Appsmith to users. - Outbound network access to `cs.appsmith.com` for license validation and updates. @@ -69,7 +69,7 @@ Follow these steps to install Appsmith: - host: appsmith.example.com ``` - Replace `appsmith.example.com` with your domain and set `className` to match your Ingress controller. This configures the chart to use the [MongoDB Kubernetes Operator](/getting-started/setup/instance-configuration/mongodb-kubernetes-operator) instead of the legacy Bitnami MongoDB subchart. For TLS configuration, see [Configure TLS](/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online). + Replace `appsmith.example.com` with your domain and set `className` to match your Ingress controller. This configures the chart to use the [MongoDB Kubernetes Operator](/getting-started/setup/instance-configuration/mongodb-kubernetes-operator) instead of the legacy Bitnami MongoDB subchart. For TLS configuration, see [Ingress and TLS](/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online). For the full list of configurable values, see the [chart README](https://github.com/appsmithorg/appsmith/tree/release/deploy/helm#parameters). 4. Deploy Appsmith: @@ -108,7 +108,7 @@ Appsmith is running and accessible via your ingress. Explore other guides below
- Configure TLS + Ingress and TLS
diff --git a/website/docs/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online.mdx b/website/docs/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online.mdx index 5eda9b8c99..197350a30d 100644 --- a/website/docs/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online.mdx +++ b/website/docs/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online.mdx @@ -1,9 +1,9 @@ --- -description: Configure TLS for your Appsmith Kubernetes deployment. +description: Configure ingress and TLS for your Appsmith Kubernetes deployment. toc_max_heading_level: 2 --- -# Configure TLS +# Ingress and TLS When running on Kubernetes, TLS should be terminated at the Ingress layer—not inside Appsmith. This page covers the common approaches to adding TLS to your Appsmith ingress. @@ -157,4 +157,4 @@ Common causes: the ClusterIssuer name doesn't match, DNS isn't pointing to the I - [Kubernetes Installation Guide](/getting-started/setup/installation-guides/kubernetes)—Install Appsmith on Kubernetes. - [Helm Chart Reference](/getting-started/setup/instance-configuration/helm-chart)—Deployment planning and chart configuration. -- [Custom SSL Certificates](/getting-started/setup/instance-configuration/custom-domain/configure-tls)—Configuring TLS for Docker and non-Kubernetes deployments. +- [Custom Domain and SSL](/getting-started/setup/instance-configuration/custom-domain)—Configuring TLS for Docker and non-Kubernetes deployments. diff --git a/website/docs/getting-started/setup/instance-configuration/README.mdx b/website/docs/getting-started/setup/instance-configuration/README.mdx index b98232e77d..0bdf09423d 100644 --- a/website/docs/getting-started/setup/instance-configuration/README.mdx +++ b/website/docs/getting-started/setup/instance-configuration/README.mdx @@ -145,15 +145,15 @@ This page provides detailed resources to assist you in configuring and managing
- +
- Configure TLS on Kubernetes + Ingress and TLS on Kubernetes
-
This guide walks you through the steps to enable TLS for secure communication on custom domains for an Appsmith instance deployed on Kubernetes, ensuring encrypted traffic and enhanced security.
+
Configure ingress and TLS for your Appsmith Kubernetes deployment, including cert-manager, bring-your-own certificates, and controller-managed TLS.
 diff --git a/website/docs/getting-started/setup/instance-configuration/custom-domain/README.md b/website/docs/getting-started/setup/instance-configuration/custom-domain/README.md index e00b781324..1bb84813c0 100644 --- a/website/docs/getting-started/setup/instance-configuration/custom-domain/README.md +++ b/website/docs/getting-started/setup/instance-configuration/custom-domain/README.md @@ -7,7 +7,7 @@ description: Learn how to secure your custom domain on a self-hosted Appsmith in This page explains how to configure SSL for your custom domain on a self-hosted Appsmith instance, ensuring secure HTTPS connections for your applications. :::info -For Kubernetes installations, see [Configure TLS for Kubernetes](/getting-started/setup/instance-configuration/custom-domain/configure-tls). +For Kubernetes installations, see [Ingress and TLS](/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online). ::: ## Prerequisites @@ -110,5 +110,5 @@ If you continue to face issues, contact the support team using the chat widget a ## See also - [Configure Environment Variables](/getting-started/setup/instance-configuration/configure-using-environment-variables?current-platform=docker): Learn how to configure environment variables, which may be necessary when setting up TLS and Appsmith in Kubernetes. - [Configure HTTP/HTTPS Proxy](/getting-started/setup/instance-configuration/http-proxy): Setup HTTP/HTTPS proxy if required for your deployment while configuring TLS or managing network traffic. -- [Configure TLS for Kubernetes](/getting-started/setup/instance-configuration/custom-domain/configure-tls): Learn how to set up TLS for Appsmith on Kubernetes. +- [Ingress and TLS](/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online): Learn how to configure ingress and TLS for Appsmith on Kubernetes. - [Install an SSL certificate on DigitalOcean](https://docs.digitalocean.com/support/how-do-i-install-an-ssl-certificate-on-a-droplet/): Follow this guide to configure SSL for your DigitalOcean Droplet. \ No newline at end of file diff --git a/website/docs/getting-started/setup/instance-configuration/helm-chart.md b/website/docs/getting-started/setup/instance-configuration/helm-chart.md index cdc383f32f..922802e479 100644 --- a/website/docs/getting-started/setup/instance-configuration/helm-chart.md +++ b/website/docs/getting-started/setup/instance-configuration/helm-chart.md @@ -36,6 +36,8 @@ The chart supports two workload modes, each with different storage behavior: | **Multi-replica / HA** | Deployment | Shared filesystem (`ReadWriteMany`)—[AWS EFS](https://docs.aws.amazon.com/eks/latest/userguide/efs-csi.html), [GCP Filestore](https://cloud.google.com/filestore/docs/csi-driver), Azure Files, NFS | 2+ | `workload.kind: Deployment`, `persistence.storageClass: ` | | **Existing claim** | Deployment | Pre-provisioned PVC | 1+ | `workload.kind: Deployment`, `persistence.existingClaim.enabled: true`, `persistence.existingClaim.claimName: ` | +Use a `StorageClass` that allows volume expansion (`allowVolumeExpansion: true`) to avoid reprovisioning storage as your data grows. + Changing the storage backend or switching between StatefulSet and Deployment on an existing release requires a migration—recreating volumes and the workload resource. See [Migrate to High Availability](/getting-started/setup/installation-guides/kubernetes/migrate-non-ha-to-ha-helm) for the procedure. Plan this before your first install. ### MongoDB @@ -48,19 +50,19 @@ MongoDB is Appsmith's primary data store. The chart supports three approaches, a | **Bitnami subchart** (default) | Being phased out | Existing installations that haven't migrated yet. The upstream Bitnami MongoDB images have been deprecated by their publisher. | | **External MongoDB** | Stable | Managed services (Atlas) or self-managed MongoDB outside the cluster. | -For a complete walkthrough of the MongoDB Operator, see the [MongoDB Kubernetes Operator](/getting-started/setup/instance-configuration/mongodb-kubernetes-operator) guide. If you have an existing install using the Bitnami subchart, see [Migrate from Bitnami to MongoDB Operator](/getting-started/setup/instance-configuration/mongodb-kubernetes-operator#migrate-from-bitnami-subchart) for the migration procedure. +For a complete walkthrough of the MongoDB Operator, see the [MongoDB Kubernetes Operator](/getting-started/setup/instance-configuration/mongodb-kubernetes-operator) guide. If you have an existing install using the Bitnami subchart, see [Migrate from Bitnami to MongoDB Operator](/getting-started/setup/instance-configuration/mongodb-kubernetes-operator#migrate-from-bitnami-subchart) for the migration procedure. To configure an external MongoDB instance, see [Custom MongoDB](/getting-started/setup/instance-configuration/custom-mongodb-redis). ### Redis Redis is used for session storage and caching. The chart bundles Redis by default (`redis.enabled: true`) and runs it in the cluster alongside Appsmith. You can also bring your own Redis—for example, a cloud-managed service like AWS ElastiCache—by disabling the bundled instance and setting `APPSMITH_REDIS_URL` in `applicationConfig`. -Redis data is ephemeral, so switching between bundled and external doesn't require a data migration. +Redis data is ephemeral, so switching between bundled and external doesn't require a data migration. See [External Redis](/getting-started/setup/instance-configuration/external-redis) for configuration details. ### PostgreSQL PostgreSQL is used by Keycloak for identity management. The chart bundles PostgreSQL by default (`postgresql.enabled: true`) and runs it in the cluster alongside Appsmith. You can also bring your own PostgreSQL—for example, Amazon RDS or Azure Database for PostgreSQL—by disabling the bundled instance and configuring the Keycloak database connection via `applicationConfig`. -Switching to an external PostgreSQL on an existing install requires migrating Keycloak's data. +Switching to an external PostgreSQL on an existing install requires migrating Keycloak's data. See [External PostgreSQL](/getting-started/setup/instance-configuration/external-postgresql-rds) for configuration details. ## Community edition @@ -84,13 +86,10 @@ helm uninstall appsmith-ee -n appsmith-ee kubectl delete namespace appsmith-ee ``` -## Values reference - -The full list of chart parameters is maintained in the [chart README](https://github.com/appsmithorg/appsmith/tree/release/deploy/helm#parameters). The README is auto-generated from annotated comments in `values.yaml` to stay in sync with each chart release. - ## See also -- [MongoDB Kubernetes Operator](/getting-started/setup/instance-configuration/mongodb-kubernetes-operator)—Install guide, configuration, and migration from Bitnami. +- [Ingress and TLS](/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online)—Configure ingress and TLS for Kubernetes. - [Kubernetes Installation Guide](/getting-started/setup/installation-guides/kubernetes)—Step-by-step install for Appsmith on Kubernetes. - [Environment Variables](/getting-started/setup/environment-variables)—Application-level configuration reference. - [High Availability Setup](/getting-started/setup/installation-guides/kubernetes/configure-high-availability)—Configure HA on AWS EKS. +- [Upgrade Helm Chart Versions](/getting-started/setup/instance-management)—Migration guides for older chart versions (v1→v2, CE→EE chart consolidation, Bitnami image deprecation). diff --git a/website/sidebars.js b/website/sidebars.js index 56fcb06de1..82ec58289e 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -130,12 +130,27 @@ const sidebars = { }, ], }, + { + type: 'category', + label: 'Helm Chart', + link: { + type: 'doc', + id: 'getting-started/setup/instance-configuration/helm-chart', + }, + items: [ + 'getting-started/setup/instance-configuration/mongodb-kubernetes-operator', + { + type: 'doc', + id: 'getting-started/setup/installation-guides/kubernetes/publish-appsmith-online', + label: 'Ingress and TLS', + }, + ], + }, { type: 'category', label: 'Custom Domain and SSL Guides', items: [ 'getting-started/setup/instance-configuration/custom-domain/README', - 'getting-started/setup/instance-configuration/custom-domain/configure-tls', 'getting-started/setup/instance-configuration/custom-domain/custom-ca-root-certificate', ], }, @@ -170,7 +185,6 @@ const sidebars = { 'getting-started/setup/instance-configuration/external-redis', 'getting-started/setup/instance-configuration/in-memory-git', 'getting-started/setup/installation-guides/azure/setup-to-integrate-sso', - 'getting-started/setup/installation-guides/kubernetes/publish-appsmith-online', 'getting-started/setup/instance-configuration/http-proxy', 'getting-started/setup/instance-configuration/configure-using-environment-variables', 'getting-started/setup/instance-management/supervisor', @@ -201,8 +215,6 @@ const sidebars = { }, 'getting-started/setup/environment-variables', - 'getting-started/setup/instance-configuration/helm-chart', - 'getting-started/setup/instance-configuration/mongodb-kubernetes-operator', 'getting-started/setup/instance-management/api-reference', ], }, From 9fbc7212bf4dd641866cafc13a589dcee028f063 Mon Sep 17 00:00:00 2001 From: Wyatt Walter Date: Wed, 20 May 2026 07:46:49 -0500 Subject: [PATCH 07/11] docs: remove obsolete configure-tls page Delete configure-tls.mdx (outdated, referenced ingress-nginx and cert-manager v1.5.3) and repoint the three migration guides that linked to it to the new Ingress and TLS page. Co-Authored-By: Claude Opus 4.6 --- .../kubernetes/migrate-k8s.md | 2 +- .../kubernetes/migrate-to-be-chart.md | 2 +- .../kubernetes/migrate-to-helm-chart-v2-ce.md | 2 +- .../custom-domain/configure-tls.mdx | 210 ------------------ 4 files changed, 3 insertions(+), 213 deletions(-) delete mode 100644 website/docs/getting-started/setup/instance-configuration/custom-domain/configure-tls.mdx diff --git a/website/docs/getting-started/setup/installation-guides/kubernetes/migrate-k8s.md b/website/docs/getting-started/setup/installation-guides/kubernetes/migrate-k8s.md index 62a536e77f..b9e03b504a 100644 --- a/website/docs/getting-started/setup/installation-guides/kubernetes/migrate-k8s.md +++ b/website/docs/getting-started/setup/installation-guides/kubernetes/migrate-k8s.md @@ -145,7 +145,7 @@ Follow the below steps to install the Helm chart with the old configuration: 2. After installation, verify that the pods are running. Use the below command to verify the new pod created by the Helm chart: :::caution Attention - Ensure that the `APPSMITH_CUSTOM_DOMAIN` environment variable is not set in the `docker.env` file when deploying Appsmith on Kubernetes. To configure the TLS on Kubernetes, see the [Configuring TLS](/getting-started/setup/instance-configuration/custom-domain/configure-tls) section. + Ensure that the `APPSMITH_CUSTOM_DOMAIN` environment variable is not set in the `docker.env` file when deploying Appsmith on Kubernetes. To configure the TLS on Kubernetes, see the [Ingress and TLS](/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online) section. ::: ```bash diff --git a/website/docs/getting-started/setup/installation-guides/kubernetes/migrate-to-be-chart.md b/website/docs/getting-started/setup/installation-guides/kubernetes/migrate-to-be-chart.md index 0fe19b7ed8..fdb941ec2a 100644 --- a/website/docs/getting-started/setup/installation-guides/kubernetes/migrate-to-be-chart.md +++ b/website/docs/getting-started/setup/installation-guides/kubernetes/migrate-to-be-chart.md @@ -129,7 +129,7 @@ To ensure that the Commercial Edition Helm chart runs, you need to make some cha 3. Add the license key and a few other variables related to Keycloak to `applicationConfig` section: :::caution Attention - Ensure that the `APPSMITH_CUSTOM_DOMAIN` environment variable is not set in the `docker.env` file when deploying Appsmith on Kubernetes. To configure the TLS on Kubernetes, see the [Configuring TLS](/getting-started/setup/instance-configuration/custom-domain/configure-tls) section. + Ensure that the `APPSMITH_CUSTOM_DOMAIN` environment variable is not set in the `docker.env` file when deploying Appsmith on Kubernetes. To configure the TLS on Kubernetes, see the [Ingress and TLS](/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online) section. ::: ```yaml diff --git a/website/docs/getting-started/setup/installation-guides/kubernetes/migrate-to-helm-chart-v2-ce.md b/website/docs/getting-started/setup/installation-guides/kubernetes/migrate-to-helm-chart-v2-ce.md index aa1bc740da..e427fdbb83 100644 --- a/website/docs/getting-started/setup/installation-guides/kubernetes/migrate-to-helm-chart-v2-ce.md +++ b/website/docs/getting-started/setup/installation-guides/kubernetes/migrate-to-helm-chart-v2-ce.md @@ -87,7 +87,7 @@ It's recommended to install the new Appsmith helm chart in the same namespace. H 3. Run the below command to install Appsmith: :::caution Attention - Ensure that the `APPSMITH_CUSTOM_DOMAIN` environment variable is not set in the `docker.env` file when deploying Appsmith on Kubernetes. To configure the TLS on Kubernetes, see the [Configuring TLS](/getting-started/setup/instance-configuration/custom-domain/configure-tls) section. + Ensure that the `APPSMITH_CUSTOM_DOMAIN` environment variable is not set in the `docker.env` file when deploying Appsmith on Kubernetes. To configure the TLS on Kubernetes, see the [Ingress and TLS](/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online) section. ::: ```bash diff --git a/website/docs/getting-started/setup/instance-configuration/custom-domain/configure-tls.mdx b/website/docs/getting-started/setup/instance-configuration/custom-domain/configure-tls.mdx deleted file mode 100644 index e97bd83e9b..0000000000 --- a/website/docs/getting-started/setup/instance-configuration/custom-domain/configure-tls.mdx +++ /dev/null @@ -1,210 +0,0 @@ ---- -description: Follow these steps to configure TLS for Appsmith on Kubernetes. ---- - -import Tabs from "@theme/Tabs"; -import TabItem from "@theme/TabItem"; - -# Configure TLS on Kubernetes - -This page provides steps to configure TLS for your Appsmith deployment using a free `Let's Encrypt` certificate. - -## Prerequisites - -Before configuring SSL for your custom domain, ensure you have the following: - -1. A self-hosted Appsmith instance installed. If not already installed, refer to the [installation guides](/getting-started/setup/installation-guides). This guide assumes you are working with an existing installation. -2. A custom domain purchased from a domain provider, such as: - - [GoDaddy](https://in.godaddy.com/help/create-a-subdomain-4080) - - [Amazon Route 53](https://aws.amazon.com/premiumsupport/knowledge-center/create-subdomain-route-53/) - - [Digital Ocean](https://www.digitalocean.com/docs/networking/dns/how-to/add-subdomain/) - - [NameCheap](https://www.namecheap.com/support/knowledgebase/article.aspx/9776/2237/how-to-create-a-subdomain-for-my-domain) - - [Domain.com](https://www.domain.com/help/article/domain-management-how-to-update-subdomains) -3. Ports 80 and 443 must be open and accessible. If using custom ports, ensure they are also open and accessible. -4. Exposed your Kubernetes deployment to the internet. If not exposed, see the[Expose K8s to Internet](/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online) guide. - -## Configure TLS (HTTPS) with Let's Encrypt - -:::tip -If you see permission errors when running these commands on Google Kubernetes Engine (GKE), refer to the official cert-manager documentation on [how to elevate your permissions](https://docs.cert-manager.io/en/latest/getting-started/install/kubernetes.html). -::: - -Follow these steps to configure TLS: - -1. Get the `LoadBalancer` hostname with: - -``` -kubectl get svc --namespace ingress-nginx ingress-nginx-controller -o jsonpath="{.status.loadBalancer.ingress[0].hostname}" -``` - -2. Confirm that you can access your Appsmith instance by browsing the hostname. - -3. Create a `CNAME` record for the `LoadBalancer` hostname in your DNS configuration. - -4. Add the repository with: - -```bash -helm repo add jetstack https://charts.jetstack.io -``` - -5. Create a namespace for cert-manager with: - -```bash -kubectl create namespace cert-manager -``` - -6. Create custom resource definitions with: - -```bash -kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v1.5.3/cert-manager.crds.yaml -``` - -7. Create a `ClusterIssuer` resource for Let's Encrypt certificates. Create a file with the below content. Replace the `` placeholder with a valid email address. Save the file as `letsencrypt-appsmith.yaml`. - -```yaml -apiVersion: cert-manager.io/v1 -kind: ClusterIssuer -metadata: - name: letsencrypt-appsmith -spec: - acme: - #highlight-next-line - email: - server: https://acme-v02.api.letsencrypt.org/directory - privateKeySecretRef: - name: letsencrypt-appsmith - solvers: - - http01: - ingress: - class: nginx -``` - -8. Apply the changes to the cluster with: - -``` -kubectl apply -f letsencrypt-appsmith.yaml -``` - -9. Install cert-manager and set up `Let's Encrypt` as the default Certificate Authority (CA) with: - -``` -helm install cert-manager --namespace cert-manager jetstack/cert-manager --version v1.5.3 -``` - -8. Install Appsmith with integration to Ingress and cert-manager. - - - - -You can use the `helm upgrade` command in one of the two ways: - -- Use the below command to update Helm parameters. Replace `` with your domain name. - -```bash - helm upgrade appsmith appsmith-ee/appsmith \ - --set service.type=ClusterIP \ - --set ingress.enabled=true \ - --set ingress.tls=true \ - --set ingress.certManager=true \ - --set ingress.annotations."cert-manager\.io/cluster-issuer"=letsencrypt-appsmith \ - #highlight-next-line - --set ingress.hosts[0].host= \ - #highlight-next-line - --set ingress.certManagerTls[0].hosts[0]= \ - --set ingress.certManagerTls[0].secretName=letsencrypt-appsmith - --set ingress.className=nginx -``` - -- **Or** use the `values.yaml` file to update parameters. Follow these steps to update: - - 1. Open the `values.yaml` file, and make changes to the parameters as shown below: - - ```yaml - ingress: - enabled: true - annotations: - cert-manager.io/cluster-issuer: "letsencrypt-appsmith" - hosts: - - host: example.appsmith.com - tls: true - secrets: [] - certManager: true - certManagerTls: - - hosts: - - example.appsmith.com - secretName: letsencrypt-appsmith - className: "nginx" - ``` - - 2. Run the below command once the parameter values are updated: - - ```bash - helm upgrade -i appsmith -f values.yaml appsmith appsmith-ee/appsmith - ``` - - - - -You can use the `helm upgrade` command to update your Appsmith installation in one of two ways: - -- Use the below command to update Appsmith using Helm parameters. In this command, replace `` with your domain name. - - ```bash - helm upgrade appsmith appsmith/appsmith \ - --set service.type=ClusterIP \ - --set ingress.enabled=true \ - --set ingress.tls=true \ - --set ingress.certManager=true \ - --set ingress.annotations."cert-manager\.io/cluster-issuer"=letsencrypt-appsmith \ - #highlight-next-line - --set ingress.hosts[0].host= \ - #highlight-next-line - --set ingress.certManagerTls[0].hosts[0]= \ - --set ingress.certManagerTls[0].secretName=letsencrypt-appsmith - --set ingress.className=nginx - ``` - -- **Or** use `values.yaml file to update parameters. Follow these steps to update: - - 1. Open the `values.yaml` file and make the necessary changes to the parameters as shown below: - - ```yaml - ingress: - enabled: true - annotations: - cert-manager.io/cluster-issuer: "letsencrypt-appsmith" - hosts: - - host: example.appsmith.com - tls: true - secrets: [] - certManager: true - certManagerTls: - - hosts: - - example.appsmith.com - secretName: letsencrypt-appsmith - className: "nginx" - ``` - - 2. Run the below command once the parameter values are updated: - - ```bash - helm upgrade -i appsmith -f values.yaml appsmith appsmith/appsmith - ``` - - - - -You can now access Appsmith via a secure TLS connection with a valid Let's Encrypt certificate. Verify this by opening the site in a browser. - -## Troubleshooting - -You may face SSL/TLS certificate error while configuring SSL, follow the below guide to troubleshoot: -* [SSL/TLS Certificate Error](/help-and-support/troubleshooting-guide/deployment-errors#ssltls-certification-errors) -* Verify logs for errors. For more information, see [Get Container logs](/getting-started/setup/instance-management/how-to-get-container-logs) guide. - -If you continue to face issues, contact the support team using the chat widget at the bottom right of this page. - -## See also - -- [Configure Environment Variables](/getting-started/setup/instance-configuration/configure-using-environment-variables?current-platform=helm):Learn how to configure environment variables, which may be necessary when setting up TLS and Appsmith in Kubernetes. -- [Configure HTTP/HTTPS Proxy](/getting-started/setup/instance-configuration/http-proxy): Setup HTTP/HTTPS proxy if required for your deployment while configuring TLS or managing network traffic. From eee3d0ec42447f85d6494e633639b8dc2efcb80e Mon Sep 17 00:00:00 2001 From: Wyatt Walter Date: Wed, 20 May 2026 10:49:38 -0500 Subject: [PATCH 08/11] docs: address install guide issues from testing - Use placeholder values (, ) that break YAML parsing if not replaced, with inline comments explaining how to find the correct values - Add ingress verification step (kubectl get ingress) before DNS/ port-forward step - Use svc/appsmith-ee for port-forward instead of pod name - Update Helm prerequisite to note Helm 4 support - Soften allowVolumeExpansion to a recommendation - Clarify prose to distinguish MongoDB config from ingress config Co-Authored-By: Claude Opus 4.6 --- .../installation-guides/kubernetes/README.mdx | 44 ++++++++++++------- .../instance-configuration/helm-chart.md | 2 +- 2 files changed, 28 insertions(+), 18 deletions(-) diff --git a/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx b/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx index ff9d07a71e..dfa35a2212 100644 --- a/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx +++ b/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx @@ -16,7 +16,7 @@ This page provides steps to install Appsmith on a Kubernetes cluster using the [ - A running Kubernetes cluster (1.33+). - Appsmith application pods need at least **6 GB of memory** and benefit from **2 vCPUs**. MongoDB, Redis, PostgreSQL, and other chart dependencies consume additional resources, and the cluster itself has overhead for system components (kube-proxy, monitoring agents, ingress controllers, etc.). Plan for a minimum of **2 nodes with 2 vCPUs and 8 GB of memory each**. -- A default `StorageClass` capable of provisioning persistent volumes with `allowVolumeExpansion: true` to avoid reprovisioning storage as data grows. +- A default `StorageClass` capable of provisioning persistent volumes. A StorageClass with `allowVolumeExpansion: true` is recommended to allow resizing volumes without reprovisioning. - An Ingress controller (such as [Traefik](https://doc.traefik.io/traefik/providers/kubernetes-ingress/) or an AWS/GCP load balancer controller) or a `LoadBalancer`-type Service to expose Appsmith to users. - Outbound network access to `cs.appsmith.com` for license validation and updates. @@ -24,7 +24,7 @@ If you are setting up a new cluster on AWS, see [Set up Kubernetes cluster on AW ### Client machine -- [Helm 3.14+](https://helm.sh/docs/intro/install/)—the Helm package manager. +- [Helm 3.14+](https://helm.sh/docs/intro/install/) (Helm 4 is also supported)—the Helm package manager. - [`kubectl`](https://kubernetes.io/docs/tasks/tools/)—configured to connect to your cluster. ## Install Appsmith @@ -40,18 +40,13 @@ Follow these steps to install Appsmith: helm repo update ``` -2. Look up the latest Appsmith release version: - - ```bash - APPSMITH_VERSION=$(curl -s https://api.github.com/repos/appsmithorg/appsmith/releases/latest | jq -r '.tag_name') - echo $APPSMITH_VERSION - ``` - -3. Create a `values.yaml` file with the following content: +2. Create a `values.yaml` file with the following content: ```yaml image: - tag: # paste the version from step 2 (e.g. v1.99) + # Required: pin to a release tag (e.g. v1.99) + # Find the latest version: https://github.com/appsmithorg/appsmith/releases/latest + tag: mongodb: enabled: false @@ -64,12 +59,19 @@ Follow these steps to install Appsmith: ingress: enabled: true - className: "" # leave blank for the cluster default, or set to your controller (e.g. traefik, alb) + # Required: set to match your Ingress controller (e.g. traefik, alb, nginx) + # List available controllers: kubectl get ingressclass + className: hosts: - host: appsmith.example.com ``` - Replace `appsmith.example.com` with your domain and set `className` to match your Ingress controller. This configures the chart to use the [MongoDB Kubernetes Operator](/getting-started/setup/instance-configuration/mongodb-kubernetes-operator) instead of the legacy Bitnami MongoDB subchart. For TLS configuration, see [Ingress and TLS](/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online). For the full list of configurable values, see the [chart README](https://github.com/appsmithorg/appsmith/tree/release/deploy/helm#parameters). + Replace the placeholder values before installing: + - ``—the release tag from the [GitHub releases page](https://github.com/appsmithorg/appsmith/releases/latest). + - ``—the name of your cluster's IngressClass. Run `kubectl get ingressclass` to see available options. + - `appsmith.example.com`—your domain. + + The MongoDB values configure the chart to use the [MongoDB Kubernetes Operator](/getting-started/setup/instance-configuration/mongodb-kubernetes-operator) instead of the legacy Bitnami MongoDB subchart. For TLS configuration, see [Ingress and TLS](/getting-started/setup/installation-guides/kubernetes/publish-appsmith-online). For the full list of configurable values, see the [chart README](https://github.com/appsmithorg/appsmith/tree/release/deploy/helm#parameters). 4. Deploy Appsmith: @@ -87,17 +89,25 @@ Follow these steps to install Appsmith: Proceed once all pods show `Running`. -6. If your ingress and DNS are already configured, open `https://appsmith.example.com`. Otherwise, use port-forward to verify the installation locally: +6. Verify the Ingress has been assigned an address by your controller: + + ```bash + kubectl get ingress -n appsmith-ee + ``` + + The `ADDRESS` column should show a hostname or IP. If it's empty, your Ingress controller isn't claiming the resource—check that `className` in your `values.yaml` matches your controller. + +7. If your DNS is already pointing to the Ingress address, open `https://appsmith.example.com`. Otherwise, use port-forward to verify the installation locally: ```bash - kubectl -n appsmith-ee port-forward appsmith-ee-0 8080:80 + kubectl -n appsmith-ee port-forward svc/appsmith-ee 8080:80 ``` Open [http://localhost:8080](http://localhost:8080) and wait for the server to come up. This can take up to 5 minutes. -7. Fill in your details to create an administrator account. +8. Fill in your details to create an administrator account. -8. Once you've created an account, you can either start with the free plan or activate your instance with a license key. If you want to generate a license key, sign up on [customer.appsmith.com](https://customer.appsmith.com) to create one, and then proceed to activate your instance using the newly generated license key. +9. Once you've created an account, you can either start with the free plan or activate your instance with a license key. If you want to generate a license key, sign up on [customer.appsmith.com](https://customer.appsmith.com) to create one, and then proceed to activate your instance using the newly generated license key. ## Next steps diff --git a/website/docs/getting-started/setup/instance-configuration/helm-chart.md b/website/docs/getting-started/setup/instance-configuration/helm-chart.md index 922802e479..2f48c966e6 100644 --- a/website/docs/getting-started/setup/instance-configuration/helm-chart.md +++ b/website/docs/getting-started/setup/instance-configuration/helm-chart.md @@ -36,7 +36,7 @@ The chart supports two workload modes, each with different storage behavior: | **Multi-replica / HA** | Deployment | Shared filesystem (`ReadWriteMany`)—[AWS EFS](https://docs.aws.amazon.com/eks/latest/userguide/efs-csi.html), [GCP Filestore](https://cloud.google.com/filestore/docs/csi-driver), Azure Files, NFS | 2+ | `workload.kind: Deployment`, `persistence.storageClass: ` | | **Existing claim** | Deployment | Pre-provisioned PVC | 1+ | `workload.kind: Deployment`, `persistence.existingClaim.enabled: true`, `persistence.existingClaim.claimName: ` | -Use a `StorageClass` that allows volume expansion (`allowVolumeExpansion: true`) to avoid reprovisioning storage as your data grows. +A `StorageClass` with `allowVolumeExpansion: true` is recommended to allow resizing volumes without reprovisioning. Changing the storage backend or switching between StatefulSet and Deployment on an existing release requires a migration—recreating volumes and the workload resource. See [Migrate to High Availability](/getting-started/setup/installation-guides/kubernetes/migrate-non-ha-to-ha-helm) for the procedure. Plan this before your first install. From bed00835e8ea19f1c69f22c9bcbc3c6ded2d0501 Mon Sep 17 00:00:00 2001 From: Wyatt Walter Date: Wed, 20 May 2026 10:56:31 -0500 Subject: [PATCH 09/11] docs: drop unnecessary Helm 4 note from prerequisites Co-Authored-By: Claude Opus 4.6 --- .../setup/installation-guides/kubernetes/README.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx b/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx index dfa35a2212..aabf71ea27 100644 --- a/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx +++ b/website/docs/getting-started/setup/installation-guides/kubernetes/README.mdx @@ -24,7 +24,7 @@ If you are setting up a new cluster on AWS, see [Set up Kubernetes cluster on AW ### Client machine -- [Helm 3.14+](https://helm.sh/docs/intro/install/) (Helm 4 is also supported)—the Helm package manager. +- [Helm 3.14+](https://helm.sh/docs/intro/install/)—the Helm package manager. - [`kubectl`](https://kubernetes.io/docs/tasks/tools/)—configured to connect to your cluster. ## Install Appsmith From 7cc46812153f56e19068dadc48cdc979156a630f Mon Sep 17 00:00:00 2001 From: Wyatt Walter Date: Wed, 20 May 2026 11:19:13 -0500 Subject: [PATCH 10/11] docs: fix migration guide issues found during testing - Run mongodump/mongorestore from operator pod (Bitnami image lacks the database tools) - Use operator's connection secret for DEST_URI instead of hand-constructed URI - Add explicit PHASE=Running gate before proceeding past step 1 - Add pod termination verification command to step 2 - Clarify step 4 describes connection rewiring - Add backup recommendation before starting migration Co-Authored-By: Claude Opus 4.6 --- .../mongodb-kubernetes-operator.md | 29 ++++++++++++------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/website/docs/getting-started/setup/instance-configuration/mongodb-kubernetes-operator.md b/website/docs/getting-started/setup/instance-configuration/mongodb-kubernetes-operator.md index c8e8adb86d..0e5b60457c 100644 --- a/website/docs/getting-started/setup/instance-configuration/mongodb-kubernetes-operator.md +++ b/website/docs/getting-started/setup/instance-configuration/mongodb-kubernetes-operator.md @@ -90,6 +90,8 @@ If you have an existing Appsmith install using the Bitnami MongoDB subchart, fol Test this procedure on a non-production cluster first. The migration requires downtime while Appsmith is scaled down, data is exported and imported, and the deployment is reconfigured. ::: +Before starting, [back up your Appsmith instance](/getting-started/setup/instance-management/backup-and-restore/backup-instance?current-command-type=kubernetes-commands) so you can restore if anything goes wrong. + ### Overview The migration follows an expand-move-contract pattern. First, deploy the MongoDB Operator alongside your existing Bitnami instance so both are running. Then scale down Appsmith to stop writes, export data from Bitnami, and import it into the operator-managed MongoDB. Finally, reconfigure the release to use the new MongoDB and remove the old Bitnami resources. @@ -111,12 +113,14 @@ helm upgrade appsmith-ee appsmith-ee/appsmith -n appsmith-ee --wait --timeout 10 --set mongodbOperator.enabled=true ``` -Wait for the operator-managed MongoDB to reach a `Running` phase: +Wait for the operator-managed MongoDB to reach a `Running` phase before proceeding: ```bash kubectl get mongodbcommunity -n appsmith-ee -w ``` +Do not continue until the `PHASE` column shows `Running`. + ### Step 2: Scale down Appsmith Once the operator-managed MongoDB is running, stop the Appsmith workload to prevent writes during the data migration. @@ -136,7 +140,13 @@ kubectl patch hpa appsmith-ee -n appsmith-ee --patch '{"spec":{"minReplicas":0}} kubectl scale deployment appsmith-ee -n appsmith-ee --replicas=0 ``` -Wait for all Appsmith pods to terminate before proceeding. +Wait for all Appsmith pods to terminate before proceeding: + +```bash +kubectl get pods -n appsmith-ee -l app.kubernetes.io/name=appsmith +``` + +The command should return no resources. ### Step 3: Export and import data @@ -145,28 +155,27 @@ Retrieve both connection strings—the existing Bitnami URI from the ConfigMap a ```bash SOURCE_URI=$(kubectl get cm appsmith-ee -n appsmith-ee -o jsonpath='{.data.APPSMITH_DB_URL}') -MONGO_PASS=$(kubectl get secret appsmith-ee-mongo-password -n appsmith-ee \ - -o jsonpath='{.data.password}' | base64 -d) -DEST_URI="mongodb://appsmith:${MONGO_PASS}@appsmith-ee-mongo-0.appsmith-ee-mongo-svc.appsmith-ee.svc.cluster.local:27017/appsmith?authSource=appsmith" +DEST_URI=$(kubectl get secret appsmith-ee-mongo-appsmith-appsmith -n appsmith-ee \ + -o jsonpath='{.data.connectionString\.standardSrv}' | base64 -d) ``` -Dump from the Bitnami MongoDB and restore directly into the operator-managed instance, all from the Bitnami pod: +Dump from Bitnami and restore into the operator-managed instance. The Bitnami image does not include `mongodump`/`mongorestore`, so both commands run from the operator pod's `mongod` container: ```bash -# Dump the data -kubectl exec -n appsmith-ee appsmith-ee-mongodb-0 -- \ +# Dump from Bitnami MongoDB +kubectl exec -n appsmith-ee appsmith-ee-mongo-0 -c mongod -- \ mongodump --uri="$SOURCE_URI" \ --archive=/tmp/appsmith-dump.gz --gzip # Restore into the operator-managed MongoDB -kubectl exec -n appsmith-ee appsmith-ee-mongodb-0 -- \ +kubectl exec -n appsmith-ee appsmith-ee-mongo-0 -c mongod -- \ mongorestore --uri="$DEST_URI" \ --archive=/tmp/appsmith-dump.gz --gzip --drop ``` ### Step 4: Switch Appsmith to the new MongoDB -Upgrade the release to disable the Bitnami subchart. Helm will scale Appsmith back to its configured replica count: +Upgrade the release to disable the Bitnami subchart. This points Appsmith at the operator-managed MongoDB and removes the old Bitnami deployment. Helm will scale Appsmith back to its configured replica count: ```bash helm upgrade appsmith-ee appsmith-ee/appsmith -n appsmith-ee --wait --timeout 10m \ From 24ebe0c3f6e3c94f7c31e8ba3907f00a3c8db49a Mon Sep 17 00:00:00 2001 From: Wyatt Walter Date: Wed, 20 May 2026 11:20:14 -0500 Subject: [PATCH 11/11] docs: move backup recommendation inside caution box Co-Authored-By: Claude Opus 4.6 --- .../setup/instance-configuration/mongodb-kubernetes-operator.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/getting-started/setup/instance-configuration/mongodb-kubernetes-operator.md b/website/docs/getting-started/setup/instance-configuration/mongodb-kubernetes-operator.md index 0e5b60457c..9c979acb73 100644 --- a/website/docs/getting-started/setup/instance-configuration/mongodb-kubernetes-operator.md +++ b/website/docs/getting-started/setup/instance-configuration/mongodb-kubernetes-operator.md @@ -88,9 +88,9 @@ If you have an existing Appsmith install using the Bitnami MongoDB subchart, fol :::caution Test this procedure on a non-production cluster first. The migration requires downtime while Appsmith is scaled down, data is exported and imported, and the deployment is reconfigured. -::: Before starting, [back up your Appsmith instance](/getting-started/setup/instance-management/backup-and-restore/backup-instance?current-command-type=kubernetes-commands) so you can restore if anything goes wrong. +::: ### Overview