{"id":23497977,"url":"https://github.com/freedomben/dory","last_synced_at":"2025-04-04T15:07:03.393Z","repository":{"id":46318204,"uuid":"53391377","full_name":"FreedomBen/dory","owner":"FreedomBen","description":"Your development proxy for docker","archived":false,"fork":false,"pushed_at":"2023-12-30T20:36:13.000Z","size":257,"stargazers_count":158,"open_issues_count":18,"forks_count":23,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-28T14:06:26.746Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","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/FreedomBen.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}},"created_at":"2016-03-08T07:18:08.000Z","updated_at":"2025-02-14T03:20:05.000Z","dependencies_parsed_at":"2024-06-21T17:51:00.118Z","dependency_job_id":"48757ec1-e27b-4b92-8a60-85e0678ad673","html_url":"https://github.com/FreedomBen/dory","commit_stats":{"total_commits":218,"total_committers":16,"mean_commits":13.625,"dds":"0.25688073394495414","last_synced_commit":"87e29cd5821e92181350db43d750c75cde03c47d"},"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreedomBen%2Fdory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreedomBen%2Fdory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreedomBen%2Fdory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FreedomBen%2Fdory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FreedomBen","download_url":"https://codeload.github.com/FreedomBen/dory/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247198449,"owners_count":20900079,"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":[],"created_at":"2024-12-25T05:17:36.732Z","updated_at":"2025-04-04T15:07:03.370Z","avatar_url":"https://github.com/FreedomBen.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# dory\n\n[![Gem Version](https://badge.fury.io/rb/dory.svg)](https://badge.fury.io/rb/dory) [![Build Status](https://travis-ci.org/FreedomBen/dory.svg?branch=master)](https://travis-ci.org/FreedomBen/dory) [![Code Climate](https://codeclimate.com/github/FreedomBen/dory/badges/gpa.svg)](https://codeclimate.com/github/FreedomBen/dory) [![Test Coverage](https://codeclimate.com/github/FreedomBen/dory/badges/coverage.svg)](https://codeclimate.com/github/FreedomBen/dory/coverage) [![Dependency Status](https://dependencyci.com/github/FreedomBen/dory/badge)](https://dependencyci.com/github/FreedomBen/dory)\n\n[Dory](https://github.com/FreedomBen/dory) lets you forget about IP addresses and port numbers\nwhile you are developing your application.  Through the magic of local DNS and\na reverse proxy, you can access your app at the domain of your choosing.  For example,\nhttp://myapp.docker or http://this-is-a-really-long-name.but-its-cool-cause-i-like-it\n\nNow with support for Docker for Mac and even [dinghy! (more info on using with dinghy below)](#usage-with-dinghy)\n\nDory wraps [codekitchen/dinghy-http-proxy](https://github.com/codekitchen/dinghy-http-proxy)\nand makes it easily available for use outside of [dinghy](https://github.com/codekitchen/dinghy).\nThis way you can work comfortably side by side with your colleagues who run dinghy on macOS.\n\nSpecifically, dory will:\n\n* Fire up the nginx proxy in a daemonized docker container for you\n* Configure and start a local dnsmasq to forward DNS queries for\nyour local domain to the nginx proxy\n* Configure your local DNS resolver to point to the local dnsmasq\n\n## Installation\n\nA package for .deb and .rpm is planned as well as a systemd service.\nIf you'd like to help out with any of that, let me know!\n\n### [Homebrew](https://brew.sh) (recommended on macOS)\n\n```bash\nbrew install dory\n```\n\n### Ruby gem (recommended on Linux)\n\n**NOTE:** Dory requires ruby version 2.2 or greater to be installed on your system already.\n\nIf you use multiple versions, your system ruby is too old or you just prefer not to install gems into your system ruby, I recommend installing the ruby version with [ruby-install](https://github.com/postmodern/ruby-install) and then managing it with [chruby](https://github.com/postmodern/chruby).\n\n```bash\ngem install dory\n```\n\n### Arch Linux (hosted on the [quarry repository](https://wiki.archlinux.org/index.php/Unofficial_user_repositories#quarry))\n\n```bash\npacman -S ruby-dory\n```\n\n## Quick Start\n\nIn most cases, the default configuration will be all you need.  You literally\njust [set the VIRTUAL_HOST environment variable in your container](#making-your-containers-accessible-by-name-dns),\n[install dory](#installation) and then run:\n\n    dory up\n\nIf you want to fine-tune, generate a config file with:\n\n    dory config-file\n\nand edit away at `~/.dory.yml`\n\n## Usage\n\nDory has a small selection of commands that are hopefully intuitive.\nTo customize and fine-tune dory's behavior, it can be configured with a yaml config file.\n\n### Commands\n```\nCommands:\n  dory attach          # Attach to the output of a docker service container\n  dory config-file     # Write a default config file\n  dory down            # Stop all dory services\n  dory help [COMMAND]  # Describe available commands or one specific command\n  dory ip              # Grab the IPv4 address of a running dory service\n  dory pull            # Pull down the docker images that dory uses\n  dory restart         # Stop and restart all dory services\n  dory status          # Report status of the dory services\n  dory up              # Bring up dory services (nginx-proxy, dnsmasq, resolv)\n  dory upgrade         # Upgrade dory to the latest version\n  dory version         # Check current installed version of dory\n\nOptions:\n  v, [--verbose], [--no-verbose]\n```\n\n### Config file\n\nDory will start looking for a config file in your current working directory, and will recurse up to `/` until it finds one.  If dory does not find a config file, it will use the default settings.\n\nYou can bootstrap your config file with the default settings using `dory config-file`.  This\nfile will be placed by default at `~/.dory.yml`, but again you can move it to a preferred place.  This allows you to have project-specific dory configs if you so desire by putting the config at\n`\u003cyour-project\u003e/.dory.yml`:\n\n```yaml\n---\ndory:\n  # Be careful if you change the settings of some of\n  # these services.  They may not talk to each other\n  # if you change IP Addresses.\n  # For example, resolv expects a nameserver listening at\n  # the specified address.  dnsmasq normally does this,\n  # but if you disable dnsmasq, it\n  # will make your system look for a name server that\n  # doesn't exist.\n  dnsmasq:\n    enabled: true\n    domains:               # array of domains that will be resolved to the specified address\n      - domain: docker     # you can set '#' for a wildcard\n        address: 127.0.0.1 # return for queries against the domain\n    container_name: dory_dnsmasq\n    port: 53  # port to listen for dns requests on.  must be 53 on linux. can be anything that's open on macos\n    # kill_others: kill processes bound to the port we need (see previous setting 'port')\n    #   Possible values:\n    #     ask (prompt about killing each time. User can accept/reject)\n    #     yes|true (go ahead and kill without asking)\n    #     no|false (don't kill, and don't even ask)\n    kill_others: ask\n    service_start_delay: 5  # seconds to wait after restarting systemd services\n  nginx_proxy:\n    enabled: true\n    container_name: dory_dinghy_http_proxy\n    https_enabled: true\n    ssl_certs_dir: ''  # leave as empty string to use default certs\n    port: 80           # port 80 is default for http\n    tls_port: 443      # port 443 is default for https\n\n  resolv:\n    enabled: true\n    nameserver: 127.0.0.1\n    port: 53  # port where the nameserver listens. On linux it must be 53\n```\n\n#### Upgrading existing config file\n\nIf you run the `dory config-file` command and have an existing config file,\ndory will offer you the option of upgrading.  This will preserve your settings\nand migrate you to the latest format.  You can skip the prompt by passing the\n`--upgrade` flag\n\n```\ndory config-file --upgrade\n```\n\n```\nUsage:\n  dory config-file\n\nOptions:\n  u, [--upgrade], [--no-upgrade]\n  f, [--force]\n\nDescription:\n  Writes a dory config file to /home/ben/.dory.yml containing the default\n  settings. This can then be configured as preferred.\n```\n\n## Making your containers accessible by name (DNS)\n\nTo make your container(s) accessible through a domain, all you have to do is set\na `VIRTUAL_HOST` environment variable in your container.  That's it!  (Well, and you have\nto start dory with `dory up`)\n\nThe proxy will by default use the first port exposed by your container as the HTTP port to proxy to.\nThis can be overridden by setting the `VIRTUAL_PORT` environment variable on the container to the desired HTTP port.\n\nYou will also need to set `VIRTUAL_PORT` if your server binds to something other than 80\ninside its container (e.g. `VIRTUAL_PORT: 3000`).  This will tell the nginx proxy which\nport to forward traffic to in your container.  When accessing the server from outside\nof docker, you will still hit port 80 (such as with your web browser).\n\nIf your back-end container uses HTTPS, then set `VIRTUAL_PROTO: https` to tell the nginx\nproxy to use https instead of the default http.\n\nMany people do this in their `docker-compose.yml` file:\n\n```yaml\nversion: '2'\nservices:\n  web:\n    build: .\n    depends_on:\n      - db\n      - redis\n    environment:\n      VIRTUAL_HOST: myapp.docker\n  redis:\n    image: redis\n    environment:\n      VIRTUAL_HOST: redis.docker\n      VIRTUAL_PORT: 6379\n  db:\n    image: postgres\n    environment:\n      VIRTUAL_HOST: postgres.docker\n      VIRTUAL_PORT: 5432\n```\n\nIn the example above, you can hit the web container from the host machine with `http://myapp.docker`,\nand the redis container with `tcp://redis.docker`.  This does *not* affect any links on the internal docker network.\n\nYou could also just run a docker container with the environment variable like this:\n\n```\ndocker run -e VIRTUAL_HOST=myapp.docker  ...\n```\n\n## Usage with dinghy\n\nIf you are using dinghy, but want to use dory to manage the proxy instead of dinghy's built-in stuff,\nthis is now possible! (the use case for this that we ran into was multiple domain support.  For example,\nthe dev wanted to have some containers accessible at `something.docker`).  To accomplish this,\nyou need to disable dinghy's proxy stuff (otherwise dinghy and dory will stomp on each other's resolv files):\n\nIn your [`~/.dinghy/preferences.yml`](https://github.com/codekitchen/dinghy#preferences)\nfile, disable the proxy:\n\n```yaml\n:preferences:\n  :proxy_disabled: true\n  ...\n```\n\nIn your dory config file (which can be at `\u003cyour-project\u003e/.dory.yml` or anywhere else in parent directories,\n`~/.dory.yml` being the default) (hint: if it doesn't exist, [generate it with `dory config-file`](#config-file)),\nset your dnsmasq domains and their addresses to `dinghy`, as well as the resolv nameserver.  Here is\nan example (with unrelated parts removed for ease of reading):\n\n```yaml\n---\ndory:\n  dnsmasq:\n    domains:\n      - domain: docker\n        address: dinghy # instead of the default 127.0.0.1\n    ...\n  resolv:\n    nameserver: dinghy # instead of the default 127.0.0.1\n```\n\nIf the dinghy vm gets rebooted for some reason, or otherwise changes IP addresses,\nyou may need to restart dory to pickup the changes:\n\n```\ndory restart\n```\n\n## Root privilege requirement\n\nTo configure the local resolver, dory needs to edit the `/etc/resolv.conf`. Therefore\nyou may be prompted for your `sudo` password during `dory up/restart/down`.\nIf you do not want to enter your password every time you can extend the\n`sudoers` config as follows:\n\n```\nsudo visudo -f /etc/sudoers.d/dory-edit-resolv-conf\n```\n\nTo allow passwordless execution only for a single user (replace `my-user` accordingly):\n\n```\nCmnd_Alias DORY_EDIT_RESOLVCONF = /usr/bin/tee /etc/resolv.conf\nmy-user ALL=(root) NOPASSWD: DORY_EDIT_RESOLVCONF\n```\n\nTo allow passwordless execution for all users in group `sudo` (you can list the affected users with `awk -F':' '/sudo/{print $4}' /etc/group`):\n```\nCmnd_Alias DORY_EDIT_RESOLVCONF = /usr/bin/tee /etc/resolv.conf\n%sudo ALL=(root) NOPASSWD: DORY_EDIT_RESOLVCONF\n```\n\nOn OS X you probably need to change `%sudo` to `%admin`:\n```\nCmnd_Alias DORY_EDIT_RESOLVCONF = /usr/bin/tee /etc/resolv.conf\n%admin ALL=(root) NOPASSWD: DORY_EDIT_RESOLVCONF\n```\n\n*Note: Changes are only applied after closing the file.*\n\n\n## Troubleshooting\n\n*Help the dnsmasq container is having issues starting!*\n\nMake sure you aren't already running a dnsmasq service (or some other service) on port 53.\nBecause the Linux resolv file doesn't have support for port numbers, we have to run\non host port 53.  To make matters fun, some distros (such as those shipping with\n[NetworkManager](https://wiki.archlinux.org/index.php/NetworkManager)) will\nrun a dnsmasq on 53 to perform local DNS caching.  This is nice, but it will\nconflict with Dory's dnsmasq container.  You will probably want to disable it.\n\nIf using Network Manager, try commenting out `dns=dnsmasq`\nin `/etc/NetworkManager/NetworkManager.conf`.  Then restart\nNetworkManager:  `sudo service network-manager restart` or\n`sudo systemctl restart NetworkManager`\n\nIf you're using Network Manager/DNSMasqd to do NAT and/or share internet with the computer \nyou are installing dory on, stop. You'd need to configure dory's built in DNSmasq to do \nthe same, which is not trivial, out of scope, and probably more than you're bargaining for.\n\nIf you are on Mac, you can choose which port to bind the dnsmasq container to.  In your\ndory config file, adjust the setting under `dory -\u003e dnsmasq -\u003e port`.  You probably want\nto make `dory -\u003e resolv -\u003e port` match.  The default value on Mac is 19323.\n\nAs of version 0.5.0, dory is a little smarter at handling this problem for you.\ndory will identify if you have systemd services running that will race for the port\nand cause issues.  It will offer to put those services down temporarily and then put\nthem back up when finished.  You can configure this behavior in the [config file](#config-file)\nto achieve minimal annoyance (since you'll likely be prompted every time by default).\n\n## Is this dinghy for Linux?\n\nNo. Well, maybe sort of, but not really.  [Dinghy](https://github.com/codekitchen/dinghy)\nhas a lot of responsibilities on OS X, most of which are not necessary on Linux since\ndocker runs natively.  Something it does that can benefit linux users however, is the\nsetup and management of an [nginx reverse HTTP proxy](https://www.nginx.com/resources/admin-guide/reverse-proxy/).\nFor this reason, dory exists to provide this reverse proxy on Linux, along with\naccompanying dnsmasq and resolv services.\nUsing full dinghy on Linux for local development doesn't really make sense to me,\nbut using a reverse proxy does.  Furthermore, if you work with other devs who run\nDinghy on OS X, you will have to massage your [docker-compose](https://docs.docker.com/compose/)\nfiles to avoid conflicting.  By using  [dory](https://github.com/FreedomBen/dory),\nyou can safely use the same `VIRTUAL_HOST` setup without conflict.  And because\ndory uses [dinghy-http-proxy](https://github.com/codekitchen/dinghy-http-proxy)\nunder the hood, you will be as compatible as possible.\n\n## Are there any reasons to run full dinghy on Linux?\n\nGenerally speaking, IMHO, no.  The native experience is superior.  However, for\nsome reason maybe you'd prefer to not have docker on your local machine?\nMaybe you'd rather run it in a VM?  If that describes you, then maybe you want full dinghy.\n\nI am intrigued at the possibilities of using dinghy on Linux to drive a\ncloud-based docker engine.  For that, stay tuned.\n\n## Why didn't you just fork dinghy?\n\nThat was actually my first approach, and I considered it quite a bit.  As I\nwent through the process in my head tho, and reviewed the dinghy source code,\nI decided that it was just too heavy to really fit the need I had.  I love being\nable to run docker natively, and I revere\n[the Arch Way](https://wiki.archlinux.org/index.php/Arch_Linux#Principles).  Dinghy just\nseemed like too big of a hammer for this problem (the problem being that I work\non Linux, but my colleagues use OS X/Dinghy for docker development).\n\n## What if I'm developing on a cloud server?\n\nYou do this too!?  Well fine hacker, it's your lucky day because dory has you\ncovered.  You can run the nginx proxy on the cloud server and the dnsmasq/resolver\nlocally.  Here's how:\n\n* Install dory on both client and server:\n```\ngem install dory\n```\n* Gen a base config file:\n```\ndory config-file\n```\n* On the local machine, disable the nginx-proxy, and set the dnsmasq address to that of your cloud server:\n```yaml\n  dnsmasq:\n    enabled: true\n    domain: docker      # domain that will be listened for\n    address: \u003ccloud-server-ip\u003e  # address returned for queries against domain\n    container_name: dory_dnsmasq\n  nginx_proxy:\n    enabled: false\n    container_name: dory_dinghy_http_proxy\n```\n* On the server, disable resolv and dnsmasq:\n```yaml\n  dnsmasq:\n    enabled: false\n    domain: docker      # domain that will be listened for\n    address: 127.0.0.1  # address returned for queries against domain\n    container_name: dory_dnsmasq\n  resolv:\n    enabled: false\n    nameserver: 127.0.0.1\n```\n* Profit!\n\n## Contributing\n\nWant to contribute?  Cool!  Fork it, push it, request it.  Please try to write tests for any functionality you add.\n\n## Development Quick Start\n\n1.  If you want to send a pull request with your changes, then fork the repo\n1.  Clone it:  `git clone https://github.com/FreedomBen/dory.git` or if you forked in step 1, use the URL for your fork\n1.  Make your changes\n1.  Build the gem locally:  `gem build dory.gemspec`\n1.  Now you can run your locally built version of the gem like normal:  `dory \u003csomecommand\u003e`\n1.  Rinse and repeat.  For easy cleaning and reinstalling, I recommend using this command, which you might want to alias:  `rm *.gem; gem clean dory; yes | gem uninstall dory; gem build dory.gemspec \u0026\u0026 gem install dory*.gem`\n1.  Run the specs locally (note that I've attempted to make the specs interfere with the running system as minimally as possible, but some things are difficult to avoid.  For example, if you have something running on port 53, the specs will kill it.  Also, you will need to enter password for sudo):  `bundle exec rspec spec/`\n1.  Specific specs can be run with:  `bundle exec rspec spec/some/file.rb`\n\n## Built on:\n\n* [jwilder/nginx-proxy](https://github.com/jwilder/nginx-proxy) (Indirectly but worthy of mention)\n* [codekitchen/dinghy-http-proxy](https://github.com/codekitchen/dinghy-http-proxy)\n* [freedomben/dory-http-proxy](https://github.com/freedomben/dory-http-proxy)\n* [andyshinn/dnsmasq](https://hub.docker.com/r/andyshinn/dnsmasq/)\n* [freedomben/dory-dnsmasq](https://github.com/FreedomBen/dory-dnsmasq)\n* [erikhuda/thor](https://github.com/erikhuda/thor)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreedomben%2Fdory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffreedomben%2Fdory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreedomben%2Fdory/lists"}