Documentation updates

docs/development/integrating-services.md

@@ -161,38 +161,6 @@ The service should iterate through all of its recorded users and update their gr
 
 I'm really not sure when this is called, it may have been a hold over from before signals started to be used. Regardless, it can be useful to server admins who may call this from a Django shell to force a synchronisation of all user groups for a specific service.
 
-#### service_enabled_members
-`def service_enabled_members(self):`
-
-Is this service enabled for users with the `Member` state? It should return `True` if the service is enabled for Members, and `False` otherwise. The default is `False`.
-
-An implementation will usually look like:
-
-    def service_enabled_members(self):
-        return settings.ENABLE_AUTH_EXAMPLE or False
-        
-        
-```eval_rst
-.. note::
-    There has been discussion about moving services to permissions based access. You should review `Issue #663 <https://github.com/allianceauth/allianceauth/issues/663/>`_.
-```
-
-#### service_enabled_blues
-`def service_enabled_blues(self):`
-
-Is this service enabled for users with the `Blue` state? It should return `True` if the service is enabled for Blues, and `False` otherwise. The default is `False`.
-
-An implementation will usually look like:
-
-    def service_enabled_blues(self):
-        return settings.ENABLE_BLUE_EXAMPLE or False
-        
-        
-```eval_rst
-.. note::
-    There has been discussion about moving services to permissions based access. You should review `Issue #663 <https://github.com/allianceauth/allianceauth/issues/663/>`_.
-```
-
 #### service_active_for_user
 `def service_active_for_user(self, user):`
 
@@ -200,11 +168,6 @@ Is this service active for the given user? The `user` parameter should be a Djan
 
 Usually you wont need to override this as it calls `service_enabled_members` or `service_enabled_blues` depending on the users state.
 
-```eval_rst
-.. note::
-    There has been discussion about moving services to permissions based access. You should review `Issue #663 <https://github.com/allianceauth/allianceauth/issues/663/>`_ as this function will likely need to be defined by each service to check its permission.
-```
-
 #### show_service_ctrl
 `def show_service_ctrl(self, user, state):`
 

docs/installation/auth/centos.md

@@ -39,40 +39,34 @@ AllianceAuth needs a MySQL user account. Create one as follows, replacing `PASSW
     CREATE USER 'allianceserver'@'localhost' IDENTIFIED BY 'PASSWORD';
     GRANT ALL PRIVILEGES ON * . * TO 'allianceserver'@'localhost';
 
-Now we need to make the requisite databases.
+Now we need to make the requisite database.
 
     create database alliance_auth;
-    create database alliance_forum;
-    create database alliance_jabber;
-    create database alliance_mumble;
-    create database alliance_killboard;
 
-Ensure you are in the allianceserver home directory by issuing `cd`
+Create a Python virtual environment and put it somewhere convenient (e.g. ~/venv/aauth/)
 
-Now we clone the source code:
+    python3 -m venv /path/to/new/virtual/environment
 
