@codions/portta 0.0.0-develop.147.sha-1859ad1

package/dist/runtime/templates/README.md

@@ -0,0 +1,43 @@
+# Templates
+
+Reference overlays for the shapes a project usually has. They are **references
+to copy from**, not runtime that projects depend on: nothing here is included,
+mounted or extended by a consumer project. Copy the closest one, adjust the
+service names and ports, and it is yours.
+
+`portta env init <path>` generates the same thing from a project's actual
+Compose file, which is usually faster.
+
+| Template | Shape |
+|---|---|
+| [`01-single-web.yaml`](overlays/01-single-web.yaml) | one HTTP service |
+| [`02-web-api.yaml`](overlays/02-web-api.yaml) | web + API |
+| [`03-web-api-postgres.yaml`](overlays/03-web-api-postgres.yaml) | web + API + a database that stays private |
+| [`04-web-api-postgres-redis.yaml`](overlays/04-web-api-postgres-redis.yaml) | the common full stack |
+| [`05-multiple-apis.yaml`](overlays/05-multiple-apis.yaml) | several APIs behind one namespace |
+| [`06-monorepo.yaml`](overlays/06-monorepo.yaml) | `apps/` and `services/` in one repository |
+| [`07-worktree.env`](overlays/07-worktree.env) | a second copy of a project, in parallel |
+| [`08-nonstandard-port.yaml`](overlays/08-nonstandard-port.yaml) | an HTTP service on an unusual internal port |
+| [`09-tcp-routing.yaml`](overlays/09-tcp-routing.yaml) | opt a datastore into hostname TCP routing |
+| [`10-mailpit.yaml`](overlays/10-mailpit.yaml) | Mailpit UI on the gateway (SMTP stays private) |
+| [`11-rustfs.yaml`](overlays/11-rustfs.yaml) | RustFS console on the gateway (S3 API stays private) |
+
+## The two rules every template follows
+
+**Labels are in list form.** Compose interpolates `${VAR}` inside a list entry
+but **not** inside a mapping key. Written as a map, the Traefik service name
+keeps the literal `${COMPOSE_PROJECT_NAME}` and every worktree of the project
+collapses onto one load balancer.
+
+**Traefik service names carry the namespace.** Those names are flat across the
+whole host. Two projects declaring a bare `web` are merged into a single load
+balancer and start serving each other's traffic.
+
+`portta doctor` reports both.
+
+## For the consumer repository
+
+[`project/PORTTA.md`](project/PORTTA.md) is a short page to copy into
+the project itself: how to start it, its URLs, how to reach its database, how
+to run a second copy. It deliberately does not restate the gateway's
+documentation; this repository stays the single source of the rules.

package/dist/runtime/templates/overlays/01-single-web.yaml

@@ -0,0 +1,23 @@
+# ============================================================================
+# One HTTP service
+# ============================================================================
+#   docker compose -f compose.yaml -f compose.portta.yaml up -d
+#   -> http://<COMPOSE_PROJECT_NAME>-web.localhost
+# ============================================================================
+
+services:
+  web:
+    networks:
+      - default
+      - portta
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      # Only needed when the image's EXPOSE does not match the port the app
+      # actually listens on. It usually does not, so state it.
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-web.loadbalancer.server.port=3000"
+
+networks:
+  portta:
+    external: true
+    name: ${PORTTA_NETWORK:-portta}

package/dist/runtime/templates/overlays/02-web-api.yaml

@@ -0,0 +1,30 @@
+# ============================================================================
+# Web + API
+# ============================================================================
+# Both keep their internal ports. Other projects on this host use the same
+# 3000 and 8000 at the same time, and nothing collides, because neither
+# publishes a host port.
+#
+#   -> http://<COMPOSE_PROJECT_NAME>-web.localhost
+#   -> http://<COMPOSE_PROJECT_NAME>-api.localhost
+# ============================================================================
+
+services:
+  web:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-web.loadbalancer.server.port=3000"
+
+  api:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-api.loadbalancer.server.port=8000"
+
+networks:
+  portta:
+    external: true
+    name: ${PORTTA_NETWORK:-portta}

package/dist/runtime/templates/overlays/03-web-api-postgres.yaml

