From b11ab757e6a4acce95ece68e1ae8502de2cc2dfe Mon Sep 17 00:00:00 2001 From: Luis Ibarra Date: Mon, 1 Jun 2026 18:03:40 -0500 Subject: [PATCH 1/2] docs: add infrastructure sizing guidance and update related documentation --- website/docs/getting-started/setup/README.md | 2 + .../getting-started/setup/best-practices.md | 7 +- .../setup/deployment-architecture.md | 9 +++ .../setup/environment-variables.md | 2 +- .../setup/infrastructure-sizing.md | 72 +++++++++++++++++++ .../setup/installation-guides/aws-ami.md | 7 +- .../aws-ecs/aws-ecs-on-ec2.md | 2 +- .../installation-guides/docker/README.mdx | 1 + website/sidebars.js | 1 + 9 files changed, 97 insertions(+), 6 deletions(-) create mode 100644 website/docs/getting-started/setup/infrastructure-sizing.md diff --git a/website/docs/getting-started/setup/README.md b/website/docs/getting-started/setup/README.md index fb67c6e3ed..b360e52069 100644 --- a/website/docs/getting-started/setup/README.md +++ b/website/docs/getting-started/setup/README.md @@ -15,6 +15,8 @@ Appsmith works best on AMD and ARM architectures on AWS, Azure, GCP, and Digital - Two virtual CPUs - 8 GB of memory +These values are a baseline for getting started. Production sizing depends on application workload, concurrency, and whether supporting services run locally or externally. For the full planning workflow, see [Infrastructure and capacity planning](/getting-started/setup/infrastructure-sizing). + You can follow one of the below guides to deploy Appsmith on the platform you prefer: - [Docker](/getting-started/setup/installation-guides/docker) (_Recommended_) diff --git a/website/docs/getting-started/setup/best-practices.md b/website/docs/getting-started/setup/best-practices.md index 5f117d056f..f9347ad3e6 100644 --- a/website/docs/getting-started/setup/best-practices.md +++ b/website/docs/getting-started/setup/best-practices.md @@ -19,9 +19,9 @@ Selecting the right platform and deployment method is crucial for the scalabilit - The preferred method for production environments is **Kubernetes**, as it supports high availability and scalability, managing Appsmith's dependencies like MongoDB and Redis within Kubernetes pods without requiring external instances. For more information, see [Kubernetes Installation](/getting-started/setup/installation-guides/kubernetes) guide. - If using serverless platforms such as **AWS ECS**, external instances of MongoDB and Redis must be provisioned, with **MongoDB Atlas** and **Elasticache** recommended. For more information, see [AWS ECS Installation](/getting-started/setup/installation-guides/aws-ecs/aws-ecs-on-ec2) guide. -- **Instance recommendations**: - - **Minimum instance size**: `t3.large` or equivalent (2 vCPU, 8 GB of memory). This should scale well for hundreds of users. - - **For 500 concurrent users**, we recommend `t3.xlarge` or larger instances. +- **Infrastructure and capacity planning**: + - **Baseline**: Start with **2 vCPU** and **8 GB of memory** for standard deployments. On AWS, the [AWS AMI](/getting-started/setup/installation-guides/aws-ami) guide lists **`t3.large`** or **`t3a.large`** as the minimum instance size. These are entry-level baselines for testing, evaluation, or low-traffic workloads—not fixed production capacity for a given user count. + - **Production sizing**: Capacity depends on application workload, concurrency, and whether MongoDB, Redis, and PostgreSQL run locally or as external services. For the full planning workflow, see [Infrastructure and capacity planning](/getting-started/setup/infrastructure-sizing). - **Free disk space**: Always ensure at least `10-15GB` of free space. - **Node separation**: For better data safety, keep separate node groups for **MongoDB**, **Redis**, **Postgres**, and the **Appsmith pod** in Kubernetes. @@ -85,5 +85,6 @@ Having a proper upgrade strategy ensures that your environment remains up-to-dat ## See also +- [Infrastructure and capacity planning](/getting-started/setup/infrastructure-sizing): Plan CPU, memory, and disk for your deployment. - [Manage Installation](/getting-started/setup/instance-configuration): Learn how to manage your Appsmith instance. - [Upgrade Installation Guides](/getting-started/setup/instance-management/): Learn how to upgrade your Appsmith installation. \ No newline at end of file diff --git a/website/docs/getting-started/setup/deployment-architecture.md b/website/docs/getting-started/setup/deployment-architecture.md index cc9bc539e3..6630cd4d84 100644 --- a/website/docs/getting-started/setup/deployment-architecture.md +++ b/website/docs/getting-started/setup/deployment-architecture.md @@ -6,6 +6,15 @@ description: The page provides information about the deployment architecture of Appsmith can be deployed as a single Docker container with a single volume for storing persistent data. For **production environments**, Appsmith recommends deploying Appsmith on a Kubernetes platform. This page provides an overview of the deployment architecture for Self-hosted Appsmith, focusing on its key components and their interactions in a Kubernetes-based environment. +## Capacity planning and supporting services + +How you deploy MongoDB, Redis, and PostgreSQL affects infrastructure sizing: + +- **Bundled in the same environment** — A single Docker container or an all-in-one compose stack runs embedded MongoDB, Redis, and PostgreSQL alongside Appsmith. Overall CPU, memory, and disk requirements are higher and can grow with workload, data, logging, and retention. +- **External or managed services** — When these stores run outside the Appsmith runtime (for example, MongoDB Atlas, Amazon ElastiCache, or Amazon RDS), Appsmith application containers generally need fewer and more predictable resources. + +For workload factors, baseline starting points, and a recommended sizing workflow, see [Infrastructure and capacity planning](/getting-started/setup/infrastructure-sizing). + ## Core components The Appsmith deployment architecture consists of several key components grouped by their purpose and functionality. These include the Appsmith server, customer data sources, Kubernetes pods, external managed services, and frontend architecture. The diagram below illustrates these key components, their interactions, and data flow when Appsmith is deployed on a Kubernetes platform: diff --git a/website/docs/getting-started/setup/environment-variables.md b/website/docs/getting-started/setup/environment-variables.md index 45a00579f1..07b2601cc2 100644 --- a/website/docs/getting-started/setup/environment-variables.md +++ b/website/docs/getting-started/setup/environment-variables.md @@ -326,7 +326,7 @@ If you prefer to host your Appsmith instance on a personalized domain, you can d ### Telemetry -Monitoring the performance of your Appsmith instance is crucial for making informed decisions about feature improvements and resource allocation. +Monitoring the performance of your Appsmith instance is crucial for making informed decisions about feature improvements and resource allocation. For capacity planning guidance, see [Infrastructure and capacity planning](/getting-started/setup/infrastructure-sizing). ##### `APPSMITH_DISABLE_TELEMETRY` diff --git a/website/docs/getting-started/setup/infrastructure-sizing.md b/website/docs/getting-started/setup/infrastructure-sizing.md new file mode 100644 index 0000000000..68f8e779af --- /dev/null +++ b/website/docs/getting-started/setup/infrastructure-sizing.md @@ -0,0 +1,72 @@ +--- +description: Guidance for planning CPU, memory, and disk capacity for self-hosted Appsmith deployments. +--- + +# Infrastructure and capacity planning + +Appsmith can provide baseline infrastructure guidance, but exact sizing depends heavily on the applications you build and how those applications are used. Appsmith is an application development platform, so two environments with the same number of users can have very different resource profiles. + +## What affects resource requirements + +When planning capacity, consider factors such as: + +- Number and complexity of apps +- Query and API volume +- Page load frequency and concurrency +- Size of datasets returned to the browser +- Use of JavaScript transformations, workflows, and integrations +- Authentication, Git, audit and logging, and other enterprise features +- High availability requirements and backup or retention policies + +## How deployment architecture affects sizing + +Deployment architecture significantly impacts sizing requirements. + +### Docker-based deployments + +For Docker-based deployments, sizing depends on whether **MongoDB**, **Redis**, and **PostgreSQL** are externalized services or running locally within the deployment stack: + +- **Externalized or managed services** — If MongoDB, Redis, and PostgreSQL run outside the Appsmith container (for example, MongoDB Atlas, Amazon ElastiCache, or Amazon RDS), Appsmith application containers generally require fewer and more predictable resources. +- **Services in the same Docker environment** — If these services run inside the same container or compose stack as Appsmith, overall CPU, memory, and disk requirements are higher and can vary substantially depending on workload, data growth, logging, and retention policies. + +For more information on externalizing data stores, see [Custom MongoDB](/getting-started/setup/instance-configuration/custom-mongodb-redis), [External Redis](/getting-started/setup/instance-configuration/external-redis), and [External PostgreSQL](/getting-started/setup/instance-configuration/external-postgresql-rds). + +### Kubernetes and production deployments + +For production environments where scalability and availability are important, **Kubernetes** is the recommended deployment model because it allows Appsmith services and dependencies to scale more cleanly. For more information, see the [Kubernetes installation](/getting-started/setup/installation-guides/kubernetes) guide and [Deployment Architecture](/getting-started/setup/deployment-architecture). + +## Baseline starting points + +Appsmith’s current self-hosting guidance recommends **2 vCPU** and **8 GB of memory** as a starting point for standard deployments. The [AWS AMI](/getting-started/setup/installation-guides/aws-ami) guide lists **`t3.large`** or **`t3a.large`** as the minimum instance size (2 vCPU, 8 GB memory). + +These recommendations should generally be viewed as **entry-level baselines** suitable for: + +- Testing and proof-of-concept environments +- Evaluation environments +- Low-traffic workloads + +They are not a guarantee of capacity for production use with sustained activity or heavy application workloads. + +For production environments with sustained activity or higher CPU utilization, consider newer-generation instance families with stronger CPU performance. **T3** instances use burstable CPU credits and can become a bottleneck under heavier or sustained workloads. + +## Recommended approach + +Follow this workflow when planning capacity for a self-hosted Appsmith deployment: + +1. **Choose a deployment model** — Start with the documented baseline for a non-HA deployment (for example, Docker or a single VM), or use [Kubernetes](/getting-started/setup/installation-guides/kubernetes) for production and high availability requirements. +2. **Decide on supporting services** — Determine whether MongoDB, Redis, and PostgreSQL will be externalized or hosted locally with Appsmith. +3. **Run a pilot** — Deploy using representative applications, data sources, and expected concurrent usage patterns. +4. **Monitor utilization** — Track CPU, memory, disk utilization, database growth, Redis usage, API latency, and application and page load times. +5. **Scale on observed workload** — Adjust capacity based on measured usage rather than named user counts alone. +6. **Load-test before production** — For larger or business-critical deployments, use a Kubernetes or HA architecture and conduct load testing before finalizing capacity. + +:::caution User count is not a reliable sizing metric +Avoid presenting a fixed VM or instance size as guaranteed for a given user count. User count alone does not predict resource needs. **Concurrent active usage** and **application workload** are more important indicators when sizing infrastructure. +::: + +## See also + +- [Self-hosting Best Practices](/getting-started/setup/best-practices) — Platform selection, HA, security, and operations +- [Deployment Architecture](/getting-started/setup/deployment-architecture) — Components and data flow +- [Helm Chart — Planning your deployment](/getting-started/setup/instance-configuration/helm-chart#planning-your-deployment) — Kubernetes architecture decisions before install +- [In-Memory Git (Redis-backed)](/getting-started/setup/instance-configuration/in-memory-git) — Additional memory and Redis sizing for Git workloads diff --git a/website/docs/getting-started/setup/installation-guides/aws-ami.md b/website/docs/getting-started/setup/installation-guides/aws-ami.md index 0d2ac5a273..52c12d7a15 100644 --- a/website/docs/getting-started/setup/installation-guides/aws-ami.md +++ b/website/docs/getting-started/setup/installation-guides/aws-ami.md @@ -17,6 +17,10 @@ This page provides steps to install Appsmith using an Amazon Machine Image (AMI) - Ensure you have created the security group and the SSH key pair in the same region. - Whitelist `cs.appsmith.com` in your security group’s outbound rules to allow outbound HTTPS traffic. If using a custom firewall, ensure these domains are permitted. +:::info Capacity planning +The minimum instance types listed below are entry-level baselines for evaluation and low-traffic workloads. Production sizing depends on application workload and usage patterns. See [Infrastructure and capacity planning](/getting-started/setup/infrastructure-sizing) before sizing for production. +::: + ## Install Appsmith Follow these steps to install Appsmith using an Amazon Machine Image (AMI): @@ -35,7 +39,7 @@ a. Configure the instance as below: | Attribute | Value | | ----------------- | ------------------------------------------------------------------------------- | | **Name** | Give a desired name. | -| **Instance type** | A minimum `t3.large` or `t3a.large` is needed. | +| **Instance type** | Minimum `t3.large` or `t3a.large` (2 vCPU, 8 GB memory) for evaluation and low-traffic workloads. For production sizing guidance, see [Infrastructure and capacity planning](/getting-started/setup/infrastructure-sizing). | | **Key pair** | Select the Key pair you created in the [Prerequisites](#prerequisites) section. | b. Scroll down to the **Networking** section, and configure as below: @@ -152,5 +156,6 @@ If you are facing issues during deployment, refer to the guide on [troubleshooti ## See also +- [Infrastructure and capacity planning](/getting-started/setup/infrastructure-sizing): Plan CPU, memory, and disk for your deployment. - [Manage Installation](/getting-started/setup/instance-configuration): Learn how to manage your Appsmith instance. - [Upgrade Installation Guides](/getting-started/setup/instance-management/): Learn how to upgrade your Appsmith installation. diff --git a/website/docs/getting-started/setup/installation-guides/aws-ecs/aws-ecs-on-ec2.md b/website/docs/getting-started/setup/installation-guides/aws-ecs/aws-ecs-on-ec2.md index 6d03568983..98d341b703 100644 --- a/website/docs/getting-started/setup/installation-guides/aws-ecs/aws-ecs-on-ec2.md +++ b/website/docs/getting-started/setup/installation-guides/aws-ecs/aws-ecs-on-ec2.md @@ -43,7 +43,7 @@ To deploy Appsmith on the Amazon ECS cluster that has a single node, you need to * **Provisioning Model**: Choose **On-demand** * **Auto Scaling Group**: Keep default selection * **Operating system/Architecture**: Amazon Linux 2 - * **EC2 instance type**: Select at least a `t3.large` or a `t3a.large` instance type (2 vCPU, 8 GB of memory). + * **EC2 instance type**: Select at least a `t3.large` or a `t3a.large` instance type (2 vCPU, 8 GB of memory) as an entry-level baseline for evaluation and low-traffic workloads. For production sizing guidance, see [Infrastructure and capacity planning](/getting-started/setup/infrastructure-sizing). * **Desired Capacity**: Give **Minimum** as 1 and **Maximum** as 2 * **SSH Key pair**: Use the key pair created in the [Prerequisites](#prerequisites) section Keep default settings for other attributes. diff --git a/website/docs/getting-started/setup/installation-guides/docker/README.mdx b/website/docs/getting-started/setup/installation-guides/docker/README.mdx index 5485669936..d9b094147f 100644 --- a/website/docs/getting-started/setup/installation-guides/docker/README.mdx +++ b/website/docs/getting-started/setup/installation-guides/docker/README.mdx @@ -20,6 +20,7 @@ Before you begin, ensure you have the following prerequisites: - [Docker](https://docs.docker.com/get-docker/) (version 20.10.7 or later) - [Docker-Compose](https://docs.docker.com/compose/install/) (version 1.29.2 or later) - Whitelist `cs.appsmith.com` in your firewall or security group’s outbound rules to ensure Docker can pull required images and dependencies. +- **Host memory**: The default Docker Compose setup runs MongoDB, Redis, and PostgreSQL inside the Appsmith container. Plan for at least **8 GB of RAM** on the host for this all-in-one deployment. If you externalize supporting services, the Appsmith container may need less host memory. See [Infrastructure and capacity planning](/getting-started/setup/infrastructure-sizing). ## Install Appsmith diff --git a/website/sidebars.js b/website/sidebars.js index 8fbac4b47f..f46b04ddb1 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -261,6 +261,7 @@ const sidebars = { items: [ `getting-started/setup/best-practices`, + 'getting-started/setup/infrastructure-sizing', 'getting-started/setup/deployment-architecture', ], } From 0f047f3a4a6e59715bb2b82e200e434d10331fa5 Mon Sep 17 00:00:00 2001 From: Luis Ibarra Date: Mon, 1 Jun 2026 18:08:00 -0500 Subject: [PATCH 2/2] docs: standardize formatting in deployment architecture and infrastructure sizing documentation --- .../setup/deployment-architecture.md | 4 ++-- .../setup/infrastructure-sizing.md | 24 +++++++++---------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/website/docs/getting-started/setup/deployment-architecture.md b/website/docs/getting-started/setup/deployment-architecture.md index 6630cd4d84..7c4da74212 100644 --- a/website/docs/getting-started/setup/deployment-architecture.md +++ b/website/docs/getting-started/setup/deployment-architecture.md @@ -10,8 +10,8 @@ Appsmith can be deployed as a single Docker container with a single volume for s How you deploy MongoDB, Redis, and PostgreSQL affects infrastructure sizing: -- **Bundled in the same environment** — A single Docker container or an all-in-one compose stack runs embedded MongoDB, Redis, and PostgreSQL alongside Appsmith. Overall CPU, memory, and disk requirements are higher and can grow with workload, data, logging, and retention. -- **External or managed services** — When these stores run outside the Appsmith runtime (for example, MongoDB Atlas, Amazon ElastiCache, or Amazon RDS), Appsmith application containers generally need fewer and more predictable resources. +- **Bundled in the same environment**: A single Docker container or an all-in-one compose stack runs embedded MongoDB, Redis, and PostgreSQL alongside Appsmith. Overall CPU, memory, and disk requirements are higher and can grow with workload, data, logging, and retention. +- **External or managed services**: When these stores run outside the Appsmith runtime (for example, MongoDB Atlas, Amazon ElastiCache, or Amazon RDS), Appsmith application containers generally need fewer and more predictable resources. For workload factors, baseline starting points, and a recommended sizing workflow, see [Infrastructure and capacity planning](/getting-started/setup/infrastructure-sizing). diff --git a/website/docs/getting-started/setup/infrastructure-sizing.md b/website/docs/getting-started/setup/infrastructure-sizing.md index 68f8e779af..1bd3583ebd 100644 --- a/website/docs/getting-started/setup/infrastructure-sizing.md +++ b/website/docs/getting-started/setup/infrastructure-sizing.md @@ -26,8 +26,8 @@ Deployment architecture significantly impacts sizing requirements. For Docker-based deployments, sizing depends on whether **MongoDB**, **Redis**, and **PostgreSQL** are externalized services or running locally within the deployment stack: -- **Externalized or managed services** — If MongoDB, Redis, and PostgreSQL run outside the Appsmith container (for example, MongoDB Atlas, Amazon ElastiCache, or Amazon RDS), Appsmith application containers generally require fewer and more predictable resources. -- **Services in the same Docker environment** — If these services run inside the same container or compose stack as Appsmith, overall CPU, memory, and disk requirements are higher and can vary substantially depending on workload, data growth, logging, and retention policies. +- **Externalized or managed services**: If MongoDB, Redis, and PostgreSQL run outside the Appsmith container (for example, MongoDB Atlas, Amazon ElastiCache, or Amazon RDS), Appsmith application containers generally require fewer and more predictable resources. +- **Services in the same Docker environment**: If these services run inside the same container or compose stack as Appsmith, overall CPU, memory, and disk requirements are higher and can vary substantially depending on workload, data growth, logging, and retention policies. For more information on externalizing data stores, see [Custom MongoDB](/getting-started/setup/instance-configuration/custom-mongodb-redis), [External Redis](/getting-started/setup/instance-configuration/external-redis), and [External PostgreSQL](/getting-started/setup/instance-configuration/external-postgresql-rds). @@ -53,12 +53,12 @@ For production environments with sustained activity or higher CPU utilization, c Follow this workflow when planning capacity for a self-hosted Appsmith deployment: -1. **Choose a deployment model** — Start with the documented baseline for a non-HA deployment (for example, Docker or a single VM), or use [Kubernetes](/getting-started/setup/installation-guides/kubernetes) for production and high availability requirements. -2. **Decide on supporting services** — Determine whether MongoDB, Redis, and PostgreSQL will be externalized or hosted locally with Appsmith. -3. **Run a pilot** — Deploy using representative applications, data sources, and expected concurrent usage patterns. -4. **Monitor utilization** — Track CPU, memory, disk utilization, database growth, Redis usage, API latency, and application and page load times. -5. **Scale on observed workload** — Adjust capacity based on measured usage rather than named user counts alone. -6. **Load-test before production** — For larger or business-critical deployments, use a Kubernetes or HA architecture and conduct load testing before finalizing capacity. +1. **Choose a deployment model**: Start with the documented baseline for a non-HA deployment (for example, Docker or a single VM), or use [Kubernetes](/getting-started/setup/installation-guides/kubernetes) for production and high availability requirements. +2. **Decide on supporting services**: Determine whether MongoDB, Redis, and PostgreSQL will be externalized or hosted locally with Appsmith. +3. **Run a pilot**: Deploy using representative applications, data sources, and expected concurrent usage patterns. +4. **Monitor utilization**: Track CPU, memory, disk utilization, database growth, Redis usage, API latency, and application and page load times. +5. **Scale on observed workload**: Adjust capacity based on measured usage rather than named user counts alone. +6. **Load-test before production**: For larger or business-critical deployments, use a Kubernetes or HA architecture and conduct load testing before finalizing capacity. :::caution User count is not a reliable sizing metric Avoid presenting a fixed VM or instance size as guaranteed for a given user count. User count alone does not predict resource needs. **Concurrent active usage** and **application workload** are more important indicators when sizing infrastructure. @@ -66,7 +66,7 @@ Avoid presenting a fixed VM or instance size as guaranteed for a given user coun ## See also -- [Self-hosting Best Practices](/getting-started/setup/best-practices) — Platform selection, HA, security, and operations -- [Deployment Architecture](/getting-started/setup/deployment-architecture) — Components and data flow -- [Helm Chart — Planning your deployment](/getting-started/setup/instance-configuration/helm-chart#planning-your-deployment) — Kubernetes architecture decisions before install -- [In-Memory Git (Redis-backed)](/getting-started/setup/instance-configuration/in-memory-git) — Additional memory and Redis sizing for Git workloads +- [Self-hosting Best Practices](/getting-started/setup/best-practices): Platform selection, HA, security, and operations +- [Deployment Architecture](/getting-started/setup/deployment-architecture): Components and data flow +- [Helm Chart: Planning your deployment](/getting-started/setup/instance-configuration/helm-chart#planning-your-deployment): Kubernetes architecture decisions before install +- [In-Memory Git (Redis-backed)](/getting-started/setup/instance-configuration/in-memory-git): Additional memory and Redis sizing for Git workloads