local-development-gateway 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d72f55ac50271b2247bd8eb5189f4b6c25c30a62a8cb0d451cecc38b050ea98e
+  data.tar.gz: ea4e0fda3f4f88cb39666580be77960eeab97994adfd599e3b4e2db02c96f5cc
+SHA512:
+  metadata.gz: 6bbf54e670547b4ff3a4b332094493ad1c825df43a50d29079b6ebfe88d85922ad6a1d73877a8de28ce22fcf2974b48db28c70250b3389d77a062a6fd14a19d9
+  data.tar.gz: 74cfbf75708d8e46a47e19ffc4a94b732e502372edfc565702c98e7ab8177e98208e543d3be45c822a6ed76bbdd83cb56bf3b50931efb334c2d3516dff4228e7

data/README.md

@@ -0,0 +1,173 @@
+# Local Development Gateway
+
+One shared loopback-only gateway for browser-facing Docker development services.
+
+It lets several local projects use stable hostnames instead of competing for browser ports. It is intended to run once at the beginning of a development day and remain running while projects start and stop.
+
+## What problem this solves
+
+Without a gateway, two projects commonly both try to publish a web service on port `8080` and a backend service on port `3000`. Only one can start.
+
+With this gateway running, a project can publish its internal web service through a generated hostname instead:
+
+```text
+http://port-35053.traditional-knowledge.localhost
+                         |
+                         v
+Local Development Gateway on 127.0.0.1:80
+                         |
+                         v
+Traditional Knowledge web container on internal port 8080
+```
+
+`port-35053` is derived from Traditional Knowledge's generated `WEB_PORT` value. It identifies the project instance; the browser reaches the web service through the gateway on port `80`, not directly on port `35053`.
+
+The generated hostname is a local `*.localhost` name. It resolves to loopback and does not require a public domain, external DNS provider, or internet-facing listener.
+
+## Start once per day
+
+Use the small repository wrapper for the common lifecycle commands:
+
+```sh
+bin/dev up
+```
+
+Check the gateway:
+
+```sh
+bin/dev status
+```
+
+Follow its logs:
+
+```sh
+bin/dev logs
+```
+
+Stop it only when no participating local project needs it:
+
+```sh
+bin/dev down
+```
+
+The wrapper also passes unrecognized arguments directly to `docker compose`, so
+`bin/dev config` and `bin/dev up --force-recreate` remain available.
+
+Port `80` on `127.0.0.1` must be free before starting. The gateway never binds to a non-loopback address.
+
+## Install as a gem
+
+Consuming projects do not need a gateway checkout. Add the released gem to
+their bundle and pin the compatible minor version:
+
+```ruby
+gem "local-development-gateway", "~> 0.1.0"
+```
+
+The gem packages the gateway Compose file and pinned Traefik configuration.
+Its executable provides the same lifecycle commands:
+
+```sh
+bundle exec local-development-gateway up
+bundle exec local-development-gateway status
+bundle exec local-development-gateway logs
+bundle exec local-development-gateway down
+```
+
+`local-development-gateway` uses the installed asset path, the
+`local-gateway` Compose project and network labels, and the pinned minimum Ruby
+version declared by the gem. Upgrade the version constraint when a new
+compatible release is published. The repository's `bin/dev` is only a thin
+wrapper around this executable API.
+
+## Use case: Traditional Knowledge beside WRAP
+
+1. Start this gateway once.
+2. Run `dev up` in Traditional Knowledge. It writes role-based generated values to `.env.development.local`, including `WEB_PORT`, `BACKEND_PORT`, and `WEB_HOSTNAME=port-<WEB_PORT>.traditional-knowledge.localhost`.
+3. With the gateway running, Traditional Knowledge's web container joins `local-gateway`, its direct web publishing is removed, and the generated hostname routes through the gateway on `127.0.0.1:80`.
+4. Open `WEB_HOSTNAME` from `.env.development.local`.
+5. When WRAP adopts the same contract, start it normally. It can then use its own generated route labels and hostname through this same gateway.
+
+Each project receives an independent hostname, while the gateway owns the single browser port. The generated `WEB_PORT` is an identity seed in gateway mode, not the browser-facing port.
+
+Without the gateway, Traditional Knowledge publishes the same generated values directly, including `localhost:<WEB_PORT>` for the web service and `localhost:<BACKEND_PORT>` for the backend. `dev up` regenerates unavailable assignments; deleting `.env.development.local` forces a fresh assignment.
+
+## Contract for participating projects
+
+The gateway:
+
+- listens only on `127.0.0.1:80`;
+- creates the external Docker network `local-gateway`;
+- discovers only services explicitly labelled for routing;
+- has the Docker label `local-gateway=true` so a project can detect it.
+
+A participating project writes role-based generated values to its local `.env.development.local`:
+
+```dotenv
+WEB_PORT=35053
+BACKEND_PORT=38261
+WEB_HOSTNAME=port-35053.traditional-knowledge.localhost
+```
+
+With the gateway available, its web service joins `local-gateway` and supplies explicit route labels. Use a project-prefixed identifier containing the published `BACKEND_PORT` for the internal router/service name; do not generate a separate `STACK_IDENTIFIER`:
+
+```yaml
+services:
+  web:
+    networks:
+      - default
+      - local-gateway
+    labels:
+      - "traefik.enable=true"
+      - "traefik.docker.network=local-gateway"
+      - "traefik.http.routers.<project>-<backend-port>.rule=Host(`<web-hostname>`)"
+      - "traefik.http.routers.<project>-<backend-port>.entrypoints=web"
+      - "traefik.http.routers.<project>-<backend-port>.service=<project>-<backend-port>"
+      - "traefik.http.services.<project>-<backend-port>.loadbalancer.server.port=8080"
+
+networks:
+  local-gateway:
+    external: true
+    name: local-gateway
+```
+
+Without the gateway, publish the same generated values directly:
+
+```yaml
+services:
+  web:
+    ports:
+      - "127.0.0.1:${WEB_PORT}:8080"
+  backend:
+    ports:
+      - "127.0.0.1:${BACKEND_PORT}:3000"
+```
+
+Use a unique generated `WEB_PORT` and `BACKEND_PORT` for every running project instance. Never derive a destination port from the hostname; each route must name one explicit Docker service and internal port.
+
+## Authentication callbacks
+
+A wildcard hostname lets an identity provider allow one local callback pattern instead of every generated port. For Traditional Knowledge, configure:
+
+```text
+Allowed Callback URLs: http://*.traditional-knowledge.localhost/callback
+Allowed Logout URLs:   http://*.traditional-knowledge.localhost
+Allowed Web Origins:   http://*.traditional-knowledge.localhost
+```
+
+Keep existing production and staging entries. Verify that the identity provider accepts wildcard hostnames in each field before relying on this pattern.
+
+## Security boundary
+
+The gateway publishes port `80` only to the local machine. It does not create a public endpoint.
+
+It mounts the Docker socket so it can discover labelled containers. A read-only socket mount still exposes broad Docker metadata and control-plane access. Treat anyone who can modify this repository or its running gateway container as having significant access to local Docker. Do not run untrusted gateway images or route untrusted containers through it.
+
+## Troubleshooting
+
+| Symptom | Check |
+| --- | --- |
+| Gateway will not start | Confirm `127.0.0.1:80` is free. |
+| Generated hostname returns `404` | Confirm the web container has the route labels and is attached to `local-gateway`. |
+| A project uses normal ports unexpectedly | Confirm the gateway container is running and has `local-gateway=true`. |
+| Authentication rejects the callback | Confirm the generated hostname matches the allowed wildcard callback pattern. |