@@ -0,0 +1,33 @@
+# ============================================================================
+# Web + API + PostgreSQL
+# ============================================================================
+# Note what is NOT here: postgres. A database has no business on the shared
+# network, since everything else on the host could reach it, and it does not
+# need a host port either.
+#
+# The API reaches it as `postgres:5432` over the project's own network, exactly
+# as before. A human reaches it on demand:
+#
+#   portta access open --project <name> --service postgres
+#   -> 127.0.0.1:<free port>
+# ============================================================================
+
+services:
+  web:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-web.loadbalancer.server.port=3000"
+
+  api:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-api.loadbalancer.server.port=8000"
+
+networks:
+  portta:
+    external: true
+    name: ${PORTTA_NETWORK:-portta}

package/dist/runtime/templates/overlays/04-web-api-postgres-redis.yaml

@@ -0,0 +1,30 @@
+# ============================================================================
+# Web + API + PostgreSQL + Redis: the common full stack
+# ============================================================================
+# Identical to template 03: adding a cache changes nothing about the contract.
+# Postgres and Redis both stay on the project's private network, both keep
+# their standard ports, and both are reached with `portta access open`.
+#
+# Workers are absent too. A queue consumer serves no HTTP, so it has nothing to
+# route; it stays on `default` and needs no changes at all.
+# ============================================================================
+
+services:
+  web:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-web.loadbalancer.server.port=3000"
+
+  api:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-api.loadbalancer.server.port=8000"
+
+networks:
+  portta:
+    external: true
+    name: ${PORTTA_NETWORK:-portta}

package/dist/runtime/templates/overlays/05-multiple-apis.yaml

@@ -0,0 +1,37 @@
+# ============================================================================
+# Several APIs in one project
+# ============================================================================
+# Each gets its own hostname from its own service name. They can all listen on
+# 8000 internally; nothing needs renumbering.
+#
+#   -> http://<COMPOSE_PROJECT_NAME>-api-auth.localhost
+#   -> http://<COMPOSE_PROJECT_NAME>-api-billing.localhost
+#   -> http://<COMPOSE_PROJECT_NAME>-api-search.localhost
+# ============================================================================
+
+services:
+  api-auth:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-api-auth.loadbalancer.server.port=8000"
+
+  api-billing:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-api-billing.loadbalancer.server.port=8000"
+
+  api-search:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-api-search.loadbalancer.server.port=8000"
+
+networks:
+  portta:
+    external: true
+    name: ${PORTTA_NETWORK:-portta}

package/dist/runtime/templates/overlays/06-monorepo.yaml

@@ -0,0 +1,63 @@
+# ============================================================================
+# Monorepo: apps/ and services/ in one repository
+# ============================================================================
+# A monorepo is one Compose project with more services in it. Nothing about the
+# contract changes, and the gateway needs to know nothing about the layout.
+#
+#   repo/
+#     apps/web/          -> web
+#     apps/admin/        -> admin
+#     services/api/      -> api
+#     services/worker/   -> worker      (no HTTP; not routed)
+#     services/importer/ -> importer    (no HTTP; not routed)
+#     compose.yaml
+#     compose.portta.yaml   <- this file
+#
+#   -> http://<COMPOSE_PROJECT_NAME>-web.localhost
+#   -> http://<COMPOSE_PROJECT_NAME>-admin.localhost
+#   -> http://<COMPOSE_PROJECT_NAME>-api.localhost
+#
+# Build contexts, Dockerfiles and volumes stay exactly where they are. The
+# gateway never centralises any of that.
+#
+# Splitting one monorepo into several namespaces is possible: run separate
+# Compose projects per app: but it is rarely worth it: one namespace keeps the
+# services on a single private network, which is usually what they expect.
+# ============================================================================
+
+services:
+  web:
+    networks: [default, portta]
+    labels:
+      # Optional, and only useful because inference cannot get them right here:
+      # `portta.git.root` says where the repository actually starts when
+      # the Compose file is not at its root, and `portta.repo` gives the
+      # panel a repository link with no host-side Git at all. Delete both and
+      # everything behaves exactly as it does now.
+      # - "portta.repo=owner/monorepo"
+      # - "portta.git.root=/srv/dev/monorepo"
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-web.loadbalancer.server.port=3000"
+
+  admin:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-admin.loadbalancer.server.port=3000"
+
+  api:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-api.loadbalancer.server.port=8000"
+
+  # worker and importer are absent on purpose: they serve no HTTP, so they need
+  # no networks and no labels. They keep running exactly as they did.
+
+networks:
+  portta:
+    external: true
+    name: ${PORTTA_NETWORK:-portta}

