VegaDNS API, the successor to VegaDNS, is a REST API for managing DNS records in MySQL for use with tinydns. Written in python, it relies on flask, flask_restful, and peewee. It generally is run using uwsgi and supervisor behind nginx. (See the example-configs directory for example configuration files). It currently supports basic auth, cookies, and OAuth2 (section 4.4) for authentication.

There are two supported API clients at this time:

• VegaDNS-UI - a JavaScript only UI, similar to the old VegaDNS.
• VegaDNS-CLI - a command line interface that includes a reusable client library written in python.
• vegadns2client - a new, though currently incomplete, golang library.

The following steps assumes your docker host is "localhost". If it is not, you can indicate your docker host via the API_URL environment variable. i.e.:

# for standard split services via "make up":
export API_URL=http://192.168.1.1:5000

# Or if you are using "make up-apiui"
export API_URL=http://192.168.1.1:80

Start by pulling down the docker images:

make pull up

Then log in at http://localhost/ with the user "test@test.com" and a password of "test"

If you want to watch logs, say for just api and tinydns, you can do:

LOGS_ARGS="-f api tinydns" make logs

If you'd like to easily log into the example mysql service, do:

make dev-db

To shut down, just run

make down

The above will run the api on port 5000, and the ui on port 80. If you would like to experiment with the vegadns/apiui image, which runs both components on port 80, you can use the following commands:

make up apiui
make down apiui

make build-api
make build-apiui

If you want to get this up and running from a git checkout manually, you'll want to use python 2.7.9 or later (3 is not yet tested), and have pip and virtualenv installed. This assumes you have a mysql server with a database called vegadns created, and write privileges granted. From there, you can do the following to set up your virtual environment:

make venv

You'll also need to set up your vegadns/api/config/local.ini file with the following, replacing values with credentials for your mysql database:

[mysql]
user = vegadns
password = secret
database = vegadns
host = localhost

Have a look at default.ini for a full list of configuration items you may want to override.

Lastly, you need to create your database contents. You can apply the following an empty database:

mysql -u vegadns -p -h localhost vegadns < sql/create_tables.sql
mysql -u vegadns -p -h localhost vegadns < sql/data.sql

If you are testing a copy of a legacy VegaDNS 0.11.3 or newer database, you can just run this instead:

mysql -u vegadns -p -h localhost vegadns < sql/new_tables_only.sql
mysql -u vegadns -p -h localhost vegadns < sql/alter-01.sql
mysql -u vegadns -p -h localhost vegadns < sql/alter-02.sql
mysql -u vegadns -p -h localhost vegadns < sql/alter-03.sql
mysql -u vegadns -p -h localhost vegadns < sql/data_api_keys_only.sql

(If you are running VegaDNS < 0.11.3, see UPGRADE for details on upgrading beforehand)

Now that the environment is setup, you can start the built-in flask web server to test below:

$ . venv/bin/activate && DEBUG=true python run.py
 * Running on http://0.0.0.0:5000/ (Press CTRL+C to quit)
  * Restarting with stat

Once installation is complete, you'll probably want to use one of the supported clients above for accessing the api. If this is a clean install, the test account is test@test.com with a password of "test". If you're using existing accounts, they should work as well.

The vegadns/api image currently runs under gunicorn. If you want to run it under uwsgi/supervisor/nginx and alongside the UI like the vegadns/apiui image, see the files in the docker/templates directory, as well as docker/Dockerfile.apiui and docker/start.sh.

To run unit tests in a container using docker-compose, just run:

make test-docker

For integration tests only, run:

make up test-integration down

To check pep8 compliance and run tests locally, run:

make test

You can also check code coverage:

make coverage

or

make coverage-html

This will call "open" on the coverage html, opening it in your browser.

• New permissions structure. Instead of 3 tiers (senior_admin, group_admin, user), there is only senior_admin and user tiers (type). Users can own domains and privileges can now be granted to groups. This should be a much more flexible architecture. Currently there is no migration tool for people using the legacy group_admin tier. If there is much of a need, I can put one together.
• Added tinydns location support. If you want to do split horizon dns, you can specify locations and network prefixes for those locations, and then bind records to those locations to serve up different results based on the network the request came from. If you want to use IPv6 network prefixes, note that djbdns needs to be patched for IPv6. (If on debian/ubuntu, you can alternately use the already patched dbndns package instead of the djbdns package)
• Optional push notifications to updaters. If you want your tinydns servers to update on demand, you have two options:
  • You can set up a consul server to handle consul-template messaging. See default.ini, consul-template-real-time.sh, consul-lock-periodic.sh, and consul-template.in.tpl.
  • You can set up a redis server to handle Pub/Sub messaging. See default.ini and redis_listener.sh.
• REST API only, a JavaScript only UI is available separately here
• Optional global record ACLs To allow restrictions on integrations with tools like Let's Encrypt, you can now specify certain global labels (i.e. _acme-challenge.DOMAIN) that can be written to by a list of users. See default.ini for more details.
• API is written in python rather than PHP

For comments or support, please use the issue tracker on Github. You may use the Google Group as well for discussions.