2. Setup using pip

This guide explains how to install dino inside a fresh ubuntu 18.04 bionic box. It includes the installation of all on-host prerequisites and provides you with a fully functional Dino instance.

Most of the steps are the same for other distributions like Debian or CentOS, so you should be able to adpat this to your needs as you go. We’d be glad about full guides for other operating systems. So please feel free to send us tips or even open a Pull Request on GitHub.

2.1. Prerequisites

2.1.1. PowerDNS

To use dino, a running PowerDNS instance is required. In addition to the default config, the following options are needed:

# 1. enable the API and choose a sane API key
api=yes
api-key=SOME_LONG_API_KEY_CHANGE_ME_PLEASE

# 2. enable the webserver and give dino acces to it
#    either by whitelisting it here, in your reverse proxy or in your firewall.
webserver=yes
webserver-address=0.0.0.0
webserver-port=8080
webserver-allow-from=1.2.3.4/32

Remember (… or write down) server hostname, webserver port as well as the API key.

2.1.2. Python 3.6

Python 3.6 or newer is required. Ubuntu already comes with python 3.6, so we’re good here. To complete the python setup, install the package manager pip, which is needed later.

root@ubuntu-bionic:~# python3 --version
Python 3.6.7
root@ubuntu-bionic:~# apt install -y python3-pip
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following additional packages will be installed:
(...)

Note

Debian users might be able to compile python 3.6 from source or get it from the Debian Sid repos.

Note

CentOS users can get python 3.6 from the IUS Project; install python36u as well as python36u-pip.

2.1.3. Other dependencies

We also need some further dependencies to install uWSGI via pip in the next step.

root@ubuntu-bionic:~# apt install -y python3-setuptools build-essential python3-dev
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following additional packages will be installed:
(...)
root@ubuntu-bionic:~# pip3 install wheel
Collecting wheel
  Downloading https://files.py..
(...)

2.1.4. uWSGI

uWSGI actually runs dino and will later provide it via HTTP on port 8080. It is installed globally using pythons dependency manager pip:

root@ubuntu-bionic:~# pip3 install uwsgi
Collecting uwsgi
  Downloading https://files.py..
(...)

2.1.5. System User

To make sure dino can only access what it needs to access, create a new user.

Note

Instead of using the default www-dino, you can freely choose any non-existing username. Just make sure to adapt the following steps and the systemd unit accordingly.

root@ubuntu-bionic:~# adduser --disabled-password --disabled-login \
  --system --home /opt/dino www-dino

2.2. Dino

root@ubuntu-bionic:~# sudo -Hu www-dino pip3 install --user \
  https://github.com/Uberspace/dino/archive/master.zip#subdirectory=src
Collecting https://github.com/Uberspace/dino/archive/master.zip#subdirectory=src
  Downloading https://github.com/Uberspace/dino/archive/master.zip
    / 1.3MB 295.2MB/s
(...)
Successfully installed (...) dino-0.1 (...)

Note

If you’d like to use a database other than SQLite, the corresponding python client library needs to be installed. Use one of the following urls instead of the one given above:

Additionally, the libmariadbclient-dev apt package is required for mysql.

2.2.1. Configuration

Create a file called /etc/dino.cfg with the following content. It provides a bare-bones configuration for django, which should be extended. Please go through the list of config options and set the appropriate values.

# a long (>64 chars) and random (alpha-numeric-ish) string of characters
DINO_SECRET_KEY=
# URL to your PowerDNS server API endpoint, e.g. https://yourpowerdns.com/api/v1
DINO_PDNS_APIURL=
# PowerDNS API key from /etc/pdns/pdns.conf
DINO_PDNS_APIKEY=
# comma-separated list of hostnames dino should be reachable under
DINO_ALLOWED_HOSTS=
# a place for dino to drop internal data; must be writeable by dino and
# not publicly acccessible
DINO_BASE_DIR=/opt/dino
# make use of the X-Forwarded-Host/Proto headers in nginx config
DINO_TRUST_PROXY=True

Note

By default, dino uses a SQLite database inside DINO_BASE_DIR. If you’d like to use a different system or database location, provide the respective URL as DINO_DB_URL:

  • SQLite: sqlite:////some/absolute/path/db.sqlite3
  • PostgreSQL (Password): postgres://dino:PASSWORD@127.0.0.1:5432/dino
  • PostgreSQL (UNIX-Socket / Peer Auth): postgres://%2Fpath%2Fto%2Fsocket/dino
  • MySQL: mysql://dino:PASSWORD@127.0.0.1:3306/dino

Further information can be found in the dj-database-url documentation.

2.2.2. Service

To start dino automatically when your server boots up, create a new systemd unit in /etc/systemd/system/dino.service and add the following content.

Warning

The path to uwsgi (/usr/local/bin/uwsgi) may vary on other distributions. To be on the safe side, use the command which uwsgi to get the path for your installation.

[Unit]
Description=uWSGI dino
After=networking.target

[Service]
ExecStart=/usr/local/bin/uwsgi --http-socket :8080 --master --workers 8 --module dino.wsgi
User=www-dino
Restart=always
KillSignal=SIGQUIT
Type=notify
StandardError=syslog
NotifyAccess=all

[Install]
WantedBy=multi-user.target

Finally, load the newly create service:

root@ubuntu-bionic:~# systemctl daemon-reload

2.2.3. Finishing up

2.2.3.1. Initialize the database

The following command creates all tables needed by dino. This will connect to the database server specified in DINO_DB_URL, which defaults to using a file-based SQLite database. If you’d like to use a different database, jump back to the Configuration section and adpat the setting.

root@ubuntu-bionic:~# sudo -Hu www-dino python3 -m dino migrate
DEBUG enabled, but django_extensions not installed. skipping app.
Operations to perform:
  Apply all migrations: account, admin, auth, contenttypes, sessions, sites, socialaccount, synczones, tenants
Running migrations:
  Applying contenttypes.0001_initial… OK
  Applying auth.0001_initial… OK
  Applying account.0001_initial… OK
  Applying account.0002_email_max_length… OK
(...)

2.2.3.2. Create an admin user

The very first user has to be created using an interactive command. Additional users can be created in the web interface, once we’re up and running.

root@ubuntu-bionic:~# sudo -Hu www-dino python3 -m dino createsuperuser

2.2.3.3. Start dino

root@ubuntu-bionic:~# systemctl enable dino --now

Congratulations, is now running! You can verify this by querying the port directly:

root@ubuntu-bionic:~# curl 127.0.0.1:8080
<h1>Bad Request (400)</h1>

You can now configure your webserver to route requests to dino, either by yourself or using the Webserver guide.

2.3. Updates

To update dino repeat the pip3 install and dino migrate steps from the installation guide. Afterwards, restart dino to load the new code.

root@ubuntu-bionic:~# sudo -Hu www-dino pip3 install --user \
  https://github.com/Uberspace/dino/archive/master.zip#subdirectory=src
(...)
root@ubuntu-bionic:~# sudo -Hu www-dino python3 -m dino migrate
(...)
root@ubuntu-bionic:~# systemctl restart dino