✨ Why LocalSSL?

LocalSSL gives your machine one shared HTTPS gateway instead of every local project trying to own Caddy, certificates, and ports.

It reads public local domains from sumr.yaml, generates a Caddy config, and lets Caddy issue local certificates from one trusted local CA.

https://app.localhost          -> http://host.docker.internal:3000
https://api.app.localhost      -> http://host.docker.internal:4000
https://*.tenant.localhost     -> http://host.docker.internal:5000

🚀 Install

npm install -g @sumrco/local-ssl

Requirements:

• Node.js 20+
• Docker running locally
• Ports 80 and 443 available, unless you configure custom ports

⚡ Quick start

localssl init
localssl subscribe
localssl up
localssl status

🧭 How routing works

Domains come from host, not from upstream.

gateway:
  routes:
    - host: admin.app.localhost
      upstream: http://host.docker.internal:7300

That means:

Browser:  https://admin.app.localhost
Proxy:    http://host.docker.internal:7300

🧩 Many projects, one gateway

Run localssl subscribe from each project that has a sumr.yaml:

cd ~/work/project-a && localssl subscribe
cd ~/work/project-b && localssl subscribe
cd ~/work/project-c && localssl subscribe

LocalSSL keeps one shared manifest under ~/.sumr/localssl and generates one Caddyfile for all subscribed routes.

🔐 Runtime identity

The gateway identity is intentionally fixed so other projects can detect it and skip their own gateway containers:

• Container: localssl-gateway
• Label: dev.localssl.role=gateway
• Label: dev.localssl.instance=default

Users configure routes and ports, not the container name.

By default, shared state lives under ~/.sumr/localssl. Set SUMR_LOCALSSL_HOME only when you need an isolated test/dev home.

Run LocalSSL as your normal user, not with sudo. The trust command may ask macOS for admin approval only when adding the Caddy CA to the system keychain.

📝 Config

LocalSSL prefers a top-level gateway.routes section from sumr.yaml:

version: 1

gateway:
  ports:
    http: 80
    https: 443
  routes:
    - host: app.localhost
      upstream: http://host.docker.internal:3000

    - host: api.app.localhost
      upstream: http://host.docker.internal:4000

    - host: "*.tenant.localhost"
      upstream: http://host.docker.internal:5000

Only localhost and *.localhost names are accepted.

If a project already has a team.gateway.hosts list, LocalSSL can reuse it without duplicating routes:

team:
  gateway:
    httpsPort: 443
    hosts:
      - host: app.localhost
        port: 3000
      - host: api.app.localhost
        port: 4000

Those entries become http://host.docker.internal:<port> upstreams. Explicit gateway.routes still wins when both sections exist, because it can express upstream URLs and rewrites directly.

🛠️ Commands

| Command | Purpose | | --- | --- | | localssl init | Create a starter sumr.yaml. | | localssl subscribe | Merge this repo's LocalSSL routes into the shared manifest. | | localssl up | Subscribe current repo routes, write Caddyfile, and start/reload gateway. | | localssl reload | Regenerate Caddyfile and reload running Caddy. | | localssl down | Stop the fixed LocalSSL container. | | localssl status | Show container, trust, storage, and subscribed projects. | | localssl trust | Trust the Caddy local CA on macOS. | | localssl check | Validate current project config and generated Caddyfile. | | localssl routes | Print registered routes. |

🧪 Example

gateway:
  routes:
    - host: app.localhost
      upstream: http://host.docker.internal:3000
    - host: api.app.localhost
      upstream: http://host.docker.internal:4000
    - host: "*.tenant.localhost"
      upstream: http://host.docker.internal:5000