Skip to content
Simple Node.js dynamic DNS service
Branch: master
Clone or download
Latest commit 606061d Nov 26, 2018
Type Name Latest commit message Commit time
Failed to load latest commit information.
config Update and refactor for native async Jul 29, 2017
controllers Add account deletion functionality Mar 17, 2018
models Update and refactor for native async Jul 29, 2017
public Update Bootstrap Mar 17, 2018
views Add account deletion functionality Mar 17, 2018
.editorconfig Improve rules Mar 17, 2018
.eslintrc.json Update and refactor for native async Jul 29, 2017
.gitattributes Initial commit Apr 3, 2016
.gitignore Cleanup Apr 17, 2016 Bump year Mar 17, 2018 Update URL Dec 5, 2017
app.js Add account deletion functionality Mar 17, 2018
db.js Update dependencies Mar 17, 2018
dns-server.js Improve logging Jul 29, 2017
package-lock.json Update Nodejs packages Nov 26, 2018
package.json Update Nodejs packages Nov 26, 2018
production.yml Simplify config naming Apr 21, 2016
server.js Update and refactor for native async Jul 29, 2017


License Release Version Dependencies

Tiny Node.js dynamic DNS service built with dnsd, Express.js, MongoDB, Pug and Bootstrap.

The app consists of two parts: a web frontend with registration, login and IP address mapping; and a tiny DNS server which serves records from a database.

Use it for free at


You can simply login to the website and manage your subdomain and IP address there or you can use the simple HTTP API to update your IP with a script or dynamic DNS client.


The easiest way to keep your mapping up to date is to add the following line to your crontab which will update your IP every three hours:

0 */3 * * * curl -u 'USERNAME:PASSWORD'


You can use ddclient to keep your IP address up to date with the following config:, \
protocol=dyndns2,   \
login=USERNAME,     \
password=PASSWORD   \


Routers running DD-WRT can update your IP address by using the built in dynamic DNS settings found under Setup → DDNS. Other routers may also work but are untested.

DDNS Service: Custom
DYNDNS Server:
Username: USERNAME
Password: PASSWORD
URL: /nic/update?hostname=


  1. Clone this repo:
git clone && cd localdns
  1. Install dependencies:
docker-compose run --no-deps --rm app npm install
  1. Start app, DNS server and database:
docker-compose up
  1. Test the local DNS server:
dig localdns.local @localhost
  1. Register an account and subdomain in your browser at http://localhost:3000/

  2. Lookup the subdomain and check the IP address:

dig example.localdns.local @localhost


  1. Create DNS glue records for ns1.your.domain with your domain registrar pointing to your server's IP address and register it as the domain's nameserver.

  2. Configure config/production.json with your domain, server IP and any custom records and settings

  3. Make sure your server's firewall allows external DNS traffic on port 53 TCP and UDP

  4. Follow development steps 1 and 2 above and start the production stack:

docker-compose -f docker-compose.yml -f production.yml up
  1. Test DNS resolution:
dig your.domain ANY @ns1.your.domain
You can’t perform that action at this time.