data/bin/local-development-gateway

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "local_development_gateway"
+
+exit LocalDevelopmentGateway::CLI.run(ARGV)

data/config/traefik.yml

@@ -0,0 +1,11 @@
+# Pinned with the gateway gem so every consumer uses the same routing contract.
+entryPoints:
+  web:
+    address: ":80"
+
+ping: {}
+
+providers:
+  docker:
+    exposedByDefault: false
+    network: local-gateway

data/docker-compose.yml

@@ -0,0 +1,27 @@
+name: local-gateway
+
+services:
+  gateway:
+    image: traefik:v3.7.8
+    command:
+      - --configFile=/etc/traefik/traefik.yml
+    healthcheck:
+      test: ["CMD", "traefik", "healthcheck", "--ping"]
+      interval: 1s
+      timeout: 3s
+      retries: 30
+      start_period: 1s
+    labels:
+      local-gateway: "true"
+    ports:
+      - "127.0.0.1:80:80"
+    restart: unless-stopped
+    volumes:
+      - ./config/traefik.yml:/etc/traefik/traefik.yml:ro
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+    networks:
+      - local-gateway
+
+networks:
+  local-gateway:
+    name: local-gateway

data/lib/local_development_gateway/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module LocalDevelopmentGateway
+  VERSION = "0.1.0"
+end