package/dist/runtime/templates/overlays/07-worktree.env

@@ -0,0 +1,47 @@
+# ============================================================================
+# A second copy of a project, running in parallel
+# ============================================================================
+# Copy to `.env` in the worktree. This is the entire mechanism: Compose derives
+# container, network and volume names from COMPOSE_PROJECT_NAME, and the gateway
+# derives hostnames from it.
+#
+#   git worktree add ../base-empresarial-issue59 issue59
+#   cd ../base-empresarial-issue59
+#   cp <this file> .env
+#   docker compose -f compose.yaml -f compose.portta.yaml up -d
+#
+#   -> http://base-empresarial-issue59-web.localhost
+#
+# The original environment keeps running. Nothing inside the project changed.
+# Derive the name instead of inventing one:
+#
+#   portta env namespace
+# ============================================================================
+
+COMPOSE_PROJECT_NAME=base-empresarial-issue59
+
+# Saves repeating -f on every command.
+COMPOSE_FILE=compose.yaml:compose.portta.yaml
+
+# Must match PORTTA_NETWORK in the gateway's own .env.
+PORTTA_NETWORK=portta
+
+# ---------------------------------------------------------------------------
+# Optional: say which project this worktree belongs to
+# ---------------------------------------------------------------------------
+# COMPOSE_PROJECT_NAME is a per-worktree namespace, so five worktrees look like
+# five projects in the panel. A `portta.project` label on any one service
+# groups them back under one heading. Nothing depends on it: without it the
+# panel still infers the worktree from the directory name, exactly as before.
+#
+#   labels:
+#     - "portta.project=base-empresarial"
+#     - "portta.repo=owner/base-empresarial"
+
+# ---------------------------------------------------------------------------
+# What must NOT be shared with the other worktree
+# ---------------------------------------------------------------------------
+# Do not point this environment at an external volume or a database the other
+# copy also uses. Two worktrees writing to one database is the failure this
+# whole mechanism exists to prevent, and it is silent until it corrupts
+# something. Let Compose create per-namespace volumes.

package/dist/runtime/templates/overlays/08-nonstandard-port.yaml

@@ -0,0 +1,41 @@
+# ============================================================================
+# An HTTP service on an unusual internal port
+# ============================================================================
+# Traefik guesses the backend port from the image's EXPOSE when only one port
+# is exposed. That guess is wrong whenever the image exposes one port and the
+# application listens on another: which is most of the time once a command or
+# an environment variable moves it.
+#
+# The symptom is a 502 from the gateway: the route matched, the backend did not
+# answer. Stating the port removes the guess.
+#
+# Anything is fine here: 4321, 9090, 1313. The port is internal, so it never
+# competes with another project.
+# ============================================================================
+
+services:
+  docs:
+    # e.g. a static site generator listening on 1313
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-docs.loadbalancer.server.port=1313"
+
+  # A service whose container serves HTTPS internally needs the scheme too,
+  # or Traefik will speak plaintext to a TLS port.
+  secure-backend:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-secure-backend.loadbalancer.server.port=8443"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-secure-backend.loadbalancer.server.scheme=https"
+      # Development backends usually have a self-signed certificate.
+      - "traefik.http.serverstransports.${COMPOSE_PROJECT_NAME}-insecure.insecureskipverify=true"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-secure-backend.loadbalancer.serverstransport=${COMPOSE_PROJECT_NAME}-insecure@docker"
+
+networks:
+  portta:
+    external: true
+    name: ${PORTTA_NETWORK:-portta}

package/dist/runtime/templates/overlays/09-tcp-routing.yaml

