# Multi-store

Source: https://www.storeframe.io/docs/infrastructure/multi-store

Run multiple Magento stores from a single environment by adding each store's domain in the Hub, with its own TLS certificate and store code.

A single StoreFrame environment can serve any number of Magento stores. The platform supports the full Magento store hierarchy (website → store → store view) on one VM, and routes incoming requests to the correct store based on the `Host` header. Each domain gets its own TLS certificate and its own `MAGE_RUN_CODE` / `MAGE_RUN_TYPE` values.

You set this up yourself in the Hub, under the environment's **Settings → Custom domains**. See [Custom domains](/docs/hub/environments/settings/custom-domains).

## How a domain becomes a store

Each domain you add in Custom domains has:

| Field                | Purpose                                                                                                               |
| -------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Subdomain and domain | The host, for example `www` + `example.nl`                                                                            |
| Store Code           | The Magento store view code this domain should show, for example `nl_nl`. It is passed to Magento as `MAGE_RUN_CODE`. |
| Store Type           | Passed to Magento as `MAGE_RUN_TYPE`. Leave it on **Store** to map the domain to a store view.                        |

`MAGE_RUN_TYPE` and `MAGE_RUN_CODE` are Magento's built-in mechanism for routing a request to a specific store scope. The `nginx` container reads the `Host` header, looks up the matching site config, and sets these two values on the request to PHP. Magento uses them to select which store view to render.

## What gets generated per host

When the platform configures nginx, it generates one site file per host. The file declares which hostnames map to this site, the canonical host, the `MAGE_RUN_CODE` / `MAGE_RUN_TYPE` values, and the SSL certificate paths. The certificate paths reference per-host directories under `/etc/letsencrypt/live/`, so each host has an independent certificate (no SAN-shared cert across stores).

## The default domain

The environment's default StoreFrame domain keeps serving the default store view. When you add a `www` domain, the bare domain is mapped too, so `example.nl` and `www.example.nl` show the same store, each with its own certificate.

## SSL certificates

Each host gets its own certificate directory:

```
/etc/letsencrypt/live/www.example.nl/
/etc/letsencrypt/live/example.nl/        # apex (when applicable)
/etc/letsencrypt/live/www.example.de/
```

The OpenResty configuration loads certs per-SNI from these paths. There is no shared SAN certificate — adding a new store does not invalidate existing certs or require a coordinated renewal.

The nginx container requests the certificate itself on the first deploy of the host. If a certificate fails to issue (for example, DNS hasn't propagated yet), the placeholder directory is created but the cert is missing, and the host will not serve TLS until cert issuance succeeds.

## Adding a store: end-to-end

1. In Magento admin, create the website / store / store view for the new storefront, for example a store view with the code `de_de`. Magento needs a store with that code, or requests fall back to the default store.
2. Point DNS for the new host (`www.example.de`) to the environment's IP address.
3. In the Hub, open **Settings → Custom domains**, choose **Manage Domains** and add `www` + `example.de` with Store Code `de_de` and Store Type **Store**. Save.
4. The platform configures nginx for the new domain and requests its TLS certificate. You can follow the job under **Settings → Active jobs**.

## Routing decision

The nginx layer reads the `Host` header and sets Magento's `MAGE_RUN_CODE` and `MAGE_RUN_TYPE` for that store. Requests for a hostname that isn't configured still go through the security checks and are answered by the default store or a 404.

## Example

An environment running Dutch, German and English store views on a single Magento instance, with customer-facing domains `www.example.nl` and `www.example.de`, has three hosts in its nginx config, three site files and three sets of TLS certificates. All of them are served from one Magento codebase, one database and one product catalog. Stock, orders, and customers are shared; pricing, language, payment methods, and CMS content are scoped per store view.

## Limits

* Custom domains are not available on trial environments.
* All stores on one environment share the same Magento database, Redis cache, and OpenSearch index. They scale together. A traffic spike on the German store affects the Dutch store's performance because they share the same PHP workers.
* The Hyvä theme assignment defaults to all stores. Per-store theme overrides are possible but require manual `core_config_data` updates after provisioning. See [Hyvä](/docs/infrastructure/stack/hyva).

## Related

* [Environment file (.env)](/docs/infrastructure/architecture/env-file) — environment configuration file
* [OpenResty + Lua security pipeline](/docs/infrastructure/stack/openresty-lua) — the router that dispatches per-host requests
* [Hyvä](/docs/infrastructure/stack/hyva) — theme assignment across stores
