proximo

command module
v0.5.0 Latest Latest
Warning

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

Go to latest
Published: Jun 5, 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

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.

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 Routing.

Development

No local Go toolchain is required — every Make target runs Go inside the golang image (with a persistent module/build cache), so Docker is the only prerequisite:

make build      # build bin/proximo-<os>-<arch> for the host (Go runs in Docker)
make build-all  # cross-compile all targets (darwin,linux × amd64,arm64)
make test       # run the test suite (always Linux, in the golang image)
make vet        # go vet
make tidy       # go mod tidy

The binary is named per OS/arch (bin/proximo-darwin-arm64, bin/proximo-linux-amd64, …) so a macOS and a Linux build never overwrite each other in a shared working tree. Override the host target with make build GOOS=linux GOARCH=amd64.

Running it via Make

The lifecycle targets build first (so the binary always matches the host) and run the host binary, which talks to the host Docker socket:

make install   # host setup (CA, resolver, trust) + start stack — asks for sudo
make up         # start the stack (no host changes)
make status     # list routed containers
make down        # stop the stack
make uninstall  # reverse host changes + tear down
make e2e         # install + start the whoami demo + open https://whoami.test
make e2e-down    # stop demo + uninstall
Local testing without publishing

The stack's dns and watcher images are normally built with go install github.com/filippolmt/proximo/cmd/...@<ref>, which needs the module to be published. The Make lifecycle targets above pass PROXIMO_SRC=$(pwd) automatically, so those images build from local source (no push, no module fetch) via a generated docker-compose.override.yml. Run the binary directly without PROXIMO_SRC to use the published images instead.

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