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.

Docs: expand/update multi tenant guide

Damian Legawiece4fa2ec6e422
diff --git a/docs/developer/multi-tenant/quickstart.mdx b/docs/developer/multi-tenant/quickstart.mdx
index 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 te
You 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`:
```ruby
source "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 te
end
```
-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 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.
@@ -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 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.
+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, :validatable
end
```
+
+<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>