How to manage your DNS with GitHub

LuaDNS is a managed DNS service. Git is used to manage domains and Lua scripts to generate DNS records, changes are deployed to name servers with a simple git push.

What's wrong with traditional aproach?

In our opinion, DNS configurations are best expressed with simple text files. The problem is that Bind syntax is too noisy and managing tens or hundreds of domains through a web interface is not a pleasant task.

LuaDNS platform

LuaDNS borrowed convention over configuration philosophy from Rails. To accompish it's task LuaDNS is following a few conventions, once you'll understand them you'll love them. :)

It exploits defaults to the maximum to make configurations simple and clear. Why same thing should be expressed over and over? If we are comfortable with defaults, why we should pollute our configurations? Domain aliases should be expressed easily.

• Why source control ?
  When working in teams, ability to track changes (who, when, what) and changes reverting are very important.
• Why scripting ?
  Repetitive tasks can be scripted into functions to fight complexity. Lua is a mature scripting language, designed decade ago and used in many large projects.

LuaDNS supports most common Resource Records (RR):

A, AAAA, CNAME, MX, NS, PTR, SOA, SPF, SRV, TXT

Initial configuration

To use LuaDNS platform you'll need a LuaDNS account and a GitHub repository. Follow this easy steps:

1. Create a new git repository on GitHub:
   • Project Name: dns
2. Create a local repository and connect it to freshly created GitHub repository (replace USER with your GitHub username):

   mkdir dns
   cd dns
   git init
   echo 'DNS settings, more on: https://www.luadns.com/' > README.md
   git add README.md
   git commit -m 'first commit'
   git remote add origin git@github.com:USER/dns.git
   git push -u origin master
   

3. Edit your LuaDNS account and set your source repository (replace USER with your GitHub username).

   git@github.com:USER/dns.git
   

4. Configure your GitHub repository to notify LuaDNS when you push changes to it, add a Post-Receive Hook
   (Admin -> Service Hooks -> Post-Receive URL):
   https://api.luadns.com/notifications/YOUR_API_KEY/push
   (You'll find your API_KEY in the API Keys page)

After initial configuration, you are ready to proceed to next step, zone configuration.

Example domain

We'll show you an example using domain example.com, but you should replace example.com with your domain name.

Change to your git repository created in previous section and add an "example.com" zone to repository to it:

touch example.com.lua templates.lua
git add example.com.lua templates.lua

Edit example.com.lua and paste the following content:

-- File: example.com.lua
-- Zone: example.com
-- _a variable is replaced with zone name "example.com"

-- ## GitHub pages example
-- More info in "Custom Domains" section here: https://help.github.com/pages/
a(_a, "204.232.175.78")
cname("www", "charlie.github.com")

-- ## Google Apps example
-- We'll host our mail on Google Apps, because we have multiple domains using
-- Google Apps, we'll save snippet as a template (Lua function).
-- All templates should go to templates.lua file.
google_app(_a)

Save the following Lua code to templates.lua:

-- File: templates.lua
-- This file is executed before each .lua file
-- shared code/templates should reside here.

function google_app(domain)
  -- mail exchangers
  mx(domain, "aspmx.l.google.com", 5)
  mx(domain, "alt1.aspmx.l.google.com", 10)
  mx(domain, "alt2.aspmx.l.google.com", 10)
  mx(domain, "aspmx2.googlemail.com", 20)
  mx(domain, "aspmx3.googlemail.com", 20)
  -- mail.domain.com alias
  cname(concat("mail", domain), "ghs.google.com")
  -- SPF record
  spf(domain, "v=spf1 a mx include:_spf.google.com ~all")
end

Deploying

Now you are ready to to push your DNS configurations to LuaDNS servers through GitHub.

git commit -m "add example.com domain" .
git push origin master

After git push command, you'll receive an email from LuaDNS.com with the status of your changes. If everything is OK (domains and records are validated on each push), your domains and records will be deployed to name servers, if errors are found you'll receive details about the problems so you can fix them and try again.

Changing name servers at your registrar

After successful deployment, you are ready to switch to LuaDNS name servers (more about name servers here):

• ns1.luadns.net
• ns2.luadns.net
• ns3.luadns.net
• ns4.luadns.net

Open Source

LuaDNS service was built using many open source technologies. To support open source movement we are offering a special package to open source projects, more info here.

Update:

1. "Too noisy" when dealing with multiple domains sharing the same records/similar set of records (a common case).

References:

1. Documentation - https://www.luadns.com/help.html
2. Example repository - https://github.com/luadns/dns
3. GitHub - https://github.com
4. Bitbucket - https://bitbucket.org