{"id":22885346,"url":"https://github.com/oeo/localroute","last_synced_at":"2026-02-02T07:09:02.444Z","repository":{"id":266827672,"uuid":"899476486","full_name":"oeo/localroute","owner":"oeo","description":"🌐 local dns and reverse proxy with automatic https for your homelab.","archived":false,"fork":false,"pushed_at":"2024-12-06T12:12:14.000Z","size":67,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-08T21:29:40.420Z","etag":null,"topics":["dnsmasq","docker","homelab","mkcert","nginx","proxmox","reverse-proxy"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/oeo.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2024-12-06T10:47:19.000Z","updated_at":"2024-12-15T03:39:22.000Z","dependencies_parsed_at":"2024-12-10T19:39:57.846Z","dependency_job_id":null,"html_url":"https://github.com/oeo/localroute","commit_stats":null,"previous_names":["oeo/localroute"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oeo%2Flocalroute","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oeo%2Flocalroute/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oeo%2Flocalroute/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/oeo%2Flocalroute/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/oeo","download_url":"https://codeload.github.com/oeo/localroute/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253153076,"owners_count":21862308,"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":["dnsmasq","docker","homelab","mkcert","nginx","proxmox","reverse-proxy"],"created_at":"2024-12-13T19:35:37.862Z","updated_at":"2026-02-02T07:09:02.401Z","avatar_url":"https://github.com/oeo.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# localroute \n\na local dns and routing solution using dnsmasq and nginx in docker. this project allows you to:\n\n- handle local dns resolution with dnsmasq\n- route traffic using nginx as a reverse proxy\n- support both http and https with automatic certificate generation\n- run everything in containers for portability\n\n## prerequisites\n- `docker`\n- `docker-compose`\n- `node.js` (for configuration scripts)\n  - no dependencies, just used to parse `sites.conf.json`\n- `mkcert` (optional, for trusted certificates)\n\n## installation\n1. clone this repository\n2. copy the example config:\n   ```bash\n   cp sites.conf.json.example sites.conf.json\n   ```\n3. edit `sites.conf.json` to define your sites:\n   ```json\n   {\n     \"sites\": [\n       {\n         \"force_ssl\": false,\n         \"force_dns\": true,\n         \"network_domain\": \"example.local\",\n         \"real_host\": \"http://192.168.1.100:8080\"\n       },\n       {\n         \"force_ssl\": true,\n         \"force_dns\": true,\n         \"network_domain\": \"librechat.local\",\n         \"real_host\": \"http://192.168.1.167:3006\"\n       }\n     ]\n   }\n   ```\n4. install mkcert (optional, for trusted certificates):\n   ```bash\n   # macos\n   brew install mkcert\n   \n   # ubuntu/debian\n   apt install mkcert\n   \n   # arch\n   pacman -S mkcert\n   ```\n\n## usage\n\n### first time setup\n```bash\nchmod +x reload.js\n./reload.js\n```\n\n### reloading configuration\nwhenever you change `sites.conf.json`, just run:\n```bash\n./reload.js\n```\n\nthis will:\n- validate your configuration\n- generate nginx and dnsmasq configs\n- create ssl certificates if needed\n- restart the services\n- test the configuration\n\n### configuring network-wide dns\nto use localroute as your network's dns server (like pihole):\n\n#### unifi\n1. login to your unifi controller\n2. go to settings \u003e networks\n3. select your network\n4. expand 'dhcp and dns'\n5. set 'dns server 1' to 192.168.1.201\n6. click 'apply changes'\n\n#### openwrt\n1. login to luci interface\n2. go to network \u003e dhcp/dns\n3. set 'dns forwardings' to 192.168.1.201\n4. restart dnsmasq service or reboot router\n\n#### pfsense\n1. login to web interface\n2. go to services \u003e dhcp server\n3. select your lan interface\n4. set 'dns servers' to 192.168.1.201\n5. click 'save'\n6. go to system \u003e general setup\n7. set 'dns servers' to 192.168.1.201 (to use it for the router itself)\n8. click 'save'\n\n#### mikrotik\n1. login to winbox/webfig\n2. go to ip \u003e dhcp server\n3. select your dhcp server\n4. set 'dns servers' to 192.168.1.201\n5. click 'apply'\n\n#### generic router\n1. login to your router's admin interface\n2. look for dhcp/dns settings (usually under lan/network settings)\n3. set primary dns server to 192.168.1.201\n4. save changes and restart if needed\n\n#### synology\n1. login to dsm\n2. open control panel\n3. go to network \u003e general\n4. set primary dns to 192.168.1.201\n5. click 'apply'\n\n#### truenas\n1. login to web interface\n2. go to network \u003e global configuration\n3. set nameserver 1 to 192.168.1.201\n4. click 'save'\n\nnote: after changing network-wide dns:\n- some devices may need to renew their dhcp lease\n- you can force this by disconnecting/reconnecting to the network\n- or by running `ipconfig /release \u0026\u0026 ipconfig /renew` on windows\n- or `sudo dhclient -r \u0026\u0026 sudo dhclient` on linux\n\n### configuring clients to use your dns server\nto use your localroute server (assuming it's running at 192.168.1.201):\n\n#### linux (networkmanager)\n1. gui method:\n   - open network settings\n   - select your network connection\n   - click the gear icon to edit\n   - go to the 'ipv4' tab\n   - change dns method to 'manual'\n   - add 192.168.1.201 as your dns server\n   - click 'apply'\n\n2. command line method:\n   ```bash\n   # edit your connection (replace 'Wired connection 1' with your connection name)\n   nmcli con mod \"Wired connection 1\" ipv4.dns \"192.168.1.201\"\n   nmcli con mod \"Wired connection 1\" ipv4.ignore-auto-dns yes\n   \n   # restart the connection\n   nmcli con down \"Wired connection 1\"\n   nmcli con up \"Wired connection 1\"\n   ```\n\n#### linux (systemd-resolved)\n```bash\n# edit /etc/systemd/resolved.conf\nsudo tee /etc/systemd/resolved.conf \u003c\u003c EOF\n[Resolve]\nDNS=192.168.1.201\nEOF\n\n# restart systemd-resolved\nsudo systemctl restart systemd-resolved\n```\n\n#### macos\n1. gui method:\n   - open system preferences\n   - click on network\n   - select your active network connection\n   - click 'advanced'\n   - go to the 'dns' tab\n   - click '+' and add 192.168.1.201\n   - click 'ok' and then 'apply'\n\n2. command line method:\n   ```bash\n   # get your network service (usually 'Wi-Fi' or 'Ethernet')\n   networksetup -listallnetworkservices\n   \n   # set dns server (replace 'Wi-Fi' with your service name)\n   sudo networksetup -setdnsservers \"Wi-Fi\" 192.168.1.201\n   ```\n\n#### windows\n1. gui method:\n   - open network \u0026 internet settings\n   - click 'change adapter options'\n   - right-click your connection and select 'properties'\n   - select 'internet protocol version 4 (tcp/ipv4)'\n   - click 'properties'\n   - select 'use the following dns server addresses'\n   - enter 192.168.1.201 as preferred dns server\n   - click 'ok'\n\n2. powershell method (run as administrator):\n   ```powershell\n   # get your network adapter name\n   Get-NetAdapter\n   \n   # set dns server (replace 'Ethernet' with your adapter name)\n   Set-DnsClientServerAddress -InterfaceAlias \"Ethernet\" -ServerAddresses \"192.168.1.201\"\n   ```\n\n### verifying dns setup\nto verify your dns is working:\n```bash\n# test dns resolution\nping example.local\nping librechat.local\n\n# check which dns server is being used\nnslookup example.local\n```\n\n### stopping services\n```bash\ndocker-compose down\n```\n\n### viewing logs\n```bash\ndocker-compose logs -f\n```\n\n### restoring original dns\nif you want to stop using localroute's dns:\n\n#### linux (networkmanager)\n```bash\n# reset to automatic dns (replace 'Wired connection 1' with your connection name)\nnmcli con mod \"Wired connection 1\" ipv4.dns \"\"\nnmcli con mod \"Wired connection 1\" ipv4.ignore-auto-dns no\nnmcli con down \"Wired connection 1\"\nnmcli con up \"Wired connection 1\"\n```\n\n#### linux (systemd-resolved)\n```bash\n# restore default resolved.conf\nsudo rm /etc/systemd/resolved.conf\nsudo systemctl restart systemd-resolved\n```\n\n#### macos\n```bash\n# reset to automatic dns (replace 'Wi-Fi' with your service name)\nsudo networksetup -setdnsservers \"Wi-Fi\" \"empty\"\n```\n\n#### windows (powershell as administrator)\n```powershell\n# reset to automatic dns (replace 'Ethernet' with your adapter name)\nSet-DnsClientServerAddress -InterfaceAlias \"Ethernet\" -ResetServerAddresses\n```\n\n## configuration\nedit `sites.conf.json` to define your domains and upstream servers. each site can have:\n\n- `force_ssl`: enable https and redirect http to https\n- `force_dns`: add dns record to dnsmasq\n- `network_domain`: the domain name to use (e.g. example.local)\n- `real_host`: the upstream server to proxy to (e.g. http://192.168.1.100:8080)\n\n## ssl certificates\nthe project supports two methods for ssl:\n\n1. `mkcert` (recommended):\n   - generates locally-trusted certificates\n   - no browser warnings\n   - certificates are automatically trusted\n   - requires mkcert to be installed\n\n2. self-signed (fallback):\n   - used when mkcert is not available\n   - requires clicking through browser warnings\n   - still secure, just not automatically trusted\n\n## network configuration\nthe service runs on the following ports:\n- dns (dnsmasq): 53/udp\n- http (nginx): 80\n- https (nginx): 443\n\n## generated files\nthe following files are generated and should not be committed to git:\n- `docker/nginx/nginx.conf`: generated nginx configuration\n- `docker/dnsmasq/dnsmasq.conf`: generated dnsmasq configuration\n- `ssl/`: directory containing generated certificates\n- `sites.conf.json`: your local site configuration\n\n## troubleshooting\n1. dns not working:\n   - check if port 53 is available\n   - ensure your dns points to 192.168.1.201\n   - try adding domains to /etc/hosts as fallback\n   - check if your router or isp is blocking port 53\n   - verify dnsmasq container is running: `docker-compose ps`\n\n2. ssl certificate warnings:\n   - install mkcert for trusted certificates\n   - or click through the warnings for self-signed certs\n\n3. upstream server not reachable:\n   - verify the real_host ip and port in sites.conf.json\n   - ensure the upstream server is running\n   - check docker network connectivity\n\n4. checking logs:\n   ```bash\n   # all services\n   docker-compose logs -f\n   \n   # specific service\n   docker-compose logs -f nginx\n   docker-compose logs -f dnsmasq\n   ```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foeo%2Flocalroute","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Foeo%2Flocalroute","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Foeo%2Flocalroute/lists"}