Documentation
Introduction
Getting started with DNS Deploy is a simple process that takes no more than 5 minutes. This documentation breaks out the process into 5 easy sections to get you up and running as quickly as possible. We know we have built a great product to help your business, so we want to make sure we have spectacular documentation that makes sure you understand every step of the process. We provide easy to understand explanations, and relevant accompanying pictures, so everything should look familiar as you follow along.
Most of the documentation will follow along as we setup DNS Deploy for our "Example Application" that lives at https://example.com. You can find the repositories referenced in this documentation on our DNS Deploy GitHub page.
If you do have a question along the way, please do not hesitate to contact us. We will do our best to clarify the process, and will probably end up improving our documentation for the benefit of everyone!
Sources
Sources are where your records live, and where we pull the records from. Currently DNS Deploy supports the following sources:
The first step after creating your account is to connect to your sources. You can connect to any number of the available sources. This section will take you through the steps to connect your GitHub account, but the process for all the providers is very similar.
Step 1
Start off by heading to the
Sources page. Here you will find a list of all the available sources. Click on the
button.
Step 2
You will be redirected to the GitHub website to authenticate, and then authorize access of the DNS Deploy application to your account.
Step 3
Finally, you will be redirected back to DNS Deploy. If the connection was successful, you will see a confirmation message.
While most users will only have one source to connect, you are able to connect to all the Sources if you would like. Now that you are connected, you are one step close to better DNS with DNS Deploy.
Providers
Providers are the services that run your nameservers and host your domain records. They are where we will deploy your records to. We currently support the following providers:
Step 1
Start out by visiting the providers page. This will list all of your currently configured providers. To create a new one, click the button on the right.
Step 2
Fill in the desired information for the provider. Begin by selecting the provider from the dropdown. If you have multiple connections to the same provider, it can also be helpful to enter a descriptor. If your provider requires both an API Key and an API Secret, enter them both. If your provider only requires 1, enter it in the API Secret, and leave the API Key empty.
Step 3
Click the button. If you have filled everything out correctly, you will be taken back to the main providers page, and see your newly created provider in the list.
Each provider API we integrate with comes with its own nuances. Additional information about each is provided below to help you better understand how they operate.
Feel free to connect as many providers as you need, if you host different domains on different DNS. Now that we have your sources and providers connected, let's get your domains configured so we can start deploying!
GoDaddy
GoDaddy is by and large the most popular DNS provider in the world, accounting for approximately 42% of all domains. They also provide, in our opinion, the best API for DNS management due to their endpoint to replace all existing records. This means even if the operation fails, your previous records are still active.
Credentials
GoDaddy requires both an API key and an API secret. Visit their developer portal and click on "API Keys".
Now click the "Create New API Key" button.
Enter a name to help distinguish your API credentials. Don't worry, you can change this later if you need to. For the environment, select "Production", and then click next.
Copy the "Key" into your API Key field, and copy the "Secret" into the API Secret field.
Record Support
GoDaddy supports A, AAAA, CNAME, MX, NS, SRV, and TXT records. The notable exception here is CAA records, which are accepted through the web interface. We will continue to monitor this situation and add support when GoDaddy adds it.
Deploy Process
GoDaddy is the simplest of all the domain deployments, due to the fact GoDaddy must be your registrar to host DNS there, and because they have a couple extra helpful API endpoints.
- An API call is made to replace all the records of a specific domain. If it fails, no records are updated. If it succeeds, all records are updated.
Cloudflare
Cloudflare is the second most popular DNS provider in the world, accounting for approximately 23% of all domains. They are a popular choice for many developers due to the large number of services they offer.
Credentials
Cloudflare requires both a key and an API secret. Login to your account, and visit your profile. At the bottom you will see a section labelled "API Keys".
Click the "View" button next to the "Global API Key", and enter your account password. Copy the value to the API Secret field. Enter your account email address for the API Key.
Record Support
Cloudflare supports A, AAAA, CNAME, MX, NS, SRV, and TXT records. A notable exception here is CAA records. We will continue to monitor this situation and add support when Cloudflare adds it.
Deploy Process
Cloudflare has a multi-step deploy process. A failure could result in incorrect values at your provider.
- Attempt to get the domain zone.
- Create the domain zone if it does not already exist.
- If the domain zone already exists, fetch all the records, and then delete them all.
- Create the records.
Digital Ocean
Digital Ocean may not be the most popular DNS provider, but they are one of the fastest. They also hold a special place in our hearts, as we use them for a lot of our infrastructure.
Credentials
Digital Ocean only requires an API secret. Visit your API Dashboard and click "Generate New Token".
Enter a token name, to help distinguish it. Make sure both the "Read" and the "Write" scopes are checked.
Leave the API Key field blank, and copy your token into the API Secret field.
Record Support
Digital Ocean supports A, AAAA, CNAME, MX, NS, SRV, TXT, and CAA records.
Deploy Process
Digital Ocean has a multi-step deploy process. A failure could result in incorrect values at your provider.
- Attempt to create the domain. If it does not exist, it will be newly created, but if it does already exist, it will continue on.
- Get all existing records.
- Delete all existing records.
- Create the records.
Domains
Now that we've authenticated with our source, and connected to our provider, it's time to configure our domains. This is the final step before we're able to start deploying. Follow along with these instructions to see how easy it is!
Step 1
Start out by visiting the domains page. This will list all of your currently configured domains. To create a new one, click the button.
Step 2
Fill in the desired information for the domain. Enter the domain name, which Source you will be pull from, the repository the records live in, the file
Step 3
Click the button. If you have filled everything out correctly, you will be taken back to the main domains page, and see your newly created domain in the list.
Your domain is now set up! Feel free to add more as needed. If you reach your plan limit you can easily upgrade to add all the domains you require.
Zone Files
Zone files are what actually house your DNS records. The zone file contains mappings between domain names, and IP addresses and other resources. Traditionally, they are simple text files, which DNS Deploy supports. We also support (and recommend) a JSON version of your zones, which you may find easier to edit and maintain. Your zone file can live in any repository and any file that you have access to. There is no wrong answer on where you store the zone file, but we will discuss 2 common options.
Grouped Zones
If you are managing a large number of domains, and wish to have a consistent, centralized location for your zones, a common structure is to create a dedicated repository. For example, DNS Deploy has a repository in our GitHub account called 'dns', which houses the zone files for a couple of example domains.
Within this repository we have a folder called 'zones', and then within this folder, there is a file for each and every domain that we manage.
Per Project Zones
Another great option is to make the zones a part of the application repository itself. Let's say we have a repository for our application that lives at example.com. In the repository, in addition to all the site files for the application, add a file called `dns.json` (or whatever name works for you). This file will contain your DNS records.
Text Zone Files
Text files are the traditional form of zone files, and are supported by DNS Deploy. Each line is a text description that defines a single resource record. The line consists of several fields separated by white space (spaces or tabs). The information from text files is extracted by regular expressions.
JSON Zone Files
In addition to traditional text files, DNS Deploy also supports JSON zone files. Not only do we support it, we actually encourage it! The JSON format is much easier for us to parse, as opposed to the regular expressions we rely on to parse the text files. JSON is also much easier to comprehend and edit, because the fields and their values are explicitly declared, rather than simply relying on the order of elements in the text files. Again, while not required, we highly encourage you to use the JSON format for your zone files.
Extractions
If you have a large number of traditional text zones files and would like to store them as JSON files instead, it would be very time consuming to convert them all manually, so we built a tool that will do it for you! Our Extractor allows you to upload up to 500 zone files, which will be read, evaluated, and recreated as a downloadable archive file of all the JSON zones.
Now that you have authenticated to your source, connected your provider, configured your domain, and created your zone file, it's time to deploy!
Deployments
Now that we have everything setup, it's time to start an actual deployment. Running a deploy will read the zone file from your source, and write the records to your provider.
Step 1
You can start the deployment directly from the domain screen by clicking the button,
or from the domain page.
Step 2
When you start a deployment, DNS Deploy will first query the designated source, and look in the appropriate repository for the selected file. We will then extract all of the zone information from the file, and display it to you. Once you check over the records, hit the button to begin the deployment.
Step 3
The records are now being sent to the provider's API. The speed of the specific provider's API, and the number of records you have will contribute to how fast the deployment process finishes. When it is completed,
Congratulations! You have completed your first deployment of your DNS records with DNS Deploy! Thanks for taking the time to read through our documentation, and become familiar with how to use this product. As always, please feel free to reach out to us if you have got any questions, comments, or you just want to tell us about the project you are using DNS Deploy for. Happy deploying!