@@ -0,0 +1,70 @@
+# ============================================================================
+# Template 09: reach this project's database by hostname
+# ============================================================================
+# Add this on top of your project's own compose file, alongside whichever HTTP
+# overlay you already use. It opts a datastore into hostname routing, so it is
+# reachable on the gateway's shared port without publishing one of its own:
+#
+#   psql "postgresql://user@<project>-postgres.<domain>:5432/db?sslmode=require"
+#
+# Requires PORTTA_TCP=true on the gateway. Read docs/product/guides/tcp-routing.md first:
+# PostgreSQL and Redis work, MySQL cannot, and TLS is not optional.
+#
+#   docker compose -f compose.yaml -f compose.portta.yaml \
+#                  -f compose.portta-tcp.yaml up -d
+#
+# Three details worth copying verbatim:
+#
+# 1. The datastore joins `portta-access`, NOT the shared `portta`
+#    network. Databases have never been on the HTTP network and still are not.
+#
+# 2. The rule is HostSNIRegexp, not HostSNI, so this file does not have to know
+#    the gateway's domain. The same overlay then works unchanged against
+#    `.localhost` on a workstation and `.vpn.example.com` on a VPS. It grants
+#    nothing extra: whoever knows the project name can reach the entrypoint
+#    with the exact hostname anyway, and authentication is still PostgreSQL's.
+#
+# 3. Router and service names carry the project name, because they share one
+#    namespace across every project on the host. `portta doctor` reports
+#    a collision if two projects ever pick the same one.
+# ============================================================================
+
+services:
+  postgres:
+    networks:
+      - default        # keep talking to the rest of the project privately
+      - portta-access
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_ACCESS_NETWORK:-portta-access}"
+      - "traefik.tcp.routers.${COMPOSE_PROJECT_NAME}-postgres.entrypoints=postgres"
+      - "traefik.tcp.routers.${COMPOSE_PROJECT_NAME}-postgres.rule=HostSNIRegexp(`^${COMPOSE_PROJECT_NAME}-postgres\\..+$`)"
+      - "traefik.tcp.routers.${COMPOSE_PROJECT_NAME}-postgres.tls=true"
+      # libpq 17+ offers ALPN `postgresql`; without this option the TLS
+      # handshake is rejected before any Postgres traffic happens.
+      - "traefik.tcp.routers.${COMPOSE_PROJECT_NAME}-postgres.tls.options=postgres@file"
+      - "traefik.tcp.routers.${COMPOSE_PROJECT_NAME}-postgres.service=${COMPOSE_PROJECT_NAME}-postgres"
+      - "traefik.tcp.services.${COMPOSE_PROJECT_NAME}-postgres.loadbalancer.server.port=5432"
+
+  redis:
+    networks:
+      - default
+      - portta-access
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_ACCESS_NETWORK:-portta-access}"
+      - "traefik.tcp.routers.${COMPOSE_PROJECT_NAME}-redis.entrypoints=redis"
+      - "traefik.tcp.routers.${COMPOSE_PROJECT_NAME}-redis.rule=HostSNIRegexp(`^${COMPOSE_PROJECT_NAME}-redis\\..+$`)"
+      - "traefik.tcp.routers.${COMPOSE_PROJECT_NAME}-redis.tls=true"
+      - "traefik.tcp.routers.${COMPOSE_PROJECT_NAME}-redis.service=${COMPOSE_PROJECT_NAME}-redis"
+      - "traefik.tcp.services.${COMPOSE_PROJECT_NAME}-redis.loadbalancer.server.port=6379"
+
+  # MySQL and MariaDB are deliberately absent. The MySQL protocol has the
+  # server speak first, so there is no SNI for the gateway to route on before
+  # it must choose a backend. Reach them with `portta access open`, which
+  # works for every protocol. docs/product/guides/tcp-routing.md explains why in full.
+
+networks:
+  portta-access:
+    external: true
+    name: ${PORTTA_ACCESS_NETWORK:-portta-access}

package/dist/runtime/templates/overlays/10-mailpit.yaml

@@ -0,0 +1,24 @@
+# ============================================================================
+# Mailpit: capture outbound mail in development
+# ============================================================================
+# The UI (8025) is HTTP and joins the gateway. SMTP (1025) stays on the
+# project's private network and is reached with `portta access open`.
+#
+# The base Compose file should declare the mailpit service itself; this overlay
+# only adds the network and labels.
+#
+#   -> http://<COMPOSE_PROJECT_NAME>-mailpit.localhost
+# ============================================================================
+
+services:
+  mailpit:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-mailpit.loadbalancer.server.port=8025"
+
+networks:
+  portta:
+    external: true
+    name: ${PORTTA_NETWORK:-portta}