-    git clone https://github.com/allianceauth/allianceauth.git
+A virtual environment provides support for creating a lightweight "copy" of Python with their own site directories. Each virtual environment has its own Python binary (allowing creation of environments with various Python versions) and can have its own independent set of installed Python packages in its site directories. You can read more about virtual environments on the [Python docs](https://docs.python.org/3/library/venv.html).
+    
+Activate the virtualenv using `source /path/to/new/virtual/environment/bin/activate`. Note the `/bin/activate` on the end of the path. Each time you come to do maintenance on your Alliance Auth installation, you should activate your virtual environment first.
 
-Enter the folder by issuing `cd allianceauth`
+Now you can install the library using `pip install allianceauth`. This will install Alliance Auth and all its python dependencies.
 
-Ensure you're on the latest version with the following:
+Ensure you are in the allianceserver home directory by issuing `cd allianceauth`.
 
-    git tag | sort -n | tail -1 | xargs git checkout
+Now you need to create the application that will run the Alliance Auth install.
 
-Python package dependencies can be installed from the requirements file:
+Issue `django-admin startproject myauth` to bootstrap the Django application that will run Auth. You can rename it from `myauth` anything you'd like, the name is not important for auth.
 
-    sudo pip install -r requirements.txt
+Grab the example settings file from the [Alliance Auth repository](https://github.com/allianceauth/allianceauth/blob/master/alliance_auth/settings.py.example) for the relevant version you're installing.
 
-The settings file needs configuring. See this lengthy guide for specifics.
+The settings file needs configuring. See [this lengthy guide](settings.md) for specifics.
 
 Django needs to install models to the database before it can start.
 
     python manage.py migrate
 
-AllianceAuth needs to generate corp and alliance models before it can assign users to them.
-
-    python manage.py shell < run_alliance_corp_update.py
-
 Now we need to round up all the static files required to render templates. Answer ‘yes’ when prompted.
 
     python manage.py collectstatic
@@ -81,4 +75,6 @@ Test the server by starting it manually.
 
     python manage.py runserver 0.0.0.0:8000
 
-If you see an error, stop, read it, and resolve it. If the server comes up and you can access it at `yourip:8000`, you're golden. It's ok to stop the server if you're going to be installing apache.
+If you see an error, stop, read it, and resolve it. If the server comes up and you can access it at `yourip:8000`, you're golden. It's ok to stop the server if you're going to be installing a WSGI server to run it. **Do not use runserver in production!**
+
+Once installed, move onto the [Gunicorn Guide](gunicorn.md) and decide on whether you're going to use [NGINX](nginx.md) or [Apache](apache.md). You will also need to install [supervisor](supervisor.md) to run the background tasks.

docs/installation/auth/dependencies.md

@@ -2,37 +2,22 @@
 
 ## Ubuntu
 
-Tested on Ubuntu 12, 14, 15, and 16. Package names and repositories may vary.
+Tested on Ubuntu 14.04LTS, 16.04LTS and 17.04. Package names and repositories may vary. Please note that 14.04LTS comes with Python 3.4 which may be insufficient.
 
 ### Core
 Required for base auth site
 
 #### Python
 
-    python python-dev python-mysqldb python-setuptools python-mysql.connector python-pip
+    python3 python3-dev python3-mysqldb python3-setuptools python3-mysql.connector python3-pip
 
 #### MySQL
 
-    mysql-server mysql-client libmysqlclient-dev
+    mariadb-server mysql-client libmysqlclient-dev
 
 #### Utilities
 
-    screen unzip git redis-server curl libssl-dev libbz2-dev libffi-dev
+    unzip git redis-server curl libssl-dev libbz2-dev libffi-dev
-
-### Apache
-Required for displaying web content
-
-    apache2 libapache2-mod-php5 libapache2-mod-wsgi
-
-### PHP
-Required for phpBB, smf, evernus alliance market, etc
-
-    php5 php5-gd php5-mysqlnd php5-curl php5-gd php5-intl php-pear php5-imagick php5-imap php5-mcrypt php5-memcache php5-ming php5-ps php5-pspell php5-recode php5-snmp php5-sqlite php5-tidy php5-xmlrpc php5-xsl
-
-### Java
-Required for hosting jabber server
-
-    oracle-java8-installer
 
 ## CentOS 7
 
@@ -54,19 +39,4 @@ Required for base auth site
 
 #### Utilities
 
-    screen gcc gcc-c++ unzip git redis curl nano
+    gcc gcc-c++ unzip git redis curl nano
-
-### Apache
-Required for displaying web content
-
-    httpd mod_wsgi
-
-### PHP
-Required for phpBB, smf, evernus alliance market, etc
-
-    php php-gd php-mysqlnd php-intl php-pear ImageMagick php-imap php-mcrypt php-memcache php-pspell php-recode php-snmp php-pdo php-tidy php-xmlrpc
-
-### Java
-Required for hosting jabber server
-
-    java libstdc++.i686

docs/installation/auth/quickstart.md

@@ -4,11 +4,8 @@ Once you’ve installed AllianceAuth, perform these steps to get yourself up and
 
 First you need a superuser account. You can use this as a personal account. From the command line, `python manage.py createsuperuser` and follow the prompts.
 
-The big goal of AllianceAuth is the automation of group membership, so we’ll need some groups. In the admin interface, select `Groups`, then at the top-right select `Add Group`. Give it a name and select permissions. Special characters (including spaces) are removing before syncing to services, so try not to have group names which will be the same upon cleaning. A description of permissions can be found in the [readme file](https://github.com/allianceauth/allianceauth/blob/master/README.md). Repeat for all the groups you see fit, whenever you need a new one.
+The big goal of AllianceAuth is the automation of group membership, so we’ll need some groups. In the admin interface, select `Groups`, then at the top-right select `Add Group`. Give it a name and select permissions. Special characters (including spaces) are removing before syncing to services, so try not to have group names which will be the same upon cleaning. Repeat for all the groups you see fit, whenever you need a new one. Check the [groups documentation](../../features/groups.md) for more details on group configuration.
 
 ### Background Processes
 
-To start the background processes to sync groups and check api keys, issue these commands:
+To start the background processes you should utilise [supervisor](supervisor.md). Previously screen was suggested to keep these tasks running, however this is no longer the preferred method.
-
-    screen -dm bash -c 'celery -A alliance_auth worker'
-    screen -dm bash -c 'celery -A alliance_auth beat'

docs/installation/auth/ubuntu.md

@@ -6,7 +6,7 @@ It’s recommended to update all packages before proceeding.
     sudo apt-get upgrade
     sudo reboot
 
-Now install all [dependencies](dependencies.md). For this guide you'll need the optional [Apache section](dependencies.md) as well.
+Now install all [dependencies](dependencies.md).
 
     sudo apt-get install xxxxxxx
 replacing the xs with the list of packages.
@@ -29,28 +29,28 @@ AllianceAuth needs a MySQL user account. Create one as follows, replacing `PASSW
     CREATE USER 'allianceserver'@'localhost' IDENTIFIED BY 'PASSWORD';
     GRANT ALL PRIVILEGES ON * . * TO 'allianceserver'@'localhost';
 
-Now we need to make the requisite databases.
+Now we need to make the requisite database.
 
     create database alliance_auth;
-    create database alliance_forum;
+    
-    create database alliance_jabber;
+    
-    create database alliance_mumble;
+Create a Python virtual environment and put it somewhere convenient (e.g. ~/venv/aauth/)
 
-Ensure you are in the allianceserver home directory by issuing `cd`
+    python3 -m venv /path/to/new/virtual/environment
 
-Now we clone the source code:
+A virtual environment provides support for creating a lightweight "copy" of Python with their own site directories. Each virtual environment has its own Python binary (allowing creation of environments with various Python versions) and can have its own independent set of installed Python packages in its site directories. You can read more about virtual environments on the [Python docs](https://docs.python.org/3/library/venv.html).
+    
+Activate the virtualenv using `source /path/to/new/virtual/environment/bin/activate`. Note the `/bin/activate` on the end of the path. Each time you come to do maintenance on your Alliance Auth installation, you should activate your virtual environment first.
 
-    git clone https://github.com/allianceauth/allianceauth.git
+Now you can install the library using `pip install allianceauth`. This will install Alliance Auth and all its python dependencies.
 
-Enter the folder by issuing `cd allianceauth`
+Ensure you are in the allianceserver home directory by issuing `cd allianceauth`.
 
-Ensure you're on the latest version with the following:
+Now you need to create the application that will run the Alliance Auth install.
 
-    git tag | sort -n | tail -1 | xargs git checkout
+Issue `django-admin startproject myauth` to bootstrap the Django application that will run Auth. You can rename it from `myauth` anything you'd like, the name is not important for auth.
 
-Python package dependencies can be installed from the requirements file:
+Grab the example settings file from the [Alliance Auth repository](https://github.com/allianceauth/allianceauth/blob/master/alliance_auth/settings.py.example) for the relevant version you're installing.
-
-    sudo pip install -r requirements.txt
 
 The settings file needs configuring. See [this lengthy guide](settings.md) for specifics.
 
@@ -58,10 +58,6 @@ Django needs to install models to the database before it can start.
 
     python manage.py migrate
 
-AllianceAuth needs to generate corp and alliance models before it can assign users to them.
-
-    python manage.py shell < run_alliance_corp_update.py
-
 Now we need to round up all the static files required to render templates. Answer ‘yes’ when prompted.
 
     python manage.py collectstatic
@@ -70,6 +66,6 @@ Test the server by starting it manually.
 
     python manage.py runserver 0.0.0.0:8000
 
-If you see an error, stop, read it, and resolve it. If the server comes up and you can access it at `yourip:8000`, you're golden. It's ok to stop the server if you're going to be installing apache.
+If you see an error, stop, read it, and resolve it. If the server comes up and you can access it at `yourip:8000`, you're golden. It's ok to stop the server if you're going to be installing a WSGI server to run it. **Do not use runserver in production!**
 
-Once installed, follow the [Quick Start Guide](quickstart.md)
+Once installed, move onto the [Gunicorn Guide](gunicorn.md) and decide on whether you're going to use [NGINX](nginx.md) or [Apache](apache.md). You will also need to install [supervisor](supervisor.md) to run the background tasks.

docs/installation/services/discord.md

@@ -4,7 +4,7 @@ Discord is a web-based instant messaging client with voice. Kind of like teamspe
 
 ## Setup
 
-Add `services.modules.discord` to your `INSTALLED_APPS` list and run migrations before continuing with this guide to ensure the service is installed.
+Add `allianceauth.services.modules.discord` to your `INSTALLED_APPS` list and run migrations before continuing with this guide to ensure the service is installed.
 
 ### Creating a Server
 *If you already have a Discord server, skip the creation step, but be sure to retrieve the server ID and enter it in settings.py*

docs/installation/services/discourse.md

@@ -1,6 +1,6 @@
 # Discourse
 
-Add `services.modules.discourse` to your `INSTALLED_APPS` list and run migrations before continuing with this guide to ensure the service is installed.
+Add `allianceauth.services.modules.discourse` to your `INSTALLED_APPS` list and run migrations before continuing with this guide to ensure the service is installed.
 
 ## Install Docker
 

docs/installation/services/jacknife.md

@@ -1,71 +0,0 @@
-# Eve Jacknife
-
-## Overview
-Eve Jacknife is used to audit an api so that you might see character skills and what ships they can fly, mails, contracts,assets, and any other given access from a specific api key.
-
-## Dependencies
-All php and mysql dependencies should have been taken care of during setup.
-
-## Installation
-### Get Code
-Navigate to your server's web directory: `cd /var/www`
-
-Download the code: `sudo git clone https://github.com/whinis/eve-jacknife`
-
-### Create Database
-
-    mysql -u root -p -e "create database jackknife; grant all privileges on jackknife.* to 'allianceserver'@'localhost';"
-
-### Configure Settings
-
-Change directory to jacknife: `cd eve-jacknife`
-
-Now copy the template: `sudo cp base.config.php eve.config.php`
-
-And now edit: `sudo nano eve.config.php`
-
-Add the database user information:
- - `$sql_u = "allianceserver"`
- - `$sql_p = "MY_SQL_PASSWORD_HERE"`
-
-## Apache Configuration
-
-Change ownership of the directory: `sudo chown -R www-data:www-data ../eve-jacknife`
-
-Eve Jacknife can be served two ways: on its own subdomain (`jacknife.example.com`) or as an alias (`example.com/jacknife`)
-
-### Subdomain
-As its own subdomain, create a new apache config: `sudo nano /etc/apache2/sites-available/jacknife.conf` and enter the following:
-
-    <VirtualHost *:80>
-            DocumentRoot "/var/www/eve-jacknife"
-            ServerName jacknife.example.com
-            <Directory "/var/www/eve-jacknife">
-                    Require all granted
-                    AllowOverride all
-                    DirectoryIndex index.php
-            </Directory>
-    </VirtualHost>
-
-Enable the new site with `sudo a2ensite jacknife.conf` and then reload apache with `sudo service apache2 reload`
-
-### Alias
-As an alias, edit your site config (usually 000-default): `sudo nano etc/apache2/sites-available/000-default.conf` and add the following inside the `VirtualHost` block:
-
-    Alias /jacknife "/var/www/eve-jacknife/"
-    <Directory "/var/www/eve-jacknife">
-            Require all granted
-            DirectoryIndex index.php
-    </Directory>
-
-Reload apache to take effect: `sudo service apache2 reload`
-
-## Install SQL
-
-Once apache is configured, Eve Jacknife needs to install some data. Navigate to it in your browser and append `/Installer.php` to the URL.
-
-Enter your database password and press Check. If all the boxes come back green press Save. On the next screen press Install and wait for it to finish.
-
-## Update Auth Settings
-
-Edit your aut settings file (`nano ~/allianceauth/alliance_auth/settings.py`) and replace `API_KEY_AUDIT_URL` with either `http://jacknife.example.com/?usid={api_id}&apik={vcode}` or `http://example.com/jacknife/?usid={api_id}&apik={vcode}` depending on your apache choice.

docs/installation/services/market.md

@@ -1,6 +1,6 @@
 # Alliance Market
 
-Add `services.modules.market` to your `INSTALLED_APPS` list and run migrations before continuing with this guide to ensure the service is installed.
+Add `allianceauth.services.modules.market` to your `INSTALLED_APPS` list and run migrations before continuing with this guide to ensure the service is installed.
 
 Alliance Market needs a database. Create one in mysql. Default name is `alliance_market`:
 

docs/installation/services/mumble.md

@@ -1,6 +1,6 @@
 # Mumble
 
-Add `services.modules.mumble` to your `INSTALLED_APPS` list and run migrations before continuing with this guide to ensure the service is installed.
+Add `allianceauth.services.modules.mumble` to your `INSTALLED_APPS` list and run migrations before continuing with this guide to ensure the service is installed.
 
 ## Overview
 Mumble is a free voice chat server. While not as flashy as teamspeak, it has all the functionality and is easier to customize. And is better. I may be slightly biased.
@@ -73,11 +73,7 @@ Test your configuration by starting it: `python authenticator.py`
 
 ## Running the Authenticator
 
-The authenticator needs to be running 24/7 to validate users on Mumble. The best way is to run it in a screen much like celery:
+The authenticator needs to be running 24/7 to validate users on Mumble. You should check the [supervisor docs](../auth/supervisor.md) on how to achieve this.
-
-    screen -dm bash -c 'python authenticator.py'
-
-Much like celery tasks, this process needs to be started every time the server reboots. It needs to be launched from this directory, so cd to this folder to launch.
 
 Note that groups will only be created on Mumble automatically when a user joins who is in the group.
 

docs/installation/services/openfire.md

@@ -1,6 +1,6 @@
 # Openfire
 
-Add `services.modules.openfire` to your `INSTALLED_APPS` list and run migrations before continuing with this guide to ensure the service is installed.
+Add `allianceauth.services.modules.openfire` to your `INSTALLED_APPS` list and run migrations before continuing with this guide to ensure the service is installed.
 
 ## Overview
 Openfire is a java-based xmpp server (jabber).

docs/installation/services/pathfinder.md

@@ -1,77 +0,0 @@
-# Pathfinder
-Pathfinder is a wormhole mapping tool.
-
-While auth doesn't integrate with pathfinder anymore, from personal experience I've found it much easier to use the following install process than to try and follow the pathfinder-supplied docs.
-
-
-## Installation
-### Get the code
-
-Navigate to the install location: `cd /var/www/` and git clone the repo: 
-
-    sudo git clone https://github.com/exodus4d/pathfinder.git
-
-### Create logs and caches
-
-Change directory to pathfinder: `cd pathfinder`
-
-The logging and caching folders need to be created and have permission set. If upon installation you get Server Error 500, try resetting these permissions.
-
-    sudo mkdir logs
-    sudo mkdir tmp/cache
-    sudo chmod -R 766 logs
-    sudo chmod -R 766 tmp/cache
-
-## .htaccess Configuration
-
-In your `pathfinder` directory there are two `.htaccess` files. The default installation instructions want you to choose one for rewriting purposes, and these force you to www.pathfinder.example.com. Personally I don't like that.
-
-So we'll frankenstein our own. We'll use the HTTP one as a base: 
-
-    sudo mv .htaccess .htaccess_HTTPS
-    sudo mv .htaccess_HTTPS .htaccess
-    sudo nano .htaccess
-
-Find the www rewriting section (labelled `Rewrite NONE www. to force www.`). Change it so that all lines start with a `#`:
-
-    #RewriteCond %{HTTP_HOST} !^www\.
-    # skip "localhost" (dev environment)...
-    #RewriteCond %{HTTP_HOST} !=localhost
-    # skip IP calls (dev environment) e.g. 127.0.0.1
-    #RewriteCond %{HTTP_HOST} !^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}$
-    # rewrite everything else to "http://" and "www."
-    #RewriteRule .* http://www.%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
-
-This allows us to choose SSL and www forwarding with our apache conf instead of this htaccess file.
-
-## Apache Configuration
-The best way to have this is to setup a subdomain on your server.
-
-Create a config file `sudo nano /etc/apache2/sites-available/pathfinder.conf` and enter [this configuration](http://pastebin.com/wmXyf6pN), being sure to edit the `ServerName`
-
-Enable it with:
-
-    sudo a2ensite pathfinder.conf
-    sudo service apache2 reload
-
-## Configuration Files 
-
-The default configuration should be fine in most cases. Edit all values with caution!
-
-environment.ini
- - `SERVER` Should be changed to `PRODUCTION`
- - `BASE`  is the full filesystem path to the application root on your server. In our case, `/var/www/pathfinder/`
- - `URL`  Is the URL to your app (without a trailing slash). In our case, `http://pathfinder.example.com`
- - `DEBUG` sets the level of debugging (1,2 or 3) (check  /logs  for a more detail backtrace information) 
- - `DB_*` sets your DB connection information 
- - `SMTP_*`  are used to send out emails, you will need an SMTP server login to make this work. (not required)
- - `SSO_CCP_*` follow the [official docs](https://github.com/exodus4d/pathfinder/wiki/CREST)
-
-## Database Setup
-This is done through the browser. Go to `pathfinder.example.com/setup` and see the [official docs](https://github.com/exodus4d/pathfinder/wiki/Database) for instructions.
-
-## Cron Jobs 
-Again the [official docs](https://github.com/exodus4d/pathfinder/wiki/Cronjob) do a good job here.
-
-## Finish Setup
-Once you've compelted the above steps, we need to disable the setup page. Edit the routes with `nano app/routes.ini` and put a `;` in front of the line starting with `GET @setup`

docs/installation/services/phpbb3.md

@@ -1,6 +1,6 @@
 # phpBB3
 
-Add `services.modules.phpbb3` to your `INSTALLED_APPS` list and run migrations before continuing with this guide to ensure the service is installed.
+Add `allianceauth.services.modules.phpbb3` to your `INSTALLED_APPS` list and run migrations before continuing with this guide to ensure the service is installed.
 
 ## Overview
 phpBB is a free php-based forum. It’s the default forum for AllianceAuth.

docs/installation/services/smf.md

@@ -1,6 +1,6 @@
 # SMF
 
-Add `services.modules.smf` to your `INSTALLED_APPS` list and run migrations before continuing with this guide to ensure the service is installed.
+Add `allianceauth.services.modules.smf` to your `INSTALLED_APPS` list and run migrations before continuing with this guide to ensure the service is installed.
 
 ## Overview
 SMF is a free php-based forum. It’s the one of the forums for AllianceAuth.

docs/installation/services/teamspeak3.md

@@ -1,6 +1,6 @@
 # Teamspeak 3
 
-Add `services.modules.teamspeak3` to your `INSTALLED_APPS` list and run migrations before continuing with this guide to ensure the service is installed.
+Add `allianceauth.services.modules.teamspeak3` to your `INSTALLED_APPS` list and run migrations before continuing with this guide to ensure the service is installed.
 
 ## Overview
 Teamspeak3 is the most popular VOIP program for gamers.

docs/installation/services/xenforo.md

@@ -1,6 +1,6 @@
 # XenForo
 
-Add `services.modules.xenforo` to your `INSTALLED_APPS` list and run migrations before continuing with this guide to ensure the service is installed.
+Add `allianceauth.services.modules.xenforo` to your `INSTALLED_APPS` list and run migrations before continuing with this guide to ensure the service is installed.
 
 In this chapter we will explore how to setup AllianceAuth to work with [XenForo](https://xenforo.com/). At this point we will assume that you already have XenForo installed with a valid license (please keep in mind that XenForo is not free nor open-source, therefore you need to purchase a license first). If you come across any problems related with the installation of XenForo please contact their support service.