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-CLI - a command line interface that includes a reusable client library written in python.
- vegadns2client - a new, though currently incomplete, golang library.
Setup using docker compose
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
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:
To shut down, just run
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
Building the vegadns/api or vegadns/apiui images
make build-api make build-apiui
Manual setup of the api from a git checkout
If you want to get this up and running from a git checkout manually, you'll want to use python 3.6 or later (2 is no longer supported), and have pip3. 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:
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 firstname.lastname@example.org with a password of "test". If you're using existing accounts, they should work as well.
Running under uwsgi/supervisor/nginx
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.
Tests - running in containers
To run unit tests in a container using docker-compose, just run:
For integration tests only, run:
make up test-integration down
Tests - running locally
To check pycodestyle compliance and run tests locally, run:
You can also check code coverage:
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:
- 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