data/lib/local_development_gateway.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "local_development_gateway/version"
+
+module LocalDevelopmentGateway
+  PROJECT_NAME = "local-gateway"
+  NETWORK_NAME = "local-gateway"
+  SERVICE_NAME = "gateway"
+  GATEWAY_LABEL = "local-gateway"
+  ASSET_ROOT = File.expand_path("..", __dir__)
+  COMPOSE_FILE = File.join(ASSET_ROOT, "docker-compose.yml")
+  TRAEFIK_CONFIG_FILE = File.join(ASSET_ROOT, "config", "traefik.yml")
+
+  class Error < StandardError; end
+
+  class DockerError < Error
+    attr_reader :command, :output
+
+    def initialize(command, output)
+      @command = command
+      @output = output
+      super("Docker command failed: #{command.join(" ")}\n#{output}")
+    end
+  end
+
+  class Docker
+    def call(*args, capture: true)
+      command = ["docker", *args]
+      if capture
+        stdout, stderr, status = Open3.capture3(*command)
+        raise DockerError.new(command, stderr.empty? ? stdout : stderr) unless status.success?
+
+        stdout
+      elsif system(*command)
+        true
+      else
+        raise DockerError.new(command, "")
+      end
+    end
+  end
+
+  class Client
+    CONTAINER_FORMAT = "{{.ID}}\t{{.Label \"com.docker.compose.project\"}}\t{{.Label \"com.docker.compose.service\"}}\t{{.Label \"local-gateway\"}}"
+
+    def initialize(
+      runner: Docker.new,
+      timeout: 30,
+      poll_interval: 0.25,
+      sleeper: ->(seconds) { sleep seconds },
+      clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) }
+    )
+      @runner = runner
+      @timeout = timeout
+      @poll_interval = poll_interval
+      @sleeper = sleeper
+      @clock = clock
+    end
+
+    def ensure_running(*compose_args)
+      return :reused if compose_args.empty? && ready?
+
+      compose("up", "-d", "--remove-orphans", *compose_args)
+      wait_until_ready
+      :started
+    end
+
+    alias start ensure_running
+
+    def ready?
+      network_exists? && gateway_container_ids(status: "running").any? { |id| healthy_container?(id) }
+    end
+
+    def status
+      compose("ps", "--all")
+    end
+
+    def logs(*args, follow: false)
+      compose("logs", *(follow ? ["--follow"] : []), *args, capture: false)
+    end
+
+    def stop_if_unused
+      return :not_running unless gateway_exists?
+      return :in_use if non_gateway_containers_attached?
+
+      compose("down", "--remove-orphans")
+      :stopped
+    end
+
+    def compose(*args, capture: true)
+      @runner.call(
+        "compose",
+        "--project-name", PROJECT_NAME,
+        "--file", COMPOSE_FILE,
+        *args,
+        capture: capture,
+      )
+    end
+
+    private
+
+    def wait_until_ready
+      deadline = @clock.call + @timeout
+      until ready?
+        raise Error, "Local Development Gateway did not become ready" if @clock.call >= deadline
+
+        @sleeper.call(@poll_interval)
+      end
+    end
+
+    def network_exists?
+      labels = @runner.call(
+        "network",
+        "inspect",
+        NETWORK_NAME,
+        "--format",
+        "{{index .Labels \"com.docker.compose.project\"}}\t{{index .Labels \"com.docker.compose.network\"}}",
+      )
+      labels.lines.any? { |line| line.strip == "#{PROJECT_NAME}\t#{NETWORK_NAME}" }
+    rescue DockerError
+      false
+    end
+
+    def gateway_exists?
+      network_exists? && !gateway_container_ids.empty?
+    end
+
+    def gateway_container_ids(status: nil)
+      args = ["ps"]
+      args << "--all" unless status
+      args.concat([
+        "--filter", "network=#{NETWORK_NAME}",
+        "--filter", "label=com.docker.compose.project=#{PROJECT_NAME}",
+        "--filter", "label=com.docker.compose.service=#{SERVICE_NAME}",
+        "--filter", "label=#{GATEWAY_LABEL}=true",
+      ])
+      args.push("--filter", "status=#{status}") if status
+      output = @runner.call(*args, "--quiet")
+      output.lines.map(&:strip).reject(&:empty?)
+    end
+
+    def healthy_container?(id)
+      @runner.call("inspect", "--format", "{{.State.Health.Status}}", id).strip == "healthy"
+    rescue DockerError
+      false
+    end
+
+    def attached_containers
+      output = @runner.call(
+        "ps",
+        "--all",
+        "--filter", "network=#{NETWORK_NAME}",
+        "--format", CONTAINER_FORMAT,
+      )
+      output.lines.filter_map do |line|
+        id, project, service, label = line.strip.split("\t", -1)
+        next if id.nil? || id.empty?
+
+        { id: id, project: project, service: service, label: label }
+      end
+    end
+
+    def non_gateway_containers_attached?
+      attached_containers.any? do |container|
+        !gateway_container?(container)
+      end
+    end
+
+    def gateway_container?(container)
+      container[:project] == PROJECT_NAME &&
+        container[:service] == SERVICE_NAME &&
+        container[:label] == "true"
+    end
+  end
+
+  class CLI
+    USAGE = <<~USAGE
+      Usage: local-development-gateway COMMAND [OPTIONS]
+
+      Commands:
+        up, ensure  Start or reuse the shared gateway
+        status      Show the gateway Compose status
+        ready       Check gateway readiness
+        logs        Follow gateway logs
+        down, stop  Stop the gateway only when unused
+
+      Other commands are passed to Docker Compose using the packaged assets.
+    USAGE
+
+    def self.run(argv, client: Client.new, output: $stdout, error: $stderr)
+      new(argv, client: client, output: output, error: error).run
+    end
+
+    def initialize(argv, client:, output:, error:)
+      @argv = argv.dup
+      @client = client
+      @output = output
+      @error = error
+    end
+
+    def run
+      command = @argv.shift
+      return print_usage(0) if command.nil? || %w[help --help -h].include?(command)
+
+      case command
+      when "up", "ensure"
+        @client.ensure_running(*@argv)
+      when "status"
+        @output.write(@client.status)
+      when "ready"
+        return 0 if @client.ready?
+
+        @error.puts "Local Development Gateway is not ready"
+        return 1
+      when "logs"
+        @client.logs(*@argv, follow: true)
+      when "down", "stop"
+        report_stop(@client.stop_if_unused)
+      else
+        @output.write(@client.compose(command, *@argv))
+      end
+      0
+    rescue Error => error
+      @error.puts error.message
+      1
+    end
+
+    private
+
+    def print_usage(status)
+      @output.write(USAGE)
+      status
+    end
+
+    def report_stop(result)
+      messages = {
+        not_running: "Local Development Gateway is not running",
+        in_use: "Leaving Local Development Gateway running because another container is attached",
+        stopped: "Stopped Local Development Gateway",
+      }
+      @output.puts messages.fetch(result)
+    end
+  end
+
+  class << self
+    def ensure_running(*args)
+      Client.new.ensure_running(*args)
+    end
+
+    def start(*args)
+      ensure_running(*args)
+    end
+
+    def ready?
+      Client.new.ready?
+    end
+
+    def status
+      Client.new.status
+    end
+
+    def logs(*args)
+      Client.new.logs(*args, follow: true)
+    end
+
+    def stop_if_unused
+      Client.new.stop_if_unused
+    end
+  end
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: local-development-gateway
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Marlen Brunner
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-28 00:00:00.000000000 Z
+dependencies: []
+description: Ruby API and CLI for starting, monitoring, and conditionally stopping
+  the shared Docker gateway.
+email:
+- marlen@icefoganalytics.com
+executables:
+- local-development-gateway
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/local-development-gateway
+- config/traefik.yml
+- docker-compose.yml
+- lib/local_development_gateway.rb
+- lib/local_development_gateway/version.rb
+homepage: https://github.com/icefoganalytics/local-development-gateway
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/icefoganalytics/local-development-gateway/issues
+  source_code_uri: https://github.com/icefoganalytics/local-development-gateway
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Shared loopback gateway lifecycle for local Docker development
+test_files: []