@vendure/docs 0.0.0-202601161541

package/docs/guides/deployment/deploy-to-railway/index.md

@@ -0,0 +1,202 @@
+---
+title: "Deploying to Railway"
+---
+
+![Deploy to Railway](./deploy-to-railway.webp)
+
+[Railway](https://railway.app/) is a managed hosting platform which allows you to deploy and scale your Vendure server and infrastructure with ease.
+
+:::note
+This guide should be runnable on the Railway free trial plan, which means you can deploy it for free and thereafter
+pay only for the resources you use, which should be around $5 per month.
+:::
+
+## Prerequisites
+
+First of all you'll need to create a new Railway account (click "login" on the website and enter your email address) if you
+don't already have one.
+
+You'll also need a GitHub account and you'll need to have your Vendure project hosted there. 
+
+In order to use the Railway trial plan, you'll need to connect your GitHub account to Railway via the Railway dashboard.
+
+:::info
+If you'd like to quickly get started with a ready-made Vendure project which includes sample data, you can clone our
+[Vendure one-click-deploy repo](https://github.com/vendurehq/one-click-deploy).
+:::
+
+## Configuration
+
+### Port
+
+Railway defines the port via the `PORT` environment variable, so make sure your Vendure Config uses this variable:
+
+```ts title="src/vendure-config.ts"
+import { VendureConfig } from '@vendure/core';
+
+export const config: VendureConfig = {
+    apiOptions: {
+        // highlight-next-line
+        port: +(process.env.PORT || 3000),
+        // ...
+    },
+    // ...
+};
+```
+
+### Database connection
+
+:::info
+The following is already pre-configured if you are using the one-click-deploy repo.
+:::
+
+Make sure your DB connection options uses the following environment variables:
+
+```ts title="src/vendure-config.ts"
+import { VendureConfig } from '@vendure/core';
+
+export const config: VendureConfig = {
+    // ...
+    dbConnectionOptions: {
+        // ...
+        database: process.env.DB_NAME,
+        host: process.env.DB_HOST,
+        port: +process.env.DB_PORT,
+        username: process.env.DB_USERNAME,
+        password: process.env.DB_PASSWORD,
+    },
+};
+```
+### Asset storage
+
+:::info
+The following is already pre-configured if you are using the one-click-deploy repo.
+:::
+
+In this guide we will use the AssetServerPlugin's default local disk storage strategy. Make sure you use the
+`ASSET_UPLOAD_DIR` environment variable to set the path to the directory where the uploaded assets will be stored.
+
+```ts title="src/vendure-config.ts"
+import { VendureConfig } from '@vendure/core';
+import { AssetServerPlugin } from '@vendure/asset-server-plugin';
+
+export const config: VendureConfig = {
+    // ...
+    plugins: [
+        AssetServerPlugin.init({
+            route: 'assets',
+            // highlight-next-line
+            assetUploadDir: process.env.ASSET_UPLOAD_DIR || path.join(__dirname, '../static/assets'),
+        }),
+    ],
+    // ...
+};
+```
+
+## Create a new Railway project
+
+From the Railway dashboard, click "New Project" and select "Empty Project". You'll be taken to a screen where you can
+add the first service to your project. 
+
+## Create the database
+
+Click the "Add a Service" button and select "database". Choose a database that matches the one you are using in your
+Vendure project. If you are following along using the one-click-deploy repo, then choose "Postgres".
+
+## Create the Vendure server
+
+Click the "new" button to create a new service, and select "GitHub repo". Select the repository which contains your
+Vendure project. You may need to configure access to this repo if you haven't already done so.
+
+![Create new service](./01-new-service.webp)
+
+### Configure the server service
+
+You should then see a card representing this service in the main area of the dashboard. Click the card and go to the
+"settings" tab.
+
+* Scroll to the "Service" section and rename the service to "vendure-server".
+* Check the "Build" section and make sure the build settings make sense for your repo. If you are using
+the one-click-deploy repo, then it should detect the Dockerfile.
+* In the "Deploy" section, set the "Custom start command" to `node ./dist/index.js`.
+* Finally, scroll up to the "Networking" section and click "Generate domain" to set up a temporary domain for your
+Vendure server.
+
+### Create a Volume
+
+In order to persist the uploaded product images, we need to create a volume. Click the "new" button and select "Volume".
+Attach it to the "vendure-server" service and set the mount path to `/vendure-assets`.
+
+### Configure server env vars
+
+Click on the "vendure-server" service and go to the "Variables" tab. This is where we will set up the environment
+variables which are used in our Vendure Config. You can use the raw editor to add the following variables, making
+sure to replace the highlighted values with your own:
+
+```sh
+DB_NAME=${{Postgres.PGDATABASE}}
+DB_USERNAME=${{Postgres.PGUSER}}
+DB_PASSWORD=${{Postgres.PGPASSWORD}}
+DB_HOST=${{Postgres.PGHOST}}
+DB_PORT=${{Postgres.PGPORT}}
+ASSET_UPLOAD_DIR=/vendure-assets
+// highlight-next-line
+COOKIE_SECRET=<add some random characters>
+SUPERADMIN_USERNAME=superadmin
+// highlight-next-line
+SUPERADMIN_PASSWORD=<create some strong password>
+```
+
+![Setting env vars](./02-env-vars.webp) 
+
+:::note
+The variables starting with `${{Postgres...}}` assume that your database service is called "Postgres". If you have
+named it differently, then you'll need to change these variables accordingly.
+:::
+
+## Create the Vendure worker
+
+Finally, we need to define the worker process which will run the background tasks. Click the "new" button and select
+"GitHub repo". Select again the repository which contains your Vendure project. 
+
+### Configure the worker service
+
+You should then see a card representing this service in the main area of the dashboard. Click the card and go to the
+"settings" tab.
+
+* Scroll to the "Service" section and rename the service to "vendure-worker".
+* Check the "Build" section and make sure the build settings make sense for your repo. If you are using
+  the one-click-deploy repo, then it should detect the Dockerfile.
+* In the "Deploy" section, set the "Custom start command" to `node ./dist/index-worker.js`.
+
+### Configure worker env vars
+
+The worker will need to know how to connect to the database, so add the following variables to the "Variables" tab:
+
+```sh
+DB_NAME=${{Postgres.PGDATABASE}}
+DB_USERNAME=${{Postgres.PGUSER}}
+DB_PASSWORD=${{Postgres.PGPASSWORD}}
+DB_HOST=${{Postgres.PGHOST}}
+DB_PORT=${{Postgres.PGPORT}}
+```
+
+## Test your Vendure server
+
+To test that everything is working, click the "vendure-server" card and then the link to the temporary domain.
+
+![Test server](./03-test-server.webp)
+
+## Next Steps
+
+This setup gives you a basic Vendure server to get started with. When moving to a more production-ready setup, you'll
+want to consider the following:
+
+- Use MinIO for asset storage. This is a more robust and scalable solution than the local disk storage used here. 
+  - [MinIO template for Railway](https://railway.app/template/SMKOEA), 
+  - [Configuring the AssetServerPlugin for MinIO](/reference/core-plugins/asset-server-plugin/s3asset-storage-strategy/#usage-with-minio)
+- Use Redis to power the job queue and session cache. This is not only more performant, but will enable horizontal scaling of your
+server and worker instances.
+  - [Railway Redis docs](https://docs.railway.app/guides/redis)
+  - [Vendure horizontal scaling docs](/guides/deployment/horizontal-scaling)
+  

package/docs/guides/deployment/deploy-to-render/index.md

@@ -0,0 +1,221 @@
+---
+title: "Deploying to Render"
+---
+
+![Deploy to Render](./deploy-to-render.webp)
+
+[Render](https://render.com/) is a managed hosting platform which allows you to deploy and scale your Vendure server and infrastructure with ease.
+
+:::note
+The configuration in this guide will cost from around $12 per month to run.
+:::
+
+## Prerequisites
+
+First of all you'll need to [create a new Render account](https://dashboard.render.com/register) if you
+don't already have one.
+
+For this guide you'll need to have your Vendure project in a git repo on either GitHub or GitLab.
+
+:::info
+If you'd like to quickly get started with a ready-made Vendure project which includes sample data, you can use our
+[Vendure one-click-deploy repo](https://github.com/vendurehq/one-click-deploy), which means you won't have
+to set up your own git repo.
+:::
+
+## Configuration
+
+### Port
+
+Render defines the port via the `PORT` environment variable and [defaults to `10000`](https://docs.render.com/web-services#host-and-port-configuration), so make sure your Vendure Config uses this variable:
+
+```ts title="src/vendure-config.ts"
+import { VendureConfig } from '@vendure/core';
+
+export const config: VendureConfig = {
+    apiOptions: {
+        // highlight-next-line
+        port: +(process.env.PORT || 3000),
+        // ...
+    },
+    // ...
+};
+```
+
+### Database connection
+
+:::info
+The following is already pre-configured if you are using the one-click-deploy repo.
+:::
+
+Make sure your DB connection options uses the following environment variables:
+
+```ts title="src/vendure-config.ts"
+import { VendureConfig } from '@vendure/core';
+
+export const config: VendureConfig = {
+    // ...
+    dbConnectionOptions: {
+        // ...
+        database: process.env.DB_NAME,
+        host: process.env.DB_HOST,
+        port: +process.env.DB_PORT,
+        username: process.env.DB_USERNAME,
+        password: process.env.DB_PASSWORD,
+    },
+};
+```
+### Asset storage
+
+:::info
+The following is already pre-configured if you are using the one-click-deploy repo.
+:::
+
+In this guide we will use the AssetServerPlugin's default local disk storage strategy. Make sure you use the
+`ASSET_UPLOAD_DIR` environment variable to set the path to the directory where the uploaded assets will be stored.
+
+```ts title="src/vendure-config.ts"
+import { VendureConfig } from '@vendure/core';
+import { AssetServerPlugin } from '@vendure/asset-server-plugin';
+
+export const config: VendureConfig = {
+    // ...
+    plugins: [
+        AssetServerPlugin.init({
+            route: 'assets',
+            // highlight-next-line
+            assetUploadDir: process.env.ASSET_UPLOAD_DIR || path.join(__dirname, '../static/assets'),
+        }),
+    ],
+    // ...
+};
+```
+
+## Create a database
+
+From the Render dashboard, click the "New" button and select "PostgreSQL" from the list of services:
+
+![Create a new PostgreSQL database](./01-create-db.webp)
+
+Give the database a name (e.g. "postgres"), select a region close to you, select an appropriate plan
+and click "Create Database".
+
+## Create the Vendure server
+
+Click the "New" button again and select "Web Service" from the list of services. Choose the "Build and deploy from a Git repository" option.
+
+In the next step you will be prompted to connect to either GitHub or GitLab. Select the appropriate option and follow the instructions
+to connect your account and grant access to the repository containing your Vendure project.
+
+:::info
+If you are using the one-click-deploy repo, you should instead use the "Public Git repository" option and enter the URL of the repo:
+
+```
+https://github.com/vendurehq/one-click-deploy
+```
+:::
+
+### Configure the server service
+
+In the next step you will configure the server:
+
+- **Name**: "vendure-server"
+- **Region**: Select a region close to you
+- **Branch**: Select the branch you want to deploy, usually "main" or "master"
+- **Runtime**: If you have a Dockerfile then it should be auto-detected. If not you should select "Node" and enter the appropriate build and start commands. For a
+typical Vendure project these would be:
+  - **Build Command**: `yarn; yarn build` or `npm install; npm run build`
+  - **Start Command**: `node ./dist/index.js`
+- **Instance Type**: Select the appropriate instance type. Since we want to use a persistent volume to store our assets, we need to
+use at least the "Starter" instance type or higher.
+
+Click the "Advanced" button to expand the advanced options:
+
+- Click "Add Disk" to set up a persistent volume for the assets and use the following settings:
+  - **Name**: "vendure-assets"
+  - **Mount Path**: `/vendure-assets`
+  - **Size**: As appropriate. For testing purposes you can use the smallest size (1GB)
+- **Health Check Path**: `/health`
+- **Docker Command**: `node ./dist/index.js` (if you are _not_ using a Dockerfile this option will not be available)
+
+Click "Create Web Service" to create the service.
+
+:::note
+If you have not already set up payment, you will be prompted to enter credit card details at this point.
+:::
+
+## Configure environment variables
+
+Next we need to set up the environment variables which will be used by both the server and worker. Click the "Env Groups" tab
+and then click the "New Environment Group" button.
+
+Name the group "vendure configuration" and add the following variables. The database variables can be found by navigating
+to the database service, clicking the "Info" tab and scrolling to the "Connections" section:
+
+![Database connection settings](./03-db-connection.webp)
+
+```shell
+DB_NAME=<database "Database">
+DB_USERNAME=<database "Username">
+DB_PASSWORD=<database "Password">
+DB_HOST=<database "Hostname">
+DB_PORT=<database "Port">
+ASSET_UPLOAD_DIR=/vendure-assets
+// highlight-next-line
+COOKIE_SECRET=<add some random characters>
+SUPERADMIN_USERNAME=superadmin
+// highlight-next-line
+SUPERADMIN_PASSWORD=<create some strong password>
+```
+Once the correct values have been entered, click "Create Environment Group".
+
+Next, click the "vendure-server" service and go to the "Environment" tab to link the environment group to the service:
+
+![Link environment group](./04-link-env-group.webp)
+
+## Create the Vendure worker
+
+Finally, we need to define the worker process which will run the background tasks. Click the "New" button and select
+"Background Worker".
+
+Select the same git repo as before, and in the next step configure the worker:
+
+- **Name**: "vendure-worker"
+- **Region**: Same as the server
+- **Branch**: Select the branch you want to deploy, usually "main" or "master"
+- **Runtime**: If you have a Dockerfile then it should be auto-detected. If not you should select "Node" and enter the appropriate build and start commands. For a
+  typical Vendure project these would be:
+  - **Build Command**: `yarn; yarn build` or `npm install; npm run build`
+  - **Start Command**: `node ./dist/index-worker.js`
+- **Instance Type**: Select the appropriate instance type. The Starter size is fine to get started.
+
+Click the "Advanced" button to expand the advanced options:
+
+- **Docker Command**: `node ./dist/index-worker.js` (if you are _not_ using a Dockerfile this option will not be available)
+
+Click "Create Background Worker" to create the worker.
+
+Finally, click the "Environment" tab and link the "vendure configuration" environment group to the worker.
+
+## Test your Vendure server
+
+Navigate back to the dashboard, click the "vendure-server" service, and you should see a link to the temporary domain:
+
+![Test server](./05-server-url.webp)
+
+Click the link and append `/admin` to the URL to open the Admin UI. Log in with the username and password you set in the
+environment variables.
+
+## Next Steps
+
+This setup gives you a basic Vendure server to get started with. When moving to a more production-ready setup, you'll
+want to consider the following:
+
+- Use MinIO for asset storage. This is a more robust and scalable solution than the local disk storage used here.
+  - [Deploying MinIO to Render](https://docs.render.com/deploy-minio),
+  - [Configuring the AssetServerPlugin for MinIO](/reference/core-plugins/asset-server-plugin/s3asset-storage-strategy/#usage-with-minio)
+- Use Redis to power the job queue and session cache. This is not only more performant, but will enable horizontal scaling of your
+  server and worker instances.
+  - [Render Redis docs](https://docs.render.com/redis#creating-a-redis-instance)
+  - [Vendure horizontal scaling docs](/guides/deployment/horizontal-scaling)
+  

package/docs/guides/deployment/deploying-admin-ui.md

@@ -0,0 +1,130 @@
+---
+title: "Deploying the Admin UI"
+showtoc: true
+---
+
+## Compiling the Admin UI
+
+If you have customized the Admin UI with extensions, you should compile your custom Admin UI app ahead of time
+before deploying it. This will bundle the app into a set of static files which are then served by the AdminUiPlugin.
+
+- [Guide: Compiling the Admin UI as a deployment step](/guides/extending-the-admin-ui/getting-started/#compiling-as-a-deployment-step).
+
+:::warning
+
+It is not recommended to compile the Admin UI on the server at runtime, as this can be slow and resource-intensive.
+Instead, compile the Admin UI ahead of time and deploy the compiled assets, as covered in the guide linked above.
+:::
+
+## Setting the API host & port
+
+When running in development mode, the Admin UI app will "guess" the API host and port based on the current URL in the browser. Typically, this will
+be `http://localhost:3000`. For production deployments where the Admin UI app is served from a different host or port than the Vendure server, you'll need to
+configure the Admin UI app to point to the correct API host and port.
+
+```ts title="src/vendure-config.ts"
+import { VendureConfig } from '@vendure/core';
+import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
+
+const config: VendureConfig = {
+    // ...
+    plugins: [
+        AdminUiPlugin.init({
+            port: 3001,
+            route: 'admin',
+            adminUiConfig: {
+                apiHost: 'https://api.example.com',
+                apiPort: 443,
+            },
+        }),
+    ],
+};
+```
+
+## Deploying a stand-alone Admin UI
+
+Usually, the Admin UI is served from the Vendure server via the AdminUiPlugin. However, you may wish to deploy the Admin UI app elsewhere. Since it is just a static Angular app, it can be deployed to any static hosting service such as Vercel or Netlify.
+
+#### Metrics
+
+The AdminUiPlugin not only serves the Admin UI app, but also provides a `metricSummary` query which is used to display the order metrics on the dashboard. If you wish to deploy the Admin UI app stand-alone (not served by the AdminUiPlugin), but still want to display the metrics on the dashboard, you'll need to include the AdminUiPlugin in your server's plugins array, but do not call `init()`:
+
+```ts title="src/vendure-config.ts"
+import { AdminUiPlugin } from '@vendure/admin-ui-plugin';
+
+const config: VendureConfig = {
+    plugins: [
+        AdminUiPlugin, // <== include the plugin, but don't call init()
+    ],
+    // ...
+};
+```
+
+#### Example Script
+
+Here's an example script that can be run as part of your host's `build` command, which will generate a stand-alone app bundle and configure it to point to your remote server API.
+
+This example is for Vercel, and assumes:
+
+* A `BASE_HREF` environment variable to be set to `/`
+* A public (output) directory set to `build/dist`
+* A build command set to `npm run build` or `yarn build`
+* A package.json like this:
+    ```json title="package.json"
+    {
+      "name": "standalone-admin-ui",
+      "version": "0.1.0",
+      "private": true,
+      "scripts": {
+        "build": "ts-node compile.ts"
+      },
+      "devDependencies": {
+        "@vendure/ui-devkit": "^1.4.5",
+        "ts-node": "^10.2.1",
+        "typescript": "~4.3.5"
+      }
+    }
+    ```
+
+```ts title="compile.ts"
+import { compileUiExtensions } from '@vendure/ui-devkit/compiler';
+import { DEFAULT_BASE_HREF } from '@vendure/ui-devkit/compiler/constants';
+import path from 'path';
+import { promises as fs } from 'fs';
+
+/**
+ * Compiles the Admin UI. If the BASE_HREF is defined, use that.
+ * Otherwise, go back to the default admin route.
+ */
+compileUiExtensions({
+    outputPath: path.join(__dirname, 'build'),
+    baseHref: process.env.BASE_HREF ?? DEFAULT_BASE_HREF,
+    extensions: [
+        /* any UI extensions would go here, or leave empty */
+    ],
+})
+    .compile?.()
+    .then(() => {
+        // If building for Vercel deployment, replace the config to make 
+        // api calls to api.example.com instead of localhost.
+        if (process.env.VERCEL) {
+            console.log('Overwriting the vendure-ui-config.json for Vercel deployment.');
+            return fs.writeFile(
+                path.join(__dirname, 'build', 'dist', 'vendure-ui-config.json'),
+                JSON.stringify({
+                    apiHost: 'https://api.example.com',
+                    apiPort: '443',
+                    adminApiPath: 'admin-api',
+                    tokenMethod: 'cookie',
+                    defaultLanguage: 'en',
+                    availableLanguages: ['en', 'de'],
+                    hideVendureBranding: false,
+                    hideVersion: false,
+                }),
+            );
+        }
+    })
+    .then(() => {
+        process.exit(0);
+    });
+```

package/docs/guides/deployment/getting-data-into-production.md

@@ -0,0 +1,50 @@
+---
+title: "Getting data into production"
+showtoc: true
+weight: 4
+---
+
+# Getting data into production
+
+Once you have set up your production deployment, you'll need some way to get your products and other data into the system.
+
+The main tasks will be:
+
+1. Creation of the database schema
+2. Importing initial data like roles, tax rates, countries etc.
+3. Importing catalog data like products, variants, options, facets
+4. Importing other data used by your application
+
+## Creating the database schema
+
+The first item - creation of the schema - can be automatically handled by TypeORM's `synchronize` feature. Switching it on for the initial
+run will automatically create the schema. This can be done by using an environment variable:
+
+```ts title="src/vendure-config.ts"
+import { VendureConfig } from '@vendure/core';
+
+export const config: VendureConfig = {
+    // ...
+    dbConnectionOptions: {
+        type: 'postgres',
+        // highlight-next-line
+        synchronize: process.env.DB_SYNCHRONIZE,
+        host: process.env.DB_HOST,
+        port: process.env.DB_PORT,
+        username: process.env.DB_USER,
+        password: process.env.DB_PASSWORD,
+        database: process.env.DB_DATABASE,
+    },
+    // ...
+};
+```
+
+Set the `DB_SYNCHRONIZE` variable to `true` on first start, and then after the schema is created, set it to `false`.
+
+## Importing initial & catalog data
+
+Importing initial and catalog data can be handled by Vendure `populate()` helper function - see the [Importing Product Data guide](/guides/developer-guide/importing-data/).
+
+## Importing other data
+
+Any kinds of data not covered by the `populate()` function can be imported using a custom script, which can use any Vendure service or service defined by your custom plugins to populate data in any way you like. See the [Stand-alone scripts guide](/guides/developer-guide/stand-alone-scripts/).