Skip to content

Local domain resolution for parallel instances #1094

Description

User story

As a developer running multiple Shopware instances in parallel, I want each instance reachable at a stable, dedicated local hostname (e.g. admin.instance1.shopware.local, admin.instance2.shopware.local) instead of differing ports, so I can work with several instances simultaneously without tracking which port maps to which shop.

Problem to solve

With multiple instances, port-based access (localhost:8000, :8001, …) is hard to keep straight and changes as ports shift to avoid collisions. Stable per-instance subdomains make each shop addressable and memorable, and the storefront/admin URLs stay consistent across restarts. This is the OrbStack domain-resolution approach applied to local Shopware dev.

Related to #939 (running multiple shops in parallel / changing ports), but a different mechanism: #939 resolves conflicts by changing ports; this proposes routing by hostname so port juggling is unnecessary.

Origin: suggestion from the SCD audience.

Acceptance criteria

For review and refinement:

  • Each instance is reachable via a dedicated local hostname (e.g. <service>.<instance>.shopware.local).
  • Hostnames resolve locally without manual /etc/hosts edits per instance.
  • Admin and storefront are addressable per instance (e.g. admin.instance1.shopware.local).
  • APP_URL / sales-channel domains are set consistently with the assigned hostname.
  • The assigned hostname(s) are shown clearly after setup and discoverable later.
  • Works alongside running multiple instances at once (no collision between instances).
  • Documented: how hostnames are assigned and how to customize them.

Readiness checklist

  • Acceptance criteria are clearly defined.
  • Backward compatibility impact addressed.
  • Documentation written.
  • Tests added or adjusted accordingly.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    Fields

    No fields configured for Story.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions