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
Docs: expand/update multi tenant guide
Damian Legawiece4fa2ec6e422
diff --git a/docs/developer/multi-tenant/quickstart.mdx b/docs/developer/multi-tenant/quickstart.mdxindex 40bc38f130..ca35a8d86c 100644--- a/docs/developer/multi-tenant/quickstart.mdx+++ b/docs/developer/multi-tenant/quickstart.mdx@@ -20,7 +20,7 @@ Each tenant (store) can have its own isolated data and configuration, including:* store settings (name, logo, etc.)* etc.-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.+All data is fully isolated besides 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.<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.@@ -38,9 +38,19 @@ All data is fully isolated besided the staff users, which can manage multiple teYou will need to add these environment variables to your CI/CD pipeline and staging/production environments.</Info>-## Installing gems+## Installation-1. Add the following code to your `Gemfile`:+### Eject the Spree backend++If you've created your project with `create-spree-app` you will need to eject the backend to be able to install the Enterprise and Multi-Tenant gems. You can do this by running:++```bash+spree eject+```++### Adding gems++1. Add the following code to your `backend/Gemfile`:```rubysource "https://license:#{ENV['KEYGEN_LICENSE_KEY']}@rubygems.pkg.keygen.sh/#{ENV['KEYGEN_ACCOUNT_ID']}" do@@ -49,7 +59,61 @@ All data is fully isolated besided the staff users, which can manage multiple teend```-2. Install gems:+2. Configure the Docker image build to authenticate against the Keygen source.++ If you use the Spree CLI (Docker), `spree bundle install` resolves the licensed+ gems **inside the image at build time**, so the Keygen credentials must be available+ during `bundle install` in the `Dockerfile` — not just at runtime. Pass them as+ [BuildKit secrets](https://docs.docker.com/build/building/secrets/) so they are mounted+ as environment variables for the `bundle install` step only, and never baked into the+ image layers or history (unlike `ARG`/`ENV`/`COPY`).++ <Info>+ Skip this step if you install without the Spree CLI (plain `bundle install` on the host).+ In that case the Gemfile reads `KEYGEN_LICENSE_KEY` / `KEYGEN_ACCOUNT_ID` directly from+ your shell environment.+ </Info>++ Wrap **every** `bundle install` in your `backend/Dockerfile` with the secret mounts. There+ are usually two — one in the build stage and one in the dev stage:++ ```dockerfile backend/Dockerfile+ COPY .ruby-version Gemfile Gemfile.lock ./+ RUN bundle install # [!code --]+ RUN --mount=type=secret,id=keygen_license_key,env=KEYGEN_LICENSE_KEY,required=false \ # [!code ++]+ --mount=type=secret,id=keygen_account_id,env=KEYGEN_ACCOUNT_ID,required=false \ # [!code ++]+ bundle install # [!code ++]+ ```++ Then wire the secrets into **both** compose files (`docker-compose.yml` and+ `docker-compose.dev.yml` — the latter is what `spree eject` copies over) so the CLI+ supplies them to the build:++ ```yaml docker-compose.yml+ x-app: &app+ build:+ context: ./backend+ dockerfile: Dockerfile+ target: dev+ secrets: # [!code ++]+ - keygen_license_key # [!code ++]+ - keygen_account_id # [!code ++]++ # ...at the bottom of the file, declare where the secrets come from:+ secrets: # [!code ++]+ keygen_license_key: # [!code ++]+ environment: KEYGEN_LICENSE_KEY # [!code ++]+ keygen_account_id: # [!code ++]+ environment: KEYGEN_ACCOUNT_ID # [!code ++]+ ```++ <Info>+ Compose reads `environment:`-sourced secrets from the **shell environment** that runs+ the build, not from `.env`. Make sure `KEYGEN_LICENSE_KEY` and `KEYGEN_ACCOUNT_ID` are+ exported in the shell (and in your CI/CD and production build environments).+ </Info>++3. Install gems:<CodeGroup>@@ -63,7 +127,7 @@ All data is fully isolated besided the staff users, which can manage multiple te</CodeGroup>-3. Run generators:+4. Run generators:<CodeGroup>@@ -79,10 +143,14 @@ All data is fully isolated besided the staff users, which can manage multiple te<Info>This will copy and run migrations for `spree_enterprise` and `spree_multi_tenant` gems.+ The `spree_multi_tenant:install` generator also edits `config/routes.rb` (to add the+ tenant domain routing constraints), your customer user model, and your admin user model+ — see [Post-install configuration](#post-install-configuration) below.</Info>+## Post-install configuration-## Setting root domain+### Setting root domainUsually 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.@@ -94,23 +162,93 @@ Spree.root_domain = 'example.com'or use environment variable:```ruby-Spree.root_domain = ENV.fetch('SPREE_ROOT_DOMAIN', 'localhost')+Spree.root_domain = ENV.fetch('SPREE_ROOT_DOMAIN', 'lvh.me')+```++You need to use `lvh.me` for local development, so cross-subdomain cookies will work, `localhost` will **not** work.++<Warning>+ `localhost` cannot be used as a cookie domain by browsers, so the session cookie set on+ `store1.localhost` is rejected and never sent back — you get logged out when moving between+ subdomains, and admin sign-in fails with `ActionController::InvalidAuthenticityToken`+ ("Can't verify CSRF token authenticity"). Use `lvh.me` (or `localtest.me`); both resolve to+ `127.0.0.1` and are valid cookie domains.+</Warning>++#### Sharing the session cookie across subdomains++For staff to stay signed in while moving between the app domain (`app.example.com`) and tenant+subdomains (`store1.example.com`), the session cookie must be scoped to the parent domain. Set+`COOKIE_TLD_LENGTH` to the number of labels in your root domain:++| Root domain | `COOKIE_TLD_LENGTH` | Cookie domain |+| ----------- | ------------------- | ------------- |+| `lvh.me` | `2` | `.lvh.me` |+| `example.com` | `2` | `.example.com` |+| `shop.example.co.uk` | `3` | `.example.co.uk` |++```bash .env+SPREE_ROOT_DOMAIN=lvh.me+COOKIE_TLD_LENGTH=2```-This way you can also test it locally using `localhost` as root domain, and use `tenant1.localhost`, `tenant2.localhost`, etc. for tenants.+#### Allowing tenant subdomains through host authorization++Rails' host authorization blocks unknown hosts. `.localhost` and `.test` are permitted in+development by default, but `.lvh.me` (and your production domain) are not — requests to+`app.lvh.me` are rejected with a "Blocked hosts" error until you allow them. Add your root+domain to `config/environments/development.rb`:++```ruby backend/config/environments/development.rb+if (root_domain = ENV['SPREE_ROOT_DOMAIN']).present?+ config.hosts << ".#{root_domain}"+end+```-## Customer User Class adjustment+### Customer User Class adjustmentWe 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.+The `spree_multi_tenant:install` generator adds `include SpreeMultiTenant::CustomerUserConcern`+to your customer user model automatically. You then need to **remove the `:validatable` module**+manually. `:validatable` validates the user's email uniqueness globally; the concern re-validates+it in the scope of the tenant instead, so the same email can exist across different tenants.```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+class Spree::User < Spree.base_class+ include Spree::UserAddress+ include Spree::UserMethods+ include Spree::UserPaymentSource+ include SpreeMultiTenant::CustomerUserConcern # added by the generator++ devise :database_authenticatable, :registerable, :recoverable, :rememberable, :validatable # [!code --]+ devise :database_authenticatable, :registerable, :recoverable, :rememberable # [!code ++]+end+```++<Warning>+ Only remove `:validatable`. Do not add other Devise modules (such as `:confirmable`) here+ unless your app is already set up for them — `:confirmable`, for example, requires additional+ columns and a confirmation flow, and adding it will break sign-in.+</Warning>++### Admin User Class adjustment++The generator also changes your admin user model's base class from `Spree.base_class` to+`Spree::Base`. If your `admin_user.rb` exists, this is applied automatically; otherwise make the+change yourself:- include SpreeMultiTenant::CustomerUserConcern # [!code ++]+```ruby backend/app/models/spree/admin_user.rb+class Spree::AdminUser < Spree.base_class # [!code --]+class Spree::AdminUser < Spree::Base # [!code ++]+ include Spree::AdminUserMethods++ devise :database_authenticatable, :registerable,+ :recoverable, :rememberable, :validatableend```++<Info>+ Unlike the customer user model, the admin user model keeps `:validatable` — staff accounts are+ global and can manage multiple tenants, so their emails remain globally unique.+</Info>