Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Improve multi tenant documentation (#14212)
Damian Legawiecbc4adafba09a
diff --git a/docs/developer/admin/extending-ui.mdx b/docs/developer/admin/extending-ui.mdxindex b1f47ec32c..7cbd0f8a44 100644--- a/docs/developer/admin/extending-ui.mdx+++ b/docs/developer/admin/extending-ui.mdx@@ -553,32 +553,6 @@ Here's a list of all places you can inject your custom code:</Accordion></AccordionGroup>-### Custom Domains--<AccordionGroup>- <Accordion title="Custom Domains Actions">- `custom_domains_actions`-- Injects code into the page actions area for the custom domains list page.-- ```erb- <%= link_to "Verify All Domains", verify_all_domains_path, class: "btn btn-secondary" %>- ```- </Accordion>-- <Accordion title="Custom Domains Header">- `custom_domains_header`-- Injects code between the page header and the main content area for the custom domains list page.-- ```erb- <div class="alert alert-info">- <strong>SSL:</strong> SSL certificates are automatically managed.- </div>- ```- </Accordion>-</AccordionGroup>-### Customer Returns<AccordionGroup>diff --git a/docs/developer/core-concepts/stores.mdx b/docs/developer/core-concepts/stores.mdxindex fa01769562..d7d826e34f 100644--- a/docs/developer/core-concepts/stores.mdx+++ b/docs/developer/core-concepts/stores.mdx@@ -5,9 +5,7 @@ description: Understand Spree Stores — the top-level tenant boundary that scop## Overview-The Store is the top-level tenant in Spree. Every resource — products, orders, channels, markets, taxonomies — belongs to exactly one store. A store owns its branding (logo, custom domain, mail-from address), its [channels](/developer/core-concepts/channels) (online, POS, wholesale, …), its [markets](/developer/core-concepts/markets) (region/currency/locale), and its catalog.--## Store Attributes+The StThe Store is the top-level tenant in Spree. Every resource — products, orders, channels, markets, taxonomies — belongs to exactly one store. A store owns its [channels](/developer/core-concepts/channels) (online, POS, wholesale, …), its [markets](/developer/core-concepts/markets) (region/currency/locale), and its [product catalog](/developer/core-concepts/products).tore Attributes| Attribute | Description ||-----------|-------------|diff --git a/docs/developer/multi-tenant/configuration.mdx b/docs/developer/multi-tenant/configuration.mdxindex 644e3c3a70..ea40f5b6ae 100644--- a/docs/developer/multi-tenant/configuration.mdx+++ b/docs/developer/multi-tenant/configuration.mdx@@ -5,16 +5,6 @@ sidebarTitle: ConfigurationMulti-tenant applications include additional configuration options. All configuration should be placed in `config/initializers/spree_multi_tenant.rb` file.-### Root domain--To make multi-tenant, you need a root/wildcard domain, eg. `*.example.com`. Tenant stores are usually accessed via subdomains, eg. `store1.example.com`, `store2.example.com`, etc.--```bash-Spree.root_domain = 'example.com'-```--Still your tenants will be able to add custom domains, eg. `myflowerstore.com` via the Spree admin panel. Tenant subdomains are used only for admin panel access.-### App subdomainApplication subdomains is used to access the application, eg. `app.example.com`. By default for existing tenants it will redirect them to their tenant subdomain, eg. `store1.example.com`. If you want, you can also use this as a tenant signup/store setup page, this is available under `app.example.com/tenants/new`.@@ -40,4 +30,4 @@ SpreeMultiTenant::Config[:mail_from_address] = ENV.fetch('MAIL_FROM_ADDRESS', "s`mail_from_name` is only used in admin emails, such as admin staff invitations, exports, etc. For consumer facing emails, this will be your tenant store name, eg. `My Flower Store` (or whatever they set in the store settings).Also, customer facing emails will use the tenant email address in `Reply-To` header.-</Info>\ No newline at end of file+</Info>diff --git a/docs/developer/multi-tenant/quickstart.mdx b/docs/developer/multi-tenant/quickstart.mdxindex 521fa754a3..2f92a58ddb 100644--- a/docs/developer/multi-tenant/quickstart.mdx+++ b/docs/developer/multi-tenant/quickstart.mdx@@ -1,88 +1,42 @@----title: Spree Multi Tenant Installation-sidebarTitle: Installation-description: Install and configure Spree Multi-Tenant to run a SaaS ecommerce platform, including prerequisites, gem setup, license keys, and tenant provisioning.+title: Create a multi-tenant / SaaS platform on top of Spree+sidebarTitle: Quickstart+description: Configure Spree to run a SaaS ecommerce platform, including prerequisites, gem setup, license keys, and tenant provisioning.----<Warning>- This installation instructions assume you have a clean Spree Starter installation and you've purchased the [Spree Enterprise Edition license](https://spreecommerce.org/pricing).-- For migrating existing application from single-tenant to multi-tenant, please contact us at [[email protected]](mailto:[email protected]).-</Warning>--## Prerequisites--* You need to be on Spree 5.1+, we recommend using [spree_starter](https://github.com/spree/spree_starter) as a base for your application-* You need to have 2 environment variables set:- * `KEYGEN_ACCOUNT_ID`- * `KEYGEN_LICENSE_KEY`-* We support both PostgreSQL and MySQL databases-<Info>- Environment variables will be provided to you after purchasing the [Spree Enterprise Edition license](https://spreecommerce.org/pricing).+ Multi-tenancy requires [Spree Enterprise Edition license](https://spreecommerce.org/pricing).</Info>-<Warning>- You will need to add these environment variables to your CI/CD pipeline and production environments.-</Warning>--## Customer User Class+Spree can be configured to run a multi-tenant / SaaS platform. This guide will walk you through the steps to set up your Spree application to support multiple tenants (stores).+Each tenant (store) can have its own isolated data and configuration, including:-Please follow [Authentication](/developer/customization/authentication) documentation to create a new user class.+* customer accounts+* staff accounts (admin users), staff can manage multiple tenants (it's the standard invitation flow)+* products, categories, and other catalog data+* orders and order history+* shipping and payment methods+* tax rates and zones+* store settings (name, logo, etc.)+* etc.-Now we will need to make slight adjustments to the generated user class so it can work in a multi-tenant environment.+All data is fully isolated besided the staff users, which can manage multiple tenants. This allows you to create a SaaS platform where each tenant can have its own store with its own branding and configuration. Isolation works across admin dashboard and API.-If you're using Devise, you will need to remove `:validatable` module. This module is responsible for validating the user's email uniqueness. We need to change it to validate it in the scope of the tenant.--Spree Multi-Tenant gem injects `SpreeMultiTenant::CustomerUserConcern` that handles that instead.--## Admin User Class--For our multi-tenant setup we will need a separate Admin user class. Our standard User class will be only used for customer accounts which will be isolated by tenant.-Admin user classes will be shared across tenants allowing them to manage multiple tenants from a single admin panel.--Let's create a new model with Devise (unless you already have one):--<CodeGroup>--```bash Spree CLI (Docker)-spree rails g devise Spree::AdminUser-```--```bash Without Spree CLI-bin/rails g devise Spree::AdminUser-```--</CodeGroup>--Replace the generated Devise code with the following:--```ruby-class Spree::AdminUser < Spree::Base- # Include default devise modules. Others available are:- # :confirmable, :lockable, :timeoutable, :trackable and :omniauthable- devise :database_authenticatable, :registerable,- :recoverable, :rememberable, :validatable-- # Spree modules- include Spree::UserMethods-end-```--If you already have a custom Admin user class, you can add the following code to it:--```ruby- # Spree modules- include Spree::UserMethods-```+<Info>+ If you need individual seller/supplier/vendor accounts but shared product listings under one site you should use [multi vendor recipe](/developer/multi-vendor) instead.+</Info>-This will make sure that the Admin user class works well with Spree ecosystem.+## Prerequisites-Register new model in `config/initializers/spree.rb`:+* You need to be on Spree 5.1+, we recommend using [CLI](/developer/getting-started) to setup your Spree application.+* You need to set 2 environment variables in your `backend` directory:+ * `KEYGEN_ACCOUNT_ID`+ * `KEYGEN_LICENSE_KEY`+* Both PostgreSQL and MySQL are supported-```ruby-Spree.admin_user_class = "Spree::AdminUser"-```+<Info>+ You will need to add these environment variables to your CI/CD pipeline and staging/production environments.+</Info>## Installing gems@@ -126,3 +80,37 @@ Spree.admin_user_class = "Spree::AdminUser"<Info>This will copy and run migrations for `spree_enterprise` and `spree_multi_tenant` gems.</Info>+++## Setting root domain++Usually multi-tenant applications are configured to use subdomains for each tenant. For example, if your root domain is `example.com`, you can have tenants like `tenant1.example.com`, `tenant2.example.com`, etc.+To make it work you need to set the `Spree.root_domain` in your `config/initializers/spree.rb` file, eg.++```ruby+Spree.root_domain = 'example.com'+```++or use environment variable:++```ruby+Spree.root_domain = ENV.fetch('SPREE_ROOT_DOMAIN', 'localhost')+```++This way you can also test it locally using `localhost` as root domain, and use `tenant1.localhost`, `tenant2.localhost`, etc. for tenants.++## Customer User Class adjustment++We need to make slight adjustments to the user class so it can work in a multi-tenant environment.++You need to remove `:validatable` module. This module is responsible for validating the user's email uniqueness. We need to change it to validate it in the scope of the tenant.++```ruby backend/app/models/spree/user.rb+class User < ApplicationRecord+ devise :database_authenticatable, :registerable, :validatable # [!code --]+ devise :database_authenticatable, :registerable, # [!code ++]+ :recoverable, :rememberable, :trackable, :confirmable++ include SpreeMultiTenant::CustomerUserConcern # [!code ++]+end+```diff --git a/docs/user/settings/metafields.mdx b/docs/user/settings/metafields.mdxindex 3a0616d567..ca66620bfd 100644--- a/docs/user/settings/metafields.mdx+++ b/docs/user/settings/metafields.mdx@@ -40,7 +40,6 @@ You can define metafields for nearly any data object in Spree:- **Address** - e.g., delivery instructions- **Asset** - e.g., alt text or copyright- **Credit Card** - e.g., vault token-- **Custom Domain** - e.g., domain verification token- **Customer Return** - e.g., return reason detail- **Gift Card** - e.g., personal message- **Image** - e.g., display priority or alt tag