{"id":13414129,"url":"https://github.com/cristianoliveira/ergo","last_synced_at":"2025-04-12T19:46:01.476Z","repository":{"id":24185194,"uuid":"100814404","full_name":"cristianoliveira/ergo","owner":"cristianoliveira","description":"The management of multiple apps running over different ports made easy","archived":false,"fork":false,"pushed_at":"2024-07-11T14:04:30.000Z","size":3813,"stargazers_count":619,"open_issues_count":7,"forks_count":59,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-07-31T20:53:33.447Z","etag":null,"topics":["developer-tools","development","development-environment","distributed-systems","ergo","golang","linux","microservices","osx","proxy","proxy-server","reverse-proxy","tools","web-proxy","windows"],"latest_commit_sha":null,"homepage":"","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/cristianoliveira.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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}},"created_at":"2017-08-19T18:41:56.000Z","updated_at":"2024-07-20T08:49:16.000Z","dependencies_parsed_at":"2022-07-27T04:32:24.740Z","dependency_job_id":"e2a21b6f-fe00-451a-b3da-941be714fd3d","html_url":"https://github.com/cristianoliveira/ergo","commit_stats":{"total_commits":216,"total_committers":21,"mean_commits":"10.285714285714286","dds":0.5648148148148149,"last_synced_commit":"5f1ccf2225cb15adb4c458021bfd76c0bc0f34f9"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cristianoliveira%2Fergo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cristianoliveira%2Fergo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cristianoliveira%2Fergo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cristianoliveira%2Fergo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cristianoliveira","download_url":"https://codeload.github.com/cristianoliveira/ergo/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248625491,"owners_count":21135513,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["developer-tools","development","development-environment","distributed-systems","ergo","golang","linux","microservices","osx","proxy","proxy-server","reverse-proxy","tools","web-proxy","windows"],"created_at":"2024-07-30T20:01:58.481Z","updated_at":"2025-04-12T19:46:01.454Z","avatar_url":"https://github.com/cristianoliveira.png","language":"Go","funding_links":[],"categories":["Workflow","Utilities","工具库","Go","公用事业公司","Utility","实用工具","工具库`可以提升效率的通用代码库和工具`"],"sub_categories":["Visual Studio Code","Utility/Miscellaneous","交流","实用程序/Miscellaneous","HTTP Clients","\u003cspan id=\"高级控制台用户界面-advanced-console-uis\"\u003e高级控制台用户界面 Advanced Console UIs\u003c/span\u003e","查询语","Fail injection","Advanced Console UIs"],"readme":"\n# Ergo [![GoDoc](https://godoc.org/github.com/cristianoliveira/ergo?status.svg)](https://godoc.org/github.com/cristianoliveira/ergo) [![Go Report Card](https://goreportcard.com/badge/github.com/cristianoliveira/ergo)](https://goreportcard.com/report/github.com/cristianoliveira/ergo) [![unix](https://github.com/cristianoliveira/ergo/actions/workflows/on-push.yml/badge.svg)](https://github.com/cristianoliveira/ergo/actions/workflows/on-push.yml) [![win build](https://img.shields.io/appveyor/ci/cristianoliveira/ergo.svg?label=win)](https://ci.appveyor.com/project/cristianoliveira/ergo) [![codecov](https://codecov.io/gh/cristianoliveira/ergo/branch/master/graph/badge.svg)](https://codecov.io/gh/cristianoliveira/ergo)\n\n\u003cp align=\"left\" \u003e\n\u003cimg src=\"https://s-media-cache-ak0.pinimg.com/736x/aa/bc/3b/aabc3b2b789f478ffb87ac2f0bdd2d33--ergo-proxy-manga-anime.jpg\" width=\"250\" align=\"center\" /\u003e\n\u003cspan\u003eErgo Proxy - The reverse proxy agent for local domain management.\u003c/span\u003e\n\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  The management of multiple apps running over different ports made easy through custom local domains.\n\u003c/p\u003e\n\n## Demo\n\n\u003cimg src=\"https://raw.githubusercontent.com/cristianoliveira/ergo/master/demo.gif\" align=\"center\" /\u003e\n\nSee more on [examples](https://github.com/cristianoliveira/ergo/tree/master/examples)\n\n## TL;DR;\n```bash\npython3 -m http.server 8800 \u0026 # launch a web server listening on 8800\necho \"http://localhost:8800 mylocalsite\" \u003e .ergo # adds a service \"mylocalsite\" to ergo\nergo local \u0026 # it may need sudo since it binds to port 80\ncurl http://mylocalsite.localhost # make a HTTP request to the ergo service :)\n```\n\n## Summary\n* [Philosophy](#philosophy)\n* [Installation](#installation)\n  - [osx](#osx)\n  - [linux](#linux)\n  - [windows](#windows)\n  - [nix](#nix)\n  - [from source](#go)\n* [Usage](#usage)\n* [Configuration](#configuration)\n* [Testing](#run-tests)\n* [Contributing](#contributing)\n\n### Philosophy\n\nErgo's goal is to be a simple reverse proxy that follows the [Unix philosophy](https://en.wikipedia.org/wiki/Unix_philosophy) of doing only one thing and doing it well. Simplicity means no magic involved. Just a flexible reverse proxy which extends the well-known `/etc/hosts` declaration.\n\n**Feedback**\n\nThis project is constantly undergoing development, however, it's ready to use. Feel free to provide\nfeedback as well as open issues. All suggestions and contributions are welcome. :)\n\nFor help and feedback you can find us at #ergo-proxy channel on https://gopher.slack.com\n\n## Why?\n\nDealing with multiple apps locally, and having to remember each port representing each microservice is frustrating. I wanted a simple way to assign each service a proper local domain. Ergo solves this problem.\n\n## Installation\n\n**Important** These are the only official ways to install ergo.\n\n### OSX\n```\nbrew tap cristianoliveira/tap\nbrew install ergo\n```\n\n### Linux\nTo install the latest official version\n```\ncurl -s https://raw.githubusercontent.com/cristianoliveira/ergo/master/install.sh | sh\n```\n\nOr to install a specific version\n```\ncurl -s https://raw.githubusercontent.com/cristianoliveira/ergo/master/install.sh v0.2.5 | sh\n```\n\n### Windows\n\nFrom powershell run:\n\n```\nInvoke-WebRequest https://raw.githubusercontent.com/cristianoliveira/ergo/master/install.ps1 -out ./install.ps1; ./install.ps1\n```\n\n_You can also find the Windows executables in [release](https://github.com/cristianoliveira/ergo/releases)._\n\n***Disclaimer:***\nI use Unix-based systems on a daily basis, so I am not able to test each build alone. :(\n\n### Nix\n\n```bash\nnix profile install 'github:cristianoliveira/ergo'\n```\nMore examples see: https://github.com/cristianoliveira/nixpkgs\n\n### Go\n```\ngo install github.com/cristianoliveira/ergo\n```\nMake sure you have `$GOPATH/bin` in your path: `export PATH=$PATH:$GOPATH/bin`\n\n## Usage\n\nErgo looks for a `.ergo` file inside the current directory. It must contain the names and URL of the services following the same format as `/etc/hosts` (`domain`+`space`+`url`). The main difference is it also considers the specified port.\n\n### Subdomains for localhost\n \nRun `ergo local` it'll attempt to bind to `localhost:80` and listen for requests to your services as \"subdmains\" eg. `http://serviceone.localhost` and `http://servicetwo.localhost`. (Check [examples](https://github.com/cristianoliveira/ergo/tree/master/examples) for more)\n\n**Note:** It __may__ requires sudo to bind to port 80.\n\nYou can give it a different port by `ergo local -p \u003cport\u003e` and access it through `http://serviceone.localhost:\u003cport\u003e`.\n\nYou can also add a different loopback in `/etc/hosts` like `echo '127.0.0.1 localapp' \u003e\u003e /etc/hosts` and run `ergo local -domain localapp` to access your services through `http://serviceone.localapp` and `http://servicetwo.localapp`.\n\n### Setting up as a webproxy\n\n**You need to set the `http://127.0.0.1:2000/proxy.pac` configuration on your system network config.**\n\nErgo comes with a setup command that can configure it for you. The current systems supported are:\n\n - osx\n - linux-gnome\n - windows\n\n```bash\nergo setup \u003coperation-system\u003e\n```\n\nIn case of errors / it doesn't work, please look at the detailed config session below.\n\n### Adding Services and Running\n\n#### OS X / Linux\n```\necho \"ergoproxy http://localhost:3000\" \u003e .ergo\nergo run\n```\n\nNow you should be able to access: `http://ergoproxy.dev`.\nErgo redirects anything ending with `.dev` to the configured URL.\n\n#### Windows\nYou should not use the default `.dev` domain, we suggest `.test` instead (see [#58](https://github.com/cristianoliveira/ergo/issues/58)) unless your service supports https out of the box and you have already a certificate\n```\nset ERGO_DOMAIN=.test\necho \"ergoproxy  http://localhost:3000\" \u003e .ergo\nergo list # you shouldn't see any quotas in the output\nergo run\n```\nNow you should be able to access: `http://ergoproxy.test`.\nErgo redirects anything ending with `.test` to the configured URL.\n\nSimple, right? No magic involved.\n\nDo you want to add more services? It's easy, just add more lines in `.ergo`:\n```\necho \"otherservice http://localhost:5000\" \u003e\u003e .ergo\nergo list\nergo run\n```\n\nRestart the ergo server and access: `http://otherservice.dev`\n\n`ergo add otherservice http://localhost:5000` is a shorthand for appending lines to `./.ergo`\n\n### Ergo's configuration\n\nErgo accepts different configurations like run in different `port` (default: 2000) and change `domain` (default: dev). You can find all this configs on ergo's help running `ergo -h`.\n\n## Configuration\n\nIn order to use Ergo domains you need to set it as a proxy. Set the `http://127.0.0.1:2000/proxy.pac` on:\n\n### Networking Web Proxy\n\n#### OS X\n\n`Network Preferences \u003e Advanced \u003e Proxies \u003e Automatic Proxy Configuration`\n\n#### Windows\n\n`Settings \u003e Network and Internet \u003e Proxy \u003e Use setup script`\n\n#### Linux\n\nOn Ubuntu\n\n`System Settings \u003e Network \u003e Network Proxy \u003e Automatic`\n\nFor other distributions, check your network manager and look for proxy configuration. Use browser configuration as an alternative.\n\n### Browser configuration\n\nBrowsers can be configured to use a specific proxy. Use this method as an alternative to system-wide configuration.\n\nKeep in mind that if you requested the site before setting the proxy properly, you have to reset the cache of the browser or change the name of the service. In `incognito` windows cache is disabled by default, so you can use them if you don't wish to delete the cache\n\nAlso you should not use the default `.dev` domain, we suggest `.test` instead (see [#58](https://github.com/cristianoliveira/ergo/issues/58)) unless your service supports https out of the box and you have already a certificate\n\n#### Chrome\n\nExit Chrome and start it using the following option:\n\n```sh\n# Linux\n$ google-chrome --proxy-pac-url=http://localhost:2000/proxy.pac\n\n# OS X\n$ open -a \"Google Chrome\" --args --proxy-pac-url=http://localhost:2000/proxy.pac\n```\n\n#### Firefox\n\n##### through menus and mouse\n1. Click the hamburger button otherwise click on \"Edit\" Menu\n1. then \"Preferences\"\n1. then \"Settings\" button at the bottom of the page (\"General\" active in sidebar) with title \"Network Settings\"\n1. check `Automatic Proxy configuration URL` and enter value `http://localhost:2000/proxy.pac` below\n1. hit \"ok\"\n\n\n##### from about:config\n`network.proxy.autoconfig_url` -\u003e `http://localhost:2000/proxy.pac`\n\n\n### Using on terminal\n\nIn order to use ergo as your web proxy on terminal you must set the `http_proxy` variable. (Only for linux/osx)\n\n```sh\nexport http_proxy=\"http://localhost:2000\"\n```\n\n### Ephemeral Setup\n\nAs an alternative you can see the scripts inside `/resources` for running an\nephemeral setup. Those scripts set the proxy only while `ergo` is running.\n\n## Contributing\n - Fork it!\n - Create your feature branch: `git checkout -b my-new-feature`\n - Commit your changes: `git commit -am 'Add some feature'`\n - Push to the branch: `git push origin my-new-feature`\n - Submit a pull request, they are welcome!\n - Please include unit tests in your pull requests\n\n## Development\n\nMinimal required golang version `go1.22`.\nWe recommend using [GVM](https://github.com/moovweb/gvm) for managing\nyour go versions.\n\nThen simply run:\n```sh\ngvm use $(cat .gvmrc)\n```\n\n### Building\n\n```sh\n  make all\n```\n\n## Testing\n\n  ```sh\n  make test\n  make test-integration # Requires admin permission so use it carefully.\n```\n\n# License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcristianoliveira%2Fergo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcristianoliveira%2Fergo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcristianoliveira%2Fergo/lists"}