Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Improve multi tenant documentation (#14212)

Damian Legawiecbc4adafba09a
diff --git a/docs/developer/admin/extending-ui.mdx b/docs/developer/admin/extending-ui.mdx
index 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.mdx
index 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.mdx
index 644e3c3a70..ea40f5b6ae 100644
--- a/docs/developer/multi-tenant/configuration.mdx
+++ b/docs/developer/multi-tenant/configuration.mdx
@@ -5,16 +5,6 @@ sidebarTitle: Configuration
Multi-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 subdomain
Application 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.mdx
index 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.mdx
index 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