{"id":20301934,"url":"https://github.com/medic/nginx-local-ip","last_synced_at":"2025-04-11T13:36:52.898Z","repository":{"id":43733204,"uuid":"348697465","full_name":"medic/nginx-local-ip","owner":"medic","description":"HTTPS Nginx reverse-proxy: public URLs to expose your local webapp in your LAN","archived":false,"fork":false,"pushed_at":"2023-05-15T16:16:28.000Z","size":186,"stargazers_count":21,"open_issues_count":5,"forks_count":8,"subscribers_count":28,"default_branch":"main","last_synced_at":"2025-03-25T09:49:28.301Z","etag":null,"topics":["docker","https","nginx-proxy","reverse-proxy"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/medic.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":"2021-03-17T12:15:11.000Z","updated_at":"2024-10-21T14:46:34.000Z","dependencies_parsed_at":"2024-11-14T16:34:07.096Z","dependency_job_id":"bab00d1a-063f-4387-86c6-2e420c06e332","html_url":"https://github.com/medic/nginx-local-ip","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medic%2Fnginx-local-ip","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medic%2Fnginx-local-ip/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medic%2Fnginx-local-ip/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/medic%2Fnginx-local-ip/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/medic","download_url":"https://codeload.github.com/medic/nginx-local-ip/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248410213,"owners_count":21098772,"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":["docker","https","nginx-proxy","reverse-proxy"],"created_at":"2024-11-14T16:28:28.089Z","updated_at":"2025-04-11T13:36:52.858Z","avatar_url":"https://github.com/medic.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"local-ip.medicmobile.org HTTPS reverse-proxy\n===============================\n\n\u003e 🚀 Public URLs to expose your local webapp without\n\u003e    external proxies in your LAN\n\nSet of Nginx and Docker configurations to launch a Nginx reverse proxy\nrunning in the HTTPS port (443), using a public SSL certificate for\ndomains `*.local-ip.medicmobile.org`. The SSL certificate is signed by a CA authority\nand provided for free by [local-ip.medicmobile.org](https://local-ip.medicmobile.org/). Moreover,\nthey have a free DNS service that provides wildcard DNS for any IP\naddress, including private IPs:\n\n    $ dig 10-0-0-1.local-ip.medicmobile.org +short\n    10.0.0.1\n\nSo having a public certificate and a public DNS that resolves to your\nlocal IP address, you can launch the HTTPS server to proxy\nyour local app built with whatever stack, and connect any browser,\napp or device that requires to access it with HTTPS like the Android\napps, that some times don't work without a secure connection.\n\n\nRun\n---\n\nEg. if your webapp runs locally in the port 5988, and your\nlocal IP is 192.168.0.3, you normally access the app\nwith `http://192.168.0.3:5988` in the same device or any other\ndevice within the same network, but you can access your app with\nthe URL https://192-168-0-3.local-ip.medicmobile.org launching the Docker\nconfiguration in the same machine as follows:\n\nOnly the first time:\n\n    $ git clone https://github.com/medic/nginx-local-ip.git\n\nThen:\n\n    $ cd nginx-local-ip/\n    $ APP_URL=http://192.168.0.3:5988 docker compose up\n\nNote that the IP set in the `APP_URL` environment variable is passed\nas it is in your computer, but the URL to access the app in the devices\nseparates each number from the IP address by `-`\n(isn't `.`): https://192-168-0-3.local-ip.medicmobile.org .\n\nAnyway, you will see the final URL logged in the console when the\ncontainer is launched:\n\n![nginx-local-ip startup](docs/img/nginx-local-ip-startup.png)\n\nAlso note that you cannot use the localhost IP 127.0.0.1, it needs to\nbe the IP of your WiFi connection, Ethernet connection, or whatever\nconnection your computer has with the network is connected to. You\ncan get your IP address in a Unix system with `ifconfig` or `ip addr`.\nYour computer may also have other virtual interfaces with IP addresses\nassigned, omit them, like the IP of the _docker0_ interface.\n\n\u003e :signal_strength: **Tip**: if your IP is defined dynamically, try with `ip addr show dynamic`.\n\nThe server also opens the port 80 so if you forget to write the URL\nwith https:// , Nginx redirects the request to the HTTPS version\nfor you 😉.\n\n#### Firewall\n\nThe HTTP/HTTPS ports (`80`/`443`) need to accept traffic from the IP address of your host machine and your local webapp port (e.g. `5988`) needs to accept traffic from the IP address of the `nginx-local-ip` container (on the Docker network). If you are using the UFW firewall (in a Linux environment) you can allow traffic on these ports with the following commands:\n\n\u003e Since local IP addresses can change over time, ranges are used in these rules so that the firewall configuration does not have to be updated each time a new address is assigned.\n\n```.sh\n$ sudo ufw allow proto tcp from 192.168.0.0/16 to any port 80,443\n$ sudo ufw allow proto tcp from  172.16.0.0/16 to any port 5988\n```\n\n#### Docker note\nA local image is created the first time executed, and there is no need to rebuild it if you change the Nginx configuration or the `entrypoint.sh` file. Only changes to the Dockerfile script require a rebuild. If you just edit the Nginx configuration, or want to change the ports mapped, only restart the container is needed. \n\nIf you do need to rebuild the container, append `--build` on to your compose call: ` docker compose up --build`.\n\n### Public SSL certificate\n\nThe certs are downloaded and cached from [local-ip.medicmobile.org](https://local-ip.medicmobile.org/) on first run. On subsequent runs, the `entrypoint.sh` script checks locally whether they are expired and downloads renewed certs from  [local-ip.medicmobile.org](https://local-ip.medicmobile.org/) if needed.\n\n### Running with Medic-OS \n\n#### Change Ports\n\nThe default ports used in `nginx-local-ip` might conflict with the standard web server ports of \nthat the `medic-os` docker image uses to run, `80` and `443`. To fix this, specify `nginx-local-ip` \nto use the `medic-os.env` file. Using the included `env-file` the container will avoid `80` and `443` \nand use `8080` and `444` for http and https respectively. Your instance will be available \nat `https://192-168-0-3.local-ip.medicmobile.org:444/`\n\nCommand to run:\n\n    APP_URL=https://192.168.0.3 docker compose --env-file=medic-os.env up\n    \n#### Install Certs\n    \nTo avoid running the `nginx-local-ip` container all together, consider adding the `local-ip` certs directly to your `medic-os` container.  This simplifies your development environment by having one less docker image.  First [download the certs](https://local-ip.medicmobile.org) then follow [the steps already published in self hosting](https://docs.communityhealthtoolkit.org/apps/guides/hosting/ssl-cert-install/) on how to install the certs.\n\nIf the IP of your local machine is `192.168.0.3`, you could then access your instance directly at `https://192-168-0-3.local-ip.medicmobile.org/` after adding the certs. This way there is no `nginx-local-ip` container as a reverse proxy because `medic-os` hosts the certs internally.\n\n**NOTE** - You will have to manually refresh the `local-ip`  certificates if you use this approach.\n\n\nRequirements\n------------\n\nOnly **Docker** and **Docker compose** installed are needed, and despite\nthis setup helps you to connect your devices with your webapp using\na local connection (without complex reverse proxy connections through\nInternet like _Ngrok.com_), the devices that want to connect with the app\nstill need access to Internet just to resolve the `*.local-ip.medicmobile.org` domain\nagainst the `local-ip.medicmobile.org` public DNS, unless you configure your own DNS server\nwithin your network, which needs to be configured in all the devices were you\nare going to use the app. In that case, no Internet connection will be required,\njust a LAN connection.\n\n\nCertificate \u0026 DNSs providers\n---------\n\nBy default, this service works with `local-ip.medibmobile.org` (which in turn uses [localtls](https://github.com/Corollarium/localtls/)), but it can be configured to work with any provider that offers:\n* publicly downloadable TLS certificates via `curl`\n* DNS resolution based off IP-in-URL\n\nFor example, if you wanted to use `local-ip.co` (though use [with caution](https://github.com/medic/cht-core/issues/8100)), you would set these four environment variables for you Docker Compose call:\n\n* `CERT_PEM_SRC` set to to `http://local-ip.co/cert/server.pem`\n* `CERT_CHAIN_SRC` set to `http://local-ip.co/cert/chain.pem`\n* `CERT_KEY_SRC`  set to `http://local-ip.co/cert/server.key`\n* `DOMAIN` set to `my.local-ip.co`\n\nUsing inline variables, this would look like:\n\n```shell\nCERT_PEM_SRC=http://local-ip.co/cert/server.pem \\\nCERT_CHAIN_SRC=http://local-ip.co/cert/chain.pem \\\nCERT_KEY_SRC=http://local-ip.co/cert/server.key \\\nDOMAIN=my.local-ip.co \\\ndocker compose up \n```\n\nTroubleshooting\n---------\n\n### Port Conflicts\n\nIf you run `docker compose` and you get a `address already in use` error like this:\n\n```\nERROR: for nginx-local-ip_app_1  Cannot start service app: driver failed programming external connectivity on endpoint nginx-local-ip_app_1 (5a31171148dcaa58b4053f793288aaa940f5678043d302c1c1ad87\n5cdae3a684): Error starting userland proxy: listen tcp4 0.0.0.0:443: bind: address already in use\n```                                                                                          \n\nYou may need to change one or both ports. For example, you could shift them\nup to 8xxx like so:\n\n    $ HTTP=8080 HTTPS=8443 APP_URL=http://192.168.1.3:5988 docker compose up\n\nAlso, a convenient environment file can be used to store the new values as\nsuggested in the [Running with Medic-OS](#running-with-medic-os) section:\n\n**my.env file:**\n\n    HTTP=8080\n    HTTPS=8443\n\nRun with: `APP_URL=https://192.168.1.3:5988 docker compose --env-file=my.env up`\n\nYou would then access your dev instance with the `8443` port.\nUsing the sample URL from above, it would go from `https://192-168-0-3.local-ip.medicmobile.org`\nto this instead `https://192-168-0-3.local-ip.medicmobile.org:8443`.\n\n\nCopyright\n---------\n\nCopyright 2021 Medic Mobile, Inc. \u003chello@medic.org\u003e.\n\nThe SSL certificate files are downloaded from Internet at runtime,\nand are property of **local-ip.medicmobile.org**.\n\n\nLicense\n-------\n\nThe software is provided under AGPL-3.0. Contributions to this project\nare accepted under the same license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmedic%2Fnginx-local-ip","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmedic%2Fnginx-local-ip","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmedic%2Fnginx-local-ip/lists"}