From 670c4717b402fba7a4b864a3a24d5768a85d67bd Mon Sep 17 00:00:00 2001 From: Tomasz Turkowski Date: Fri, 14 Aug 2026 10:16:48 +0200 Subject: [PATCH] docs(cli): add Local Proxy page for running multiple shops in parallel Co-Authored-By: Claude Opus 4.8 --- .wordlist.txt | 3 + .../cli/project-commands/dev-environment.md | 1 + .../tools/cli/project-commands/local-proxy.md | 134 ++++++++++++++++++ 3 files changed, 138 insertions(+) create mode 100644 products/tools/cli/project-commands/local-proxy.md diff --git a/.wordlist.txt b/.wordlist.txt index f1391ad9e..f4b4b38ec 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -243,6 +243,7 @@ ContextTokenAware ContextTokenStorer CookiePermission CookieProviderInterface +CoreDNS CountryStateDataPagelet CreateFromTrait CreateTagAction @@ -1053,6 +1054,7 @@ ToOne Tooltips Topseller Topsellers +Traefik TransactionalAction TranslatedField TranslationConfig @@ -1148,6 +1150,7 @@ WCAG WMA WMV WSL +WSL2 WarehouseGroup WarehouseGroups WebAIM diff --git a/products/tools/cli/project-commands/dev-environment.md b/products/tools/cli/project-commands/dev-environment.md index 71c375aba..36fc15073 100644 --- a/products/tools/cli/project-commands/dev-environment.md +++ b/products/tools/cli/project-commands/dev-environment.md @@ -76,5 +76,6 @@ environments: ## Further reading +- [Local Proxy](./local-proxy.md) — run several shops at once, each on its own stable HTTPS hostname - [Development Environment guide](../../../../guides/development/dev-environment.md) — full workflow, setup wizard, service overview, troubleshooting - [Start Developing](../../../../guides/development/start-developing.md) — next steps after your environment is running diff --git a/products/tools/cli/project-commands/local-proxy.md b/products/tools/cli/project-commands/local-proxy.md new file mode 100644 index 000000000..18fe2269a --- /dev/null +++ b/products/tools/cli/project-commands/local-proxy.md @@ -0,0 +1,134 @@ +--- +nav: + title: Local Proxy + position: 2 + +--- + +# Local Proxy — Run Multiple Shops in Parallel (CLI Reference) + +A single `shopware-cli project dev` environment publishes fixed host ports (`8000`, `9080`, …), so only one shop can run at a time — a second one collides on those ports. + +The **local proxy** removes the conflict: every shop is served at its own stable HTTPS hostname (for example `https://my-shop.shopware.local`) through one shared reverse proxy, so any number of shops run side by side with no port juggling. + +For the underlying single-shop workflow, see [Development Environment](./dev-environment.md). + +## How it works + +A shop running under the proxy publishes **no host ports**. Instead: + +- a small **CoreDNS** container answers every `*.shopware.local` name with `127.0.0.1` — the lookup never leaves your machine; +- one shared **Traefik** container reads the requested hostname and routes the request to the matching shop; +- a local **certificate authority** signs the HTTPS certificates, trusted once per machine. + +```mermaid +sequenceDiagram + participant B as Browser + participant R as OS resolver + participant D as CoreDNS container + participant T as Traefik (shared, :443) + participant S as my-shop container + + B->>R: where is my-shop.shopware.local? + R->>D: routed locally + D-->>B: 127.0.0.1 + B->>T: https://my-shop.shopware.local + T->>S: routed by hostname + S-->>B: response +``` + +Nothing leaves your machine: the DNS resolver only ever answers `127.0.0.1`, and shops reach each other by the same trusted hostnames. + +## One-time setup + +Run once per machine. It points the operating system's resolver at the local DNS and installs the certificate authority into your trust stores — the single `sudo` moment: + +```bash +shopware-cli project proxy setup +``` + +To use a different base domain (persisted machine-wide), pass `--domain`: + +```bash +shopware-cli project proxy setup --domain shopware.test +``` + +## Run a shop through the proxy + +### New project + +The simplest path is interactive — create the project and answer the prompts: + +```bash +shopware-cli project create my-shop +``` + +`project create` asks whether to use **local domains** and offers to run the one-time machine setup for you (the `sudo` step). Answer yes, then start the shop — it comes up at `https://my-shop.shopware.local` with no further steps: + +```bash +cd my-shop +shopware-cli project dev +``` + +For scripting or CI, skip the prompts with flags (the machine setup must have been run once beforehand): + +```bash +shopware-cli project create --local-domain --no-interaction my-shop +``` + +### Existing project + +Opt an existing port-based project in, and revert it when you are done: + +```bash +# Start the shop under the proxy +shopware-cli project proxy up + +# Stop it and restore its previous URL and ports +shopware-cli project proxy down +``` + +`proxy up` records the previous `APP_URL`, sales-channel domain, and configuration, and `proxy down` restores them exactly. + +## Command reference + +| Command | Description | +| --- | --- | +| `project proxy setup` | One-time machine setup: DNS routing and HTTPS trust. Flags: `--domain`, `--skip-trust` | +| `project proxy up` | Register the current project with the shared proxy and start it | +| `project proxy down` | Remove the current project from the proxy, stop it, and restore its URLs | +| `project proxy status` | Report whether the current project is registered | +| `project proxy list` | List every registered project with its URLs and running state | +| `project proxy verify` | Health-check the whole chain (Docker, DNS, resolver, Traefik, HTTPS) | +| `project proxy teardown` | Remove every project and stop the shared proxy and DNS. Flag: `--force` | + +### Example: see what is running + +```bash +shopware-cli project proxy list +``` + +```text +my-shop.shopware.local running ~/projects/my-shop + Shop https://my-shop.shopware.local + Admin https://my-shop.shopware.local/admin +other-shop.shopware.local stopped ~/projects/other-shop +``` + +## Troubleshooting + +If a shop is not reachable, run the bottom-up health check. It stops at the first broken layer and prints how to fix it: + +```bash +shopware-cli project proxy verify +``` + +## Requirements + +- **Docker** — the shared proxy runs as Docker containers. +- **macOS or Linux.** On Windows, run shopware-cli inside **WSL2**. + +## Related + +- [Development Environment](./dev-environment.md) — the single-shop `project dev` reference +- [Development Environment guide](../../../../guides/development/dev-environment.md) — full workflow, setup, and configuration