@vendure/docs 0.0.0-202601161541

package/docs/guides/deployment/horizontal-scaling.md

@@ -0,0 +1,75 @@
+---
+title: "Horizontal scaling"
+showtoc: true
+weight: 2
+---
+
+# Horizontal scaling
+
+"Horizontal scaling" refers to increasing the performance capacity of your application by running multiple instances.
+
+This type of scaling has two main advantages:
+
+1. It can enable increased throughput (requests/second) by distributing the incoming requests between multiple instances.
+2. It can increase resilience because if a single instance fails, the other instances will still be able to service requests.
+
+As discussed in the [Server resource requirements guide](/guides/deployment/server-resource-requirements), horizontal scaling can be the most cost-effective way of deploying your Vendure server due to the single-threaded nature of Node.js.
+
+In Vendure, both the server and the worker can be scaled horizontally. Scaling the server will increase the throughput of the GraphQL APIs, whereas scaling the worker can increase the speed with which the job queue is processed by allowing more jobs to be run in parallel.
+
+## Multi-instance configuration
+
+In order to run Vendure in a multi-instance configuration, there are some important configuration changes you'll need to make. The key consideration in configuring Vendure for this scenario is to ensure that any persistent state is managed externally from the Node process, and is shared by all instances. Namely:
+
+* The JobQueue should be stored externally using the [DefaultJobQueuePlugin](/reference/typescript-api/job-queue/default-job-queue-plugin/) (which stores jobs in the database) or the [BullMQJobQueuePlugin](/reference/core-plugins/job-queue-plugin/bull-mqjob-queue-plugin) (which stores jobs in Redis), or some other custom JobQueueStrategy. **Note:** the BullMQJobQueuePlugin is much more efficient than the DefaultJobQueuePlugin, and is recommended for production applications.
+* An appropriate [CacheStrategy](/reference/typescript-api/cache/cache-strategy/) must be used which stores the cache externally. Both the [DefaultCachePlugin](/reference/typescript-api/cache/default-cache-plugin/) and the [RedisCachePlugin](/reference/typescript-api/cache/redis-cache-plugin/) are suitable 
+  for multi-instance setups. The DefaultCachePlugin uses the database to store the cache data, which is simple and effective, while the RedisCachePlugin uses a Redis server to store the cache data and can have better performance characteristics.
+* If you are on a version prior to v3.1, a custom [SessionCacheStrategy](/reference/typescript-api/auth/session-cache-strategy/) must be used which stores the session cache externally (such as in the database or Redis), since the default strategy stores the cache in-memory and will cause inconsistencies in multi-instance setups. [Example Redis-based SessionCacheStrategy](/reference/typescript-api/auth/session-cache-strategy/).
+  From v3.1 the session cache is handled by the underlying cache strategy, so you normally don't need to define a custom SessionCacheStrategy.
+* When using cookies to manage sessions, make sure all instances are using the _same_ cookie secret:
+    ```ts title="src/vendure-config.ts"
+    const config: VendureConfig = {
+      authOptions: {
+        cookieOptions: {
+          secret: 'some-secret'
+        }
+      }
+    }
+    ```
+* Channel and Zone data gets cached in-memory as this data is used in virtually every request. The cache time-to-live defaults to 30 seconds, which is probably fine for most cases, but it can be configured in the [EntityOptions](/reference/typescript-api/configuration/entity-options/#channelcachettl).
+
+## Using Docker or Kubernetes
+
+One way of implementing horizontal scaling is to use Docker to wrap your Vendure server & worker in a container, which can then be run as multiple instances.
+
+Some hosting providers allow you to provide a Docker image and will then run multiple instances of that image. Kubernetes can also be used to manage multiple instances
+of a Docker image.
+
+For a more complete guide, see the [Using Docker guide](/guides/deployment/using-docker).
+
+## Using PM2
+
+[PM2](https://pm2.keymetrics.io/) is a process manager which will spawn multiple instances of your server or worker, as well as re-starting any instances that crash. PM2 can be used on VPS hosts to manage multiple instances of Vendure without needing Docker or Kubernetes.
+
+PM2 must be installed on your server:
+
+```sh
+npm install pm2@latest -g
+```
+
+Your processes can then be run in [cluster mode](https://pm2.keymetrics.io/docs/usage/cluster-mode/) with the following command:
+
+```sh
+pm2 start ./dist/index.js -i 4
+```
+
+The above command will start a cluster of 4 instances. You can also instruct PM2 to use the maximum number of available CPUs with `-i max`.
+
+Note that if you are using pm2 inside a Docker container, you should use the `pm2-runtime` command:
+
+```dockerfile
+# ... your existing Dockerfile config
+RUN npm install pm2 -g
+
+CMD ["pm2-runtime", "app.js", "-i", "max"]
+```

package/docs/guides/deployment/production-configuration/index.md

@@ -0,0 +1,140 @@
+---
+title: 'Production configuration'
+showtoc: true
+weight: 0
+---
+
+# Production configuration
+
+This is a guide to the recommended configuration for a production Vendure application.
+
+## Environment variables
+
+Keep sensitive information or context-dependent settings in environment variables. In local development you can store the values in a `.env` file. For production, you should use the mechanism provided by your hosting platform to set the values for production.
+
+The default `@vendure/create` project scaffold makes use of environment variables already. For example:
+
+```ts
+const IS_DEV = process.env.APP_ENV === 'dev';
+```
+
+The `APP_ENV` environment variable can then be set using the admin dashboard of your hosting provider:
+
+![A typical UI for setting env vars](./env-var-ui.webp)
+
+If you are using [Docker or Kubernetes](/guides/deployment/using-docker), they include their own methods of setting environment variables.
+
+## Superadmin credentials
+
+Ensure you set the superadmin credentials to something other than the default of `superadmin:superadmin`. Use your hosting platform's environment variables to set a **strong** password for the Superadmin account.
+
+```ts
+import { VendureConfig } from '@vendure/core';
+
+export const config: VendureConfig = {
+  authOptions: {
+    tokenMethod: ['bearer', 'cookie'],
+    superadminCredentials: {
+      identifier: process.env.SUPERADMIN_USERNAME,
+      password: process.env.SUPERADMIN_PASSWORD,
+    },
+  },
+  // ...
+};
+```
+
+## API hardening
+
+It is recommended that you install and configure the [HardenPlugin](/reference/core-plugins/harden-plugin/) for all production deployments. This plugin locks down your schema (disabling introspection and field suggestions) and protects your Shop API against malicious queries that could otherwise overwhelm your server.
+
+Install the plugin: 
+
+```sh
+npm install @vendure/harden-plugin
+
+# or
+
+yarn add @vendure/harden-plugin
+```
+
+Then add it to your VendureConfig:
+
+```ts
+import { VendureConfig } from '@vendure/core';
+import { HardenPlugin } from '@vendure/harden-plugin';
+
+const IS_DEV = process.env.APP_ENV === 'dev';
+
+export const config: VendureConfig = {
+  // ...
+  plugins: [
+    HardenPlugin.init({
+      maxQueryComplexity: 500,
+      apiMode: IS_DEV ? 'dev' : 'prod',
+    }),
+    // ...
+  ]
+};
+```
+
+:::info
+For a detailed explanation of how to best configure this plugin, see the [HardenPlugin docs](/reference/core-plugins/harden-plugin/).
+:::
+
+## ID Strategy
+
+By default, Vendure uses auto-increment integer IDs as entity primary keys. While easier to work with in development, sequential primary keys can leak information such as the number of orders or customers in the system.
+
+For this reason you should consider using the UuidIdStrategy for production.
+
+```ts title="src/vendure-config.ts"
+import { UuidIdStrategy, VendureConfig } from '@vendure/core';
+
+export const config: VendureConfig = {
+    entityOptions: {
+        entityIdStrategy: new UuidIdStrategy(),
+    },
+    // ...
+}
+```
+
+Another option, if you wish to stick with integer IDs, is to create a custom [EntityIdStrategy](/reference/typescript-api/configuration/entity-id-strategy/) which uses the `encodeId()` and `decodeId()` methods to obfuscate the sequential nature of the ID.
+
+## Database Timezone
+
+Vendure internally treats all dates & times as UTC. However, you may sometimes run into issues where dates are offset by some fixed amount of hours. E.g. you place an order at 17:00, but it shows up in the Dashboard as being placed at 19:00. Typically, this is caused by the timezone of your database not being set to UTC.
+
+You can check the timezone in **MySQL/MariaDB** by executing:
+
+```SQL
+SELECT TIMEDIFF(NOW(), UTC_TIMESTAMP);
+```
+and you should expect to see `00:00:00`.
+
+In **Postgres**, you can execute:
+```SQL
+show timezone;
+```
+and you should expect to see `UTC` or `Etc/UTC`.
+
+## Trust proxy
+
+When deploying your Vendure application behind a reverse proxy (usually the case with most hosting services), consider configuring Express's `trust proxy` setting. This allows you to retrieve the original IP address from the `X-Forwarded-For` header, which proxies use to forward the client's IP address.
+
+You can set the `trustProxy` option in your `VendureConfig`:
+
+```ts
+import { VendureConfig } from '@vendure/core';
+
+export const config: VendureConfig = {
+    apiOptions: {
+        trustProxy: 1, // Trust the first proxy in front of your app
+    },
+};
+```
+
+For more details on configuring `trust proxy`, refer to the [Express documentation](https://expressjs.com/en/guide/behind-proxies.html).
+
+## Security Considerations
+
+Please read over the [Security](/guides/developer-guide/security) section of the Developer Guide for more information on how to secure your Vendure application.

package/docs/guides/deployment/server-resource-requirements.md

@@ -0,0 +1,29 @@
+---
+title: 'Server resource requirements'
+showtoc: true
+weight: 1
+---
+
+## Server resource requirements
+
+### RAM
+
+The Vendure server and worker process each use around 200-300MB of RAM when idle. This figure will increase under load.
+
+The total RAM required by a single instance of the server depends on your project size (the number of products, variants, customers, orders etc.) as well as expected load (the number of concurrent users you expect). As a rule, 512MB per process would be a practical minimum for a smaller project with low expected load.
+
+### CPU
+
+CPU resources are generally measured in "cores" or "vCPUs" (virtual CPUs) depending on the type of hosting. The exact relationship between vCPUs and physical CPU cores is out of the scope of this guide, but for our purposes we will use "CPU" to refer to both physical and virtual CPU resources.
+
+Because Node.js is single-threaded, a single instance of the Vendure server or worker will not be able to take advantage of multiple CPUs. For example, if you set up a server instance running with 4 CPUs, the server will only use 1 of those CPUs and the other 3 will be wasted.
+
+Therefore, when looking to optimize performance (for example, the number of requests that can be serviced per second), it makes sense to scale horizontally by running multiple instances of the Vendure server. See the [Horizontal Scaling guide](/guides/deployment/horizontal-scaling).
+
+## Load testing
+
+It is important to test whether your current server configuration will be able to handle the loads you expect when you go into production. There are numerous tools out there to help you load test your application, such as:
+
+- [k6](https://k6.io/)
+- [Artillery](https://www.artillery.io/)
+- [jMeter](https://jmeter.apache.org/)

package/docs/guides/deployment/using-docker.md

@@ -0,0 +1,193 @@
+---
+title: "Using docker"
+showtoc: true
+weight: 3
+---
+
+# Using Docker
+
+[Docker](https://docs.docker.com/) is a technology which allows you to run your Vendure application inside a [container](https://docs.docker.com/get-started/#what-is-a-container).
+The default installation with `@vendure/create` includes a sample Dockerfile:
+
+```dockerfile title="Dockerfile"
+FROM node:22
+
+WORKDIR /usr/src/app
+
+COPY package.json ./
+COPY package-lock.json ./ 
+RUN npm install --production
+COPY . .
+RUN npm run build
+```
+
+This Dockerfile can then be built into an "image" using:
+
+```sh
+docker build -t vendure .
+```
+
+This same image can be used to run both the Vendure server and the worker:
+
+```sh
+# Run the server
+docker run -dp 3000:3000 --name vendure-server vendure npm run start:server
+
+# Run the worker
+docker run -dp 3000:3000 --name vendure-worker vendure npm run start:worker
+```
+
+Here is a breakdown of the command used above:
+
+- `docker run` - run the image we created with `docker build`
+- `-dp 3000:3000` - the `-d` flag means to run in "detached" mode, so it runs in the background and does not take control of your terminal. `-p 3000:3000` means to expose port 3000 of the container (which is what Vendure listens on by default) as port 3000 on your host machine.
+- `--name vendure-server` - we give the container a human-readable name.
+- `vendure` - we are referencing the tag we set up during the build.
+- `npm run start:server` - this last part is the actual command that should be run inside the container.
+
+## Docker Compose
+
+Managing multiple docker containers can be made easier using [Docker Compose](https://docs.docker.com/compose/). In the below example, we use 
+the same Dockerfile defined above, and we also define a Postgres database to connect to:
+
+```yaml
+version: "3"
+services:
+  server:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - 3000:3000
+    command: ["npm", "run", "start:server"]
+    volumes:
+      - /usr/src/app
+    environment:
+      DB_HOST: database
+      DB_PORT: 5432
+      DB_NAME: vendure
+      DB_USERNAME: postgres
+      DB_PASSWORD: password
+  worker:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    command: ["npm", "run", "start:worker"]
+    volumes:
+      - /usr/src/app
+    environment:
+      DB_HOST: database
+      DB_PORT: 5432
+      DB_NAME: vendure
+      DB_USERNAME: postgres
+      DB_PASSWORD: password
+  database:
+    image: postgres
+    volumes:
+      - /var/lib/postgresql/data
+    ports:
+      - 5432:5432
+    environment:
+      POSTGRES_PASSWORD: password
+      POSTGRES_DB: vendure
+```
+
+## Kubernetes
+
+[Kubernetes](https://kubernetes.io/) is used to manage multiple containerized applications. 
+This deployment starts the shop container we created above as both worker and server.
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: vendure-shop
+spec:
+  selector:
+    matchLabels:
+      app: vendure-shop
+  replicas: 1
+  template:
+    metadata:
+      labels:
+        app: vendure-shop
+    spec:
+      containers:
+        - name: server
+          image: vendure-shop:latest
+          command:
+            - node
+          args:
+            - "dist/index.js"
+          env:
+          # your env config here
+          ports:
+            - containerPort: 3000
+
+        - name: worker
+          image: vendure-shop:latest
+          imagePullPolicy: Always
+          command:
+            - node
+          args:
+            - "dist/index-worker.js"
+          env:
+          # your env config here
+          ports:
+            - containerPort: 3000
+```
+
+## Health/Readiness Checks
+
+If you wish to deploy with Kubernetes or some similar system, you can make use of the health check endpoints. 
+
+### Server
+
+This is a regular REST route (note: _not_ GraphQL), available at `/health`.
+
+```text 
+REQUEST: GET http://localhost:3000/health
+```
+ 
+```json
+{
+  "status": "ok",
+  "info": {
+    "database": {
+      "status": "up"
+    }
+  },
+  "error": {},
+  "details": {
+    "database": {
+      "status": "up"
+    }
+  }
+}
+```
+
+Health checks are built on the [Nestjs Terminus module](https://docs.nestjs.com/recipes/terminus). You can also add your own health checks by creating plugins that make use of the [HealthCheckRegistryService](/reference/typescript-api/health-check/health-check-registry-service/).
+
+### Worker
+
+Although the worker is not designed as an HTTP server, it contains a minimal HTTP server specifically to support HTTP health checks. To enable this, you need to call the `startHealthCheckServer()` method after bootstrapping the worker:
+
+```ts
+bootstrapWorker(config)
+    .then(worker => worker.startJobQueue())
+    .then(worker => worker.startHealthCheckServer({ port: 3020 }))
+    .catch(err => {
+        console.log(err);
+    });
+```
+This will make the `/health` endpoint available. When the worker instance is running, it will return the following:
+
+```text 
+REQUEST: GET http://localhost:3020/health
+```
+
+```json
+{
+  "status": "ok"
+}
+```