diff --git a/docs/wiki/README.md b/docs/wiki/README.md index 8010cc1..8a002bd 100644 --- a/docs/wiki/README.md +++ b/docs/wiki/README.md @@ -1,23 +1,43 @@ # Welcome to the PowerDNS-Admin wiki! -## Preparation guides -- [Prepare MySQL or MariaDB Database for PowerDNS-Admin](preparation/Prepare-MySQL-or-MariaDB-Database-for-PowerDNS-Admin.md) -- [Using PowerDNS-Admin with PostgreSQL](preparation/Using-PowerDNS-Admin-with-PostgreSQL.md) +## Database Setup guides: +- [MySQL / MariaDB](database-setup/Setup-MySQL-or-MariaDB.md) +- [PostgreSQL](database-setup/Setup-PostgreSQL.md) -## Installation guides -- [Running PowerDNS Admin on Ubuntu or Debian](install/Running-PowerDNS-Admin-on-Ubuntu-or-Debian.md) -- [Running PowerDNS-Admin on Centos 7](install/Running-PowerDNS-Admin-on-Centos-7.md) -- [Running PowerDNS-Admin on Fedora 23](install/Running-PowerDNS-Admin-on-Fedora-23.md) -- [Running PowerDNS-Admin on Fedora 30](install/Running-PowerDNS-Admin-on-Fedora-30.md) -- [Running PowerDNS-Admin on FreeBSD 12.1-RELEASE](install/Running-on-FreeBSD.md) +## Installation guides: +- [General (Read this first)](install/General.md) + - BSD: + - [Install on FreeBSD 12.1-RELEASE](install/Running-on-FreeBSD.md) + - Containers: + - [Install on Docker](install/Running-PowerDNS-Admin-on-Docker.md) + - Debian: + - [Install on Ubuntu or Debian](install/Running-PowerDNS-Admin-on-Ubuntu-or-Debian.md) + - Red-Hat: + - [Install on Centos 7](install/Running-PowerDNS-Admin-on-Centos-7.md) + - [Install on Fedora 23](install/Running-PowerDNS-Admin-on-Fedora-23.md) + - [Install on Fedora 30](install/Running-PowerDNS-Admin-on-Fedora-30.md) -## Web Server configuration + + + +### Post install Setup: +- [Environment Variables](configuration/Environment-variables.md) +- [Getting started](configuration/Getting-started.md) +- SystemD: + - [Running PowerDNS-Admin as a service using Systemd](install/Running-PowerDNS-Admin-as-a-service-(Systemd).md) + +### Web Server configuration: - [Supervisord](web-server/Supervisord-example.md) - [Systemd](web-server/Systemd-example.md) -- [Systemd + Gunicorn + Nginx](web-server/Running-PowerDNS-Admin-with-Systemd,-Gunicorn--and--Nginx.md) +- [Systemd + Gunicorn + Nginx](web-server/Running-PowerDNS-Admin-with-Systemd-Gunicorn-and-Nginx.md) - [Systemd + Gunicorn + Apache](web-server/Running-PowerDNS-Admin-with-Systemd,-Gunicorn-and-Apache.md) - [uWSGI](web-server/uWSGI-example.md) - [WSGI-Apache](web-server/WSGI-Apache-example.md) +## Using PowerDNS-Admin: +- Setting up a domain +- Adding a record +- + ## Feature usage - [DynDNS2](features/DynDNS2.md) \ No newline at end of file diff --git a/docs/wiki/Configure-Active-Directory-Authentication-using-Group-Security.md b/docs/wiki/configuration/Configure-Active-Directory-Authentication-using-Group-Security.md similarity index 100% rename from docs/wiki/Configure-Active-Directory-Authentication-using-Group-Security.md rename to docs/wiki/configuration/Configure-Active-Directory-Authentication-using-Group-Security.md diff --git a/docs/wiki/configuration/Environment-variables.md b/docs/wiki/configuration/Environment-variables.md new file mode 100644 index 0000000..7b835e2 --- /dev/null +++ b/docs/wiki/configuration/Environment-variables.md @@ -0,0 +1,9 @@ +# Supported environment variables + +| Variable | Description | Required | Default value | +| ---------| ----------- | -------- | ------------- | +| SQLALCHEMY_DATABASE_URI | SQL Alchemy URI to connect to database | N | no default | +| SECRET_KEY | Flask secret key [^1] | Y | no default | + + +[^1]: Flask secret key (see https://flask.palletsprojects.com/en/1.1.x/config/#SECRET_KEY for how to generate) diff --git a/docs/wiki/configuration/Getting-started.md b/docs/wiki/configuration/Getting-started.md new file mode 100644 index 0000000..ce72234 --- /dev/null +++ b/docs/wiki/configuration/Getting-started.md @@ -0,0 +1,16 @@ +# Getting started with PowerDNS-Admin + + +In your FLASK_CONF (check the installation directions for where yours is) file, make sure you have the database URI filled in (in some previous documentation this was called config.py): + +For MySQL / MariaDB: +``` +SQLALCHEMY_DATABASE_URI = 'mysql://username:password@127.0.0.1/db_name' +``` + +For Postgres: +``` +SQLALCHEMY_DATABASE_URI = 'postgresql://powerdnsadmin:powerdnsadmin@127.0.0.1/powerdnsadmindb' +``` + +Open your web browser and go to `http://localhost:9191` to visit PowerDNS-Admin web interface. Register a user. The first user will be in the Administrator role. diff --git a/docs/wiki/database-setup/README.md b/docs/wiki/database-setup/README.md new file mode 100644 index 0000000..e4e4d01 --- /dev/null +++ b/docs/wiki/database-setup/README.md @@ -0,0 +1,4 @@ +# Database setup guides + +- [MySQL / MariaDB](Setup-MySQL-or-MariaDB.md) +- [PostgreSQL](Setup-PostgreSQL.md) diff --git a/docs/wiki/database-setup/Setup-MySQL-or-MariaDB.md b/docs/wiki/database-setup/Setup-MySQL-or-MariaDB.md new file mode 100644 index 0000000..246a0a5 --- /dev/null +++ b/docs/wiki/database-setup/Setup-MySQL-or-MariaDB.md @@ -0,0 +1,43 @@ +# Setup MySQL database for PowerDNS-Admin + +This guide will show you how to prepare a MySQL or MariaDB database for PowerDNS-Admin. + +We assume the database is installed per your platform's directions (apt, yum, etc). + +## Setup database: + +Connect to the database (Usually using `mysql -u root -p` - then enter your MySQL/MariaDB root users password if applicable), then enter the following: +``` +CREATE DATABASE `powerdnsadmin` CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; +GRANT ALL PRIVILEGES ON `powerdnsadmin`.* TO 'pdnsadminuser'@'localhost' IDENTIFIED BY 'YOUR_PASSWORD_HERE'; +FLUSH PRIVILEGES; +quit +``` +- If your database server is located on a different machine then change 'localhost' to '%' +- Replace YOUR_PASSWORD_HERE with a secure password. + +## Install required packages: +### Red-hat based systems: + +### Debian based systems: +``` +apt install libmysqlclient-dev +``` + +### Install python packages: +``` +pip3 install mysqlclient==2.0.1 +``` + + +## Known issues: + +Problem: If you plan to manage large zones, you may encounter some issues while applying changes. This is due to PowerDNS-Admin trying to insert the entire modified zone into the column history.detail. + +Using MySQL/MariaDB, this column is created by default as TEXT and thus limited to 65,535 characters. + +Solution: Convert the column to MEDIUMTEXT: +``` +USE powerdnsadmin; +ALTER TABLE history MODIFY detail MEDIUMTEXT; +``` diff --git a/docs/wiki/database-setup/Setup-PostgreSQL.md b/docs/wiki/database-setup/Setup-PostgreSQL.md new file mode 100644 index 0000000..40c1287 --- /dev/null +++ b/docs/wiki/database-setup/Setup-PostgreSQL.md @@ -0,0 +1,56 @@ +# Setup Postgres database for PowerDNS-Admin + +We assume you already have a postgres database software installed for your platform. + +### Create database +The below will create a database called powerdnsadmindb and a user of powerdnsadmin. + +``` +$ sudo su - postgres +$ createuser powerdnsadmin +$ createdb powerdnsadmindb +$ psql +postgres=# alter user powerdnsadmin with encrypted password 'powerdnsadmin'; +postgres=# grant all privileges on database powerdnsadmindb to powerdnsadmin; +``` + +Note: +- Please change the information above (db, user, password) to fit your setup. + +### Setup Remote access to database: +If your database is on a different server postgres does not allow remote connections by default. + +To change this follow the below directions: +``` +[root@host ~]$ sudo su - postgres +# Edit /var/lib/pgsql/data/postgresql.conf +# Change the following line: +listen_addresses = 'localhost' +# to: +listen_addresses = '*' +# Edit /var/lib/pgsql/data/pg_hba.conf +# Add the following lines to the end of the +host all all 0.0.0.0/0 md5 +host all all ::/0 md5 + +[postgres@host ~]$ exit +[root@host ~]$ sudo systemctl restart postgresql +``` + +On debian based systems these files are located in: +``` +/etc/postgresql//main/ +``` + +## Docker +TODO: Setup a local Docker postgres database ready to go (should probably move to the top). +``` +docker run --name pdnsadmin-test -e BIND_ADDRESS=0.0.0.0 +-e SECRET_KEY='a-very-secret-key' +-e PORT='9191' +-e SQLA_DB_USER='powerdns_admin_user' +-e SQLA_DB_PASSWORD='exceptionallysecure' +-e SQLA_DB_HOST='192.168.0.100' +-e SQLA_DB_NAME='powerdns_admin_test' +-v /data/node_modules:/var/www/powerdns-admin/node_modules -d -p 9191:9191 ixpict/powerdns-admin-pgsql:latest +``` \ No newline at end of file diff --git a/docs/wiki/install/General.md b/docs/wiki/install/General.md new file mode 100644 index 0000000..98dfa1f --- /dev/null +++ b/docs/wiki/install/General.md @@ -0,0 +1,7 @@ +# General installation + + +## Requirements: + +- A linux based system with python 3 or later available. Debian and Red-hat based systems are recommended, others (Arch-based for example) may work but are currently not tested. +- A database for PowerDNS-Admin, if you are using a database for PowerDNS itself this must be separate to that database. \ No newline at end of file diff --git a/docs/wiki/Running-PowerDNS-Admin-as-a-service-(Systemd).md b/docs/wiki/install/Running-PowerDNS-Admin-as-a-service-(Systemd).md similarity index 100% rename from docs/wiki/Running-PowerDNS-Admin-as-a-service-(Systemd).md rename to docs/wiki/install/Running-PowerDNS-Admin-as-a-service-(Systemd).md diff --git a/docs/wiki/install/Running-PowerDNS-Admin-on-Docker.md b/docs/wiki/install/Running-PowerDNS-Admin-on-Docker.md new file mode 100644 index 0000000..2f23845 --- /dev/null +++ b/docs/wiki/install/Running-PowerDNS-Admin-on-Docker.md @@ -0,0 +1,14 @@ +# Installation on docker + +The Docker image is ngoduykhanh/powerdns-admin available on [DockerHub](https://hub.docker.com/r/ngoduykhanh/powerdns-admin) + +The supported environment variables to configure the container are located [here](../configuration/Environment-variables.md). + +You can run the container and expose the web server on port 9191 using: +```bash +docker run -d \ + -e SECRET_KEY='a-very-secret-key' \ + -v pda-data:/data \ + -p 9191:80 \ + ngoduykhanh/powerdns-admin:latest +``` diff --git a/docs/wiki/install/Running-PowerDNS-Admin-on-Fedora-30.md b/docs/wiki/install/Running-PowerDNS-Admin-on-Fedora-30.md index 51b705c..bbd9f03 100644 --- a/docs/wiki/install/Running-PowerDNS-Admin-on-Fedora-30.md +++ b/docs/wiki/install/Running-PowerDNS-Admin-on-Fedora-30.md @@ -14,6 +14,11 @@ dnf install python37 python3-devel python3-pip ```bash dnf install mariadb-devel mariadb-common openldap-devel xmlsec1-devel xmlsec1-openssl libtool-ltdl-devel ``` +**Install Postgres dependencies** +```bash +$ sudo yum install postgresql-libs +$ pip3 install psycopg2 +``` **Install Development tools** ```bash dnf install gcc gc make @@ -27,6 +32,7 @@ pip3.7 install -U pip pip install -U virtualenv ``` + **Install Yarn for building NodeJS asset files:** ```bash dnf install npm diff --git a/docs/wiki/install/Running-PowerDNS-Admin-on-Ubuntu-or-Debian.md b/docs/wiki/install/Running-PowerDNS-Admin-on-Ubuntu-or-Debian.md index acc5858..d3bc834 100644 --- a/docs/wiki/install/Running-PowerDNS-Admin-on-Ubuntu-or-Debian.md +++ b/docs/wiki/install/Running-PowerDNS-Admin-on-Ubuntu-or-Debian.md @@ -1,37 +1,24 @@ -## Install required packages +# Installing PowerDNS-Admin on Ubuntu or Debian based systems -**Install Python 3 development package** +First setup your database accordingly: +[Database Setup](../database-setup/README.md) + +## Install required packages: + +### Install required packages for building python libraries from requirements.txt file ```bash -sudo apt install python3-dev +sudo apt install -y python3-dev git libsasl2-dev libldap2-dev libssl-dev libxml2-dev libxslt1-dev libxmlsec1-dev libffi-dev pkg-config apt-transport-https virtualenv build-essential curl ``` -**Install required packages for building python libraries from requirements.txt file** - -```bash -sudo apt install -y git libmysqlclient-dev libsasl2-dev libldap2-dev libssl-dev libxml2-dev libxslt1-dev libxmlsec1-dev libffi-dev pkg-config apt-transport-https virtualenv build-essential curl -``` - -_**Note:**_ I am using MySQL Community server as the database backend. So `libmysqlclient-dev` is required. For MariaDB, and PostgreSQL the required package will be difference. - -** Install Maria or MySQL (ONLY if not ALREADY installed)** -```bash -sudo apt install mariadb-server mariadb-client -``` -Create database and user using mysql command and entering -```bash ->create database pda; ->grant all privileges on pda.* TO 'pda'@'localhost' identified by 'YOUR_PASSWORD_HERE'; ->flush privileges; -``` -**Install NodeJs** +### Install NodeJs ```bash curl -sL https://deb.nodesource.com/setup_14.x | bash - apt install -y nodejs ``` -**Install yarn to build asset files** +### Install yarn to build asset files ```bash sudo curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | apt-key add - @@ -40,7 +27,7 @@ sudo apt update -y sudo apt install -y yarn ``` -## Checkout source code and create virtualenv +### Checkout source code and create virtualenv _**Note:**_ Please adjust `/opt/web/powerdns-admin` to your local web application directory ```bash @@ -56,9 +43,6 @@ source ./venv/bin/activate pip install --upgrade pip pip install -r requirements.txt ``` - - - ## Running PowerDNS-Admin Create PowerDNS-Admin config file and make the changes necessary for your use case. Make sure to change `SECRET_KEY` to a long random string that you generated yourself ([see Flask docs](https://flask.palletsprojects.com/en/1.1.x/config/#SECRET_KEY)), do not use the pre-defined one. E.g.: @@ -89,6 +73,7 @@ Now you can run PowerDNS-Admin by command ./run.py ``` -Open your web browser and go to `http://localhost:9191` to visit PowerDNS-Admin web interface. Register a user. The first user will be in the Administrator role. +This is good for testing, but for production usage, you should use gunicorn or uwsgi. See [Running PowerDNS Admin with Systemd, Gunicorn and Nginx](../web-server/Running-PowerDNS-Admin-with-Systemd-Gunicorn-and-Nginx.md) for instructions. -This is good for testing, but for production usage, you should use gunicorn or uwsgi. See [Running PowerDNS Admin with Systemd, Gunicorn and Nginx](web-server/Running-PowerDNS-Admin-with-Systemd,-Gunicorn--and--Nginx) for instructions. \ No newline at end of file + +From here you can now follow the [Getting started guide](../configuration/Getting-started.md). diff --git a/docs/wiki/preparation/Prepare-MySQL-or-MariaDB-Database-for-PowerDNS-Admin.md b/docs/wiki/preparation/Prepare-MySQL-or-MariaDB-Database-for-PowerDNS-Admin.md deleted file mode 100644 index 774d3e3..0000000 --- a/docs/wiki/preparation/Prepare-MySQL-or-MariaDB-Database-for-PowerDNS-Admin.md +++ /dev/null @@ -1,22 +0,0 @@ -This guide will show you how to prepare a MySQL or MariaDB database for PowerDNS-Admin. - -### Step-by-step instructions -1. ivan@ubuntu:~$ `mysql -u root -p` (then enter your MySQL/MariaDB root users password) -2. mysql> `CREATE DATABASE powerdnsadmin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;` -3. mysql> `GRANT ALL PRIVILEGES ON powerdnsadmin.* TO 'pdnsadminuser'@'%' IDENTIFIED BY 'p4ssw0rd';` -4. mysql> `FLUSH PRIVILEGES;` -5. mysql> `quit` - -**NOTE:** - -If you plan to manage large zones, you may encounter some issues while applying changes. -This is due to PowerDNS-Admin trying to insert the entire modified zone into the column history.detail. - -Using MySQL/MariaDB, this column is created by default as TEXT and thus limited to 65,535 characters. - -_Solution_: - -Convert the column to MEDIUMTEXT: - -* `USE powerdnsadmin;` -* `ALTER TABLE history MODIFY detail MEDIUMTEXT;` \ No newline at end of file diff --git a/docs/wiki/preparation/Using-PowerDNS-Admin-with-PostgreSQL.md b/docs/wiki/preparation/Using-PowerDNS-Admin-with-PostgreSQL.md deleted file mode 100644 index 04155e9..0000000 --- a/docs/wiki/preparation/Using-PowerDNS-Admin-with-PostgreSQL.md +++ /dev/null @@ -1,38 +0,0 @@ -If you would like to use PostgreSQL instead of MySQL or MariaDB, you have to install difference dependencies. Check the following instructions. - -### Install dependencies -``` -$ sudo yum install postgresql-libs -$ pip install psycopg2 -``` - -### Create database -``` -$ sudo su - postgres -$ createuser powerdnsadmin -$ createdb powerdnsadmindb -$ psql -postgres=# alter user powerdnsadmin with encrypted password 'powerdnsadmin'; -postgres=# grant all privileges on database powerdnsadmindb to powerdnsadmin; -``` - -In your `config.py` file, make sure you have -``` -SQLALCHEMY_DATABASE_URI = 'postgresql://powerdnsadmin:powerdnsadmin@127.0.0.1/powerdnsadmindb' -``` - -Note: -- Please change the information above (db, user, password) to fit your setup. -- You might need to adjust your PostgreSQL's `pg_hba.conf` config file to allow password authentication for networks. - -### Use Docker -``` -docker run --name pdnsadmin-test -e BIND_ADDRESS=0.0.0.0 --e SECRET_KEY='a-very-secret-key' --e PORT='9191' --e SQLA_DB_USER='powerdns_admin_user' --e SQLA_DB_PASSWORD='exceptionallysecure' --e SQLA_DB_HOST='192.168.0.100' --e SQLA_DB_NAME='powerdns_admin_test' --v /data/node_modules:/var/www/powerdns-admin/node_modules -d -p 9191:9191 ixpict/powerdns-admin-pgsql:latest -``` \ No newline at end of file diff --git a/docs/wiki/web-server/Running-PowerDNS-Admin-with-Systemd,-Gunicorn--and--Nginx.md b/docs/wiki/web-server/Running-PowerDNS-Admin-with-Systemd-Gunicorn-and-Nginx.md similarity index 100% rename from docs/wiki/web-server/Running-PowerDNS-Admin-with-Systemd,-Gunicorn--and--Nginx.md rename to docs/wiki/web-server/Running-PowerDNS-Admin-with-Systemd-Gunicorn-and-Nginx.md