proximo

command module
v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 18, 2026 License: MIT Imports: 1 Imported by: 0

README ΒΆ

proximo

Make any running Docker container reachable at https://<name>.test β€” with automatic local DNS and trusted HTTPS β€” on macOS and Linux. No per-container published ports, no /etc/hosts edits.

proximo gives you automatic Host-based routing plus the two things that are usually left to you: local DNS and a trusted certificate. The only mandatory prerequisite is Docker; DNS and certificates are produced natively in Go.

Documentation

πŸ“– Read the full guide β€” the docs below, rendered and searchable.

Full guides live in docs/:

  • Installation β€” requirements, install steps, what it changes on your host, and how to reverse it.
  • CLI reference β€” every command with examples.
  • Updating β€” proximo update, skew detection, and how updates apply to the stack.
  • Architecture β€” the stack, DNS, the local CA, the watcher.
  • Routing β€” the proximo.* labels and Traefik compatibility.
  • Dev-time observability β€” opt-in up --observability logs (Dozzle) + metrics (Beszel) dashboards: credential-less and over trusted HTTPS (http:// auto-redirects).
  • Troubleshooting β€” common issues. Container labeled but unreachable? Start with the container not routed checklist.
  • Development β€” building, testing from source, versioning, releases.

Quick start

Install the binary (macOS via Homebrew; Linux via release binary or go install β€” see Installation):

brew install filippolmt/tap/proximo          # macOS
go install github.com/filippolmt/proximo@latest   # Linux/from source

One-time host setup (CA, resolver, trust, and the stack β€” needs sudo once):

proximo install

Label any container with the host you want, then bring it up:

# docker-compose.yml
services:
  whoami:
    image: traefik/whoami
    labels:
      - "proximo.hosts=whoami.test"   # the port is auto-detected (single EXPOSE)
docker compose up -d
open https://whoami.test   # macOS β€” trusted HTTPS, no warning
proximo status             # see what's routed
open https://traefik.test  # Traefik's own dashboard, always on (traefik.<tld> is reserved)

A ready-to-run sample is in examples/whoami/. For the label contract (multiple hosts, explicit port, opt-out, native Traefik labels) see the routing label table. If something does not work, the troubleshooting checklist walks through the usual causes.

Development

No local Go toolchain is required β€” every Make target runs Go inside the golang image, so Docker is the only prerequisite:

make build      # build bin/proximo-<os>-<arch> for the host (Go runs in Docker)
make test       # run the test suite

Everything else β€” all Make targets, the lifecycle targets, running the stack from local source (PROXIMO_SRC), versioning, embedded assets, releases β€” is in the development guide.

License

MIT β€” free to use, modify, and distribute.

Documentation ΒΆ

Overview ΒΆ

Command proximo is a local development reverse proxy that makes any running Docker container reachable at https://<name>.<tld> with automatic DNS and trusted HTTPS, on macOS and Linux.

Directories ΒΆ

Path Synopsis
cmd
dnsserver command
Command dnsserver is the wildcard DNS server that runs inside the proximo stack.
Command dnsserver is the wildcard DNS server that runs inside the proximo stack.
watcher command
Command watcher runs inside the proximo stack and keeps the Traefik container attached to the Docker networks of routed containers across their lifecycle.
Command watcher runs inside the proximo stack and keeps the Traefik container attached to the Docker networks of routed containers across their lifecycle.
internal
cli
Package cli implements the proximo command surface.
Package cli implements the proximo command surface.
config
Package config manages proximo's persisted user configuration and the on-disk paths it uses (TLS material, the embedded stack, etc.).
Package config manages proximo's persisted user configuration and the on-disk paths it uses (TLS material, the embedded stack, etc.).
dns
Package dns implements the wildcard DNS server and the host-resolver wiring that route the configured TLD to the local proximo.
Package dns implements the wildcard DNS server and the host-resolver wiring that route the configured TLD to the local proximo.
docker
Package docker materializes and drives the embedded reverse-proxy stack (Traefik + DNS server + network watcher) via `docker compose`, and hosts the network-attach watcher used inside the stack.
Package docker materializes and drives the embedded reverse-proxy stack (Traefik + DNS server + network watcher) via `docker compose`, and hosts the network-attach watcher used inside the stack.
observability
Package observability bootstraps the opt-in dev-time observability stack (Dozzle logs + Beszel metrics hub/agent).
Package observability bootstraps the opt-in dev-time observability stack (Dozzle logs + Beszel metrics hub/agent).
platform
Package platform provides OS / package-manager detection and the small set of privileged and unprivileged host operations the CLI relies on.
Package platform provides OS / package-manager detection and the small set of privileged and unprivileged host operations the CLI relies on.
tls
Package tls generates the local CA and wildcard certificate (via crypto/x509) and installs/removes trust in the system and NSS stores.
Package tls generates the local CA and wildcard certificate (via crypto/x509) and installs/removes trust in the system and NSS stores.
version
Package version holds build metadata injected at release time via -ldflags.
Package version holds build metadata injected at release time via -ldflags.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL