mreg

mreg is an API (intended to be as RESTful as possible) for managing DNS.

An associated project for a command line interface using the mreg API is available at: mreg-cli

Getting Started

Prerequisites

If you want to set up your own PostgreSQL server by installing the necessary packages manually, you might need to install dependencies for setting up the citext extension. On Fedora, the package is called postgresql-contrib.

Installing

Using Docker

Pre-built Docker images are available from ghcr.io/unioslo/mreg:

docker pull ghcr.io/unioslo/mreg

You can also build locally, from the source:

docker build -t mreg .

It is expected that you mount a custom "mregsite" directory on /app/mregsite:

docker run \
  --mount type=bind,source=$HOME/customsettings,destination=/app/mregsite,readonly \
  ghcr.io/unioslo/mreg:latest

To access application logs outside the container, also mount /app/logs.

It is also possible to not mount a settings directory, and to supply database login details in environment variables instead, overriding the default values found in mregsite/settings.py.

docker run --network host \
  -e MREG_DB_HOST=my_postgres_host -e MREG_DB_NAME=mreg -e MREG_DB_USER=mreg -e MREG_DB_PASSWORD=mreg \
  ghcr.io/unioslo/mreg:latest

For a full example, see docker-compose.yml.

Manually

[!TIP] Depending on your operating system, you may need to install additional packages to get the necessary dependencies for the project. At the very least you will probably require development packages for Python 3.

A step by step

Start by cloning the project from github. You need a terminal, python3, and access to a package manager that can install the necessary requirements from requirements.txt. We use pip.

When you've got your copy of the mreg directory, setup you virtual environment:

> python3 -m venv venv
> source venv/bin/activate

Then install the required packages:

> pip install -r requirements.txt

Perform database migrations:

> python manage.py migrate

Load sample data from fixtures into the now migrated database:

> python manage.py loaddata mreg/fixtures/fixtures.json

And finally, run the server:

> python manage.py runserver

You should now be able to open up a browser and go to http://localhost:8000/hosts/ and see a list of hosts provided by the sample data. Or, you could perform a GET request to see the returned data.

> curl -X GET http://localhost:8000/hosts/
[{"name":"ns1.uio.no"},{"name":"ns2.uio.no"},{"name":"lucario.uio.no"},{"name":"stewie.uio.no"},{"name":"vepsebol.uio.no"}

Running the tests

To run the tests for the system, simply run

> python manage.py test

Local Settings

To override entries in mregsite/settings.py, create a file mregsite/local_settings.py and add the entries there. For example, the default database setup in settings.py uses sqlite3, but if you set up your postgres database you'll want to override this when testing. To to this, just add the following to your local_settings.py file:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'mreg_sample',
        'USER': 'mreg_user',
        'PASSWORD': 'mregdbpass',
        'HOST': 'localhost',
    }
}

Contributing

Patches and PRs are welcome. However, there are a number of intricacies in both code structure and internal expectations, so you should probably get in touch with the project maintainers before you start working on anything major. If in doubt, open an issue to start a discussion.

Reference material

Authors

Øyvind Hagberg
Øyvind Kolbu
Paal Braathen
Geir Ulvik
Nils Hiorth
Nicolay Mohebi
Magnus Hirth
Marius Bakke
Safet Amedov
Tannaz Roshandel
Terje Kvernes

License

This project is licensed under the GPL-3.0 License - see the LICENSE.md file for details

unioslo/mreg