package/dist/runtime/templates/overlays/11-rustfs.yaml

@@ -0,0 +1,25 @@
+# ============================================================================
+# RustFS: S3-compatible object storage in development
+# ============================================================================
+# The console (9001) is HTTP and joins the gateway. The S3 API (9000) stays on
+# the project's private network so sibling containers can talk to it as
+# `rustfs:9000` without publishing a host port.
+#
+# The base Compose file should declare the rustfs service itself; this overlay
+# only adds the network and labels for the console.
+#
+#   -> http://<COMPOSE_PROJECT_NAME>-rustfs.localhost
+# ============================================================================
+
+services:
+  rustfs:
+    networks: [default, portta]
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=${PORTTA_NETWORK:-portta}"
+      - "traefik.http.services.${COMPOSE_PROJECT_NAME}-rustfs.loadbalancer.server.port=9001"
+
+networks:
+  portta:
+    external: true
+    name: ${PORTTA_NETWORK:-portta}

package/dist/runtime/templates/project/PORTTA.md

@@ -0,0 +1,107 @@
+# Running this project on Portta
+
+> Copy this file into the project and adjust the names. It covers only what
+> someone working on *this* project needs. The rules themselves live in the Dev
+> Gateway repository, which stays the single source of truth.
+
+## Prerequisites
+
+Portta must be running on this machine:
+
+```bash
+portta status      # if this fails: portta bootstrap && portta up local
+```
+
+## Starting
+
+```bash
+docker compose -f compose.yaml -f compose.portta.yaml up -d
+```
+
+Set `COMPOSE_FILE=compose.yaml:compose.portta.yaml` in `.env` to drop the
+`-f` flags.
+
+## Namespace
+
+`COMPOSE_PROJECT_NAME` is what keeps this environment separate from every other
+one on the host: containers, network, volumes and hostnames all derive from it.
+
+```env
+# .env
+COMPOSE_PROJECT_NAME=<project>
+```
+
+## URLs
+
+```bash
+portta urls --project <project>
+```
+
+| Service | URL |
+|---|---|
+| web | `http://<project>-web.localhost` |
+| api | `http://<project>-api.localhost` |
+
+No port numbers, and no host port is published for either.
+
+## Database and cache
+
+Not published on the host. Two ways in:
+
+**From inside the project**, with nothing to open and nothing to close:
+
+```bash
+docker compose exec postgres psql -U <user> -d <db>
+docker compose exec redis redis-cli
+```
+
+**From a GUI on the host**, through a temporary loopback bridge on a free port:
+
+```bash
+portta access open --project <project> --service postgres
+# -> 127.0.0.1:55431
+
+portta access list
+portta access close --project <project>
+```
+
+Point TablePlus, DBeaver or DataGrip at `127.0.0.1` and the port it printed.
+Credentials are this project's, from its own `.env`.
+
+## Working on two branches at once
+
+```bash
+git worktree add ../<project>-issue59 issue59
+cd ../<project>-issue59
+echo "COMPOSE_PROJECT_NAME=<project>-issue59" >> .env
+docker compose -f compose.yaml -f compose.portta.yaml up -d
+# -> http://<project>-issue59-web.localhost
+```
+
+Both run at once, each with its own database. The first environment is not
+affected.
+
+## Troubleshooting
+
+```bash
+portta doctor
+portta urls --project <project>
+docker compose logs -f
+```
+
+**404**: the service did not opt in, or Traefik has not discovered it yet.
+**502**: the route matched but the backend did not answer, usually the wrong
+port in the overlay, or the service is not on the `portta` network.
+
+More: Portta's `docs/product/guides/troubleshooting.md`.
+
+## Without the gateway
+
+The overlay only adds networks and labels, so the project still runs on its own:
+
+```bash
+docker compose up -d
+```
+
+You lose hostname routing, so you will need published ports. Put those in your
+personal `compose.override.yaml`, not in the shared files.