Merge pull request #1302 from dmcken/setup-new-wiki-docs-2

Setup new wiki docs #2

docs/wiki/README.md

@@ -1,23 +1,43 @@
 # Welcome to the PowerDNS-Admin wiki!
 
-## Preparation guides
+## Database Setup guides:
-- [Prepare MySQL or MariaDB Database for PowerDNS-Admin](preparation/Prepare-MySQL-or-MariaDB-Database-for-PowerDNS-Admin.md)
+- [MySQL / MariaDB](database-setup/Setup-MySQL-or-MariaDB.md)
-- [Using PowerDNS-Admin with PostgreSQL](preparation/Using-PowerDNS-Admin-with-PostgreSQL.md)
+- [PostgreSQL](database-setup/Setup-PostgreSQL.md)
 
-## Installation guides
+## Installation guides:
-- [Running PowerDNS Admin on Ubuntu or Debian](install/Running-PowerDNS-Admin-on-Ubuntu-or-Debian.md)
+- [General (Read this first)](install/General.md)
-- [Running PowerDNS-Admin on Centos 7](install/Running-PowerDNS-Admin-on-Centos-7.md)
+  - BSD:
-- [Running PowerDNS-Admin on Fedora 23](install/Running-PowerDNS-Admin-on-Fedora-23.md)
+    - [Install on FreeBSD 12.1-RELEASE](install/Running-on-FreeBSD.md)
-- [Running PowerDNS-Admin on Fedora 30](install/Running-PowerDNS-Admin-on-Fedora-30.md)
+  - Containers:
-- [Running PowerDNS-Admin on FreeBSD 12.1-RELEASE](install/Running-on-FreeBSD.md)
+    - [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
+- <whatever else>
+
 ## Feature usage
 - [DynDNS2](features/DynDNS2.md)

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)

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.

docs/wiki/database-setup/README.md

@@ -0,0 +1,4 @@
+# Database setup guides
+
+- [MySQL / MariaDB](Setup-MySQL-or-MariaDB.md)
+- [PostgreSQL](Setup-PostgreSQL.md)

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;
+```

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/<version>/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
+```

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.

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
+```

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

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**
+### Install NodeJs
-
-```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**
 
 ```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.
+
+From here you can now follow the [Getting started guide](../configuration/Getting-started.md).

docs/wiki/preparation/Prepare-MySQL-or-MariaDB-Database-for-PowerDNS-Admin.md

@@ -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;`

docs/wiki/preparation/Using-PowerDNS-Admin-with-PostgreSQL.md

@@ -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
-```