{"id":50500476,"url":"https://github.com/filippolmt/proximo","last_synced_at":"2026-06-02T11:00:49.055Z","repository":{"id":362030147,"uuid":"1255813901","full_name":"filippolmt/proximo","owner":"filippolmt","description":"Local-dev reverse proxy: reach any Docker container at https://\u003cname\u003e.test with automatic DNS and trusted HTTPS, on macOS \u0026 Linux. No published ports, no /etc/hosts edits.","archived":false,"fork":false,"pushed_at":"2026-06-02T10:14:13.000Z","size":71,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-02T10:22:07.766Z","etag":null,"topics":["certificate-authority","cli","developer-tools","dns","docker","golang","homebrew","https","linux","local-development","macos","reverse-proxy","tls","traefik"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/filippolmt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-01T07:38:05.000Z","updated_at":"2026-06-02T10:14:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/filippolmt/proximo","commit_stats":null,"previous_names":["filippolmt/proximo"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/filippolmt/proximo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filippolmt%2Fproximo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filippolmt%2Fproximo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filippolmt%2Fproximo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filippolmt%2Fproximo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/filippolmt","download_url":"https://codeload.github.com/filippolmt/proximo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/filippolmt%2Fproximo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33818568,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["certificate-authority","cli","developer-tools","dns","docker","golang","homebrew","https","linux","local-development","macos","reverse-proxy","tls","traefik"],"created_at":"2026-06-02T11:00:27.697Z","updated_at":"2026-06-02T11:00:49.002Z","avatar_url":"https://github.com/filippolmt.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# proximo\n\nMake any running Docker container reachable at **`https://\u003cname\u003e.test`** — with\nautomatic local DNS and trusted HTTPS — on macOS and Linux. No per-container\npublished ports, no `/etc/hosts` edits.\n\n`proximo` gives you automatic `Host`-based routing plus the two things that are\nusually left to you: local DNS and a trusted certificate. The only mandatory\nprerequisite is Docker; DNS and certificates are produced natively in Go.\n\n## Documentation\n\nFull guides live in [`docs/`](docs/README.md):\n\n- [Installation](docs/installation.md) — requirements, install steps, what it\n  changes on your host, and how to reverse it.\n- [CLI reference](docs/cli.md) — every command with examples.\n- [Updating](docs/updating.md) — `proximo update`, skew detection, and how\n  updates apply to the stack.\n- [Architecture](docs/architecture.md) — the stack, DNS, the local CA, the\n  watcher.\n- [Routing](docs/routing.md) — the `proximo.*` labels and Traefik compatibility.\n- [Troubleshooting](docs/troubleshooting.md) — common issues.\n\n## Quick start\n\nInstall the binary (macOS via Homebrew; Linux via release binary or\n`go install` — see [Installation](docs/installation.md)):\n\n```sh\nbrew install filippolmt/tap/proximo          # macOS\ngo install github.com/filippolmt/proximo@latest   # Linux/from source\n```\n\nOne-time host setup (CA, resolver, trust, and the stack — needs `sudo` once):\n\n```sh\nproximo install\n```\n\nLabel any container with the host you want, then bring it up:\n\n```yaml\n# docker-compose.yml\nservices:\n  whoami:\n    image: traefik/whoami\n    labels:\n      - \"proximo.hosts=whoami.test\"   # the port is auto-detected (single EXPOSE)\n```\n\n```sh\ndocker compose up -d\nopen https://whoami.test   # macOS — trusted HTTPS, no warning\nproximo status             # see what's routed\n```\n\nA ready-to-run sample is in [`examples/whoami/`](examples/whoami/). For the label\ncontract (multiple hosts, explicit port, opt-out, native Traefik labels) see\n[Routing](docs/routing.md).\n\n## Development\n\nNo local Go toolchain is required — every Make target runs Go inside the\n`golang` image (with a persistent module/build cache), so **Docker is the only\nprerequisite**:\n\n```sh\nmake build      # build bin/proximo-\u003cos\u003e-\u003carch\u003e for the host (Go runs in Docker)\nmake build-all  # cross-compile all targets (darwin,linux × amd64,arm64)\nmake test       # run the test suite (always Linux, in the golang image)\nmake vet        # go vet\nmake tidy       # go mod tidy\n```\n\nThe binary is named per OS/arch (`bin/proximo-darwin-arm64`,\n`bin/proximo-linux-amd64`, …) so a macOS and a Linux build never overwrite each\nother in a shared working tree. Override the host target with\n`make build GOOS=linux GOARCH=amd64`.\n\n### Running it via Make\n\nThe lifecycle targets build first (so the binary always matches the host) and\nrun the host binary, which talks to the host Docker socket:\n\n```sh\nmake install   # host setup (CA, resolver, trust) + start stack — asks for sudo\nmake up         # start the stack (no host changes)\nmake status     # list routed containers\nmake down        # stop the stack\nmake uninstall  # reverse host changes + tear down\nmake e2e         # install + start the whoami demo + open https://whoami.test\nmake e2e-down    # stop demo + uninstall\n```\n\n### Local testing without publishing\n\nThe stack's `dns` and `watcher` images are normally built with\n`go install github.com/filippolmt/proximo/cmd/...@\u003cref\u003e`, which needs the module\nto be published. The Make lifecycle targets above pass `PROXIMO_SRC=$(pwd)`\nautomatically, so those images build **from local source** (no push, no module\nfetch) via a generated `docker-compose.override.yml`. Run the binary directly\nwithout `PROXIMO_SRC` to use the published images instead.\n\n## License\n\n[MIT](LICENSE) — free to use, modify, and distribute.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffilippolmt%2Fproximo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffilippolmt%2Fproximo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffilippolmt%2Fproximo/lists"}