Merge pull request #891 from Adarnof/sso_registration

Install using project template

.coveragerc

@@ -6,6 +6,8 @@ source =
 omit =
     */migrations/*
     */example/*
+    */project_template/*
+    */bin/*
 
 [report]
 exclude_lines =

allianceauth/authentication/tasks.py

@@ -4,7 +4,7 @@ from esi.errors import TokenExpiredError, TokenInvalidError
 from esi.models import Token
 
 from allianceauth.authentication.models import CharacterOwnership
-from allianceauth.celeryapp import app
+from allianceauth.celery import app
 
 logger = logging.getLogger(__name__)
 

allianceauth/bin/allianceauth.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python
+import os
+import sys
+from optparse import OptionParser
+from django.core.management import ManagementUtility
+
+
+def create_project(parser, options, args):
+    # Validate args
+    if len(args) < 2:
+        parser.error("Please specify a name for your Alliance Auth installation")
+    elif len(args) > 3:
+        parser.error("Too many arguments")
+
+    project_name = args[1]
+    try:
+        dest_dir = args[2]
+    except IndexError:
+        dest_dir = None
+
+    # Make sure given name is not already in use by another python package/module.
+    try:
+        __import__(project_name)
+    except ImportError:
+        pass
+    else:
+        parser.error("'%s' conflicts with the name of an existing "
+                     "Python module and cannot be used as a project "
+                     "name. Please try another name." % project_name)
+
+    print("Creating an Alliance Auth project called %(project_name)s" % {'project_name': project_name})  # noqa
+
+    # Create the project from the Alliance Auth template using startapp
+
+    # First find the path to Alliance Auth
+    import allianceauth
+    allianceauth_path = os.path.dirname(allianceauth.__file__)
+    template_path = os.path.join(allianceauth_path, 'project_template')
+
+    # Call django-admin startproject
+    utility_args = ['django-admin.py',
+                    'startproject',
+                    '--template=' + template_path,
+                    '--pythonpath=' + '/'.join(sys.executable.split('/')[:-1]),
+                    '--ext=conf',
+                    project_name]
+
+    if dest_dir:
+        utility_args.append(dest_dir)
+
+    utility = ManagementUtility(utility_args)
+    utility.execute()
+
+    print("Success! %(project_name)s has been created" % {'project_name': project_name})  # noqa
+
+
+def update_settings(parser, options, args):
+    if len(args) < 2:
+        parser.error("Please specify the path to your Alliance Auth installation")
+    elif len(args) > 2:
+        parser.error("Too many arguments")
+
+    project_path = args[1]
+
+    # find the target settings/base.py file, handing both the project and app as valid paths
+    try:
+        # given path is to the app
+        settings_path = os.path.join(project_path, 'settings/base.py')
+        assert os.path.exists(settings_path)
+    except AssertionError:
+        try:
+            # given path is to the project, so find the app within it
+            dirname = os.path.split(project_path)[-1]
+            settings_path = os.path.join(project_path, dirname, 'settings/base.py')
+            assert os.path.exists(settings_path)
+        except AssertionError:
+            parser.error("Unable to locate the Alliance Auth project at %s" % project_path)
+
+    # first find the path to the Alliance Auth template settings
+    import allianceauth
+    allianceauth_path = os.path.dirname(allianceauth.__file__)
+    template_path = os.path.join(allianceauth_path, 'project_template')
+    template_settings_path = os.path.join(template_path, 'project_name/settings/base.py')
+
+    # overwrite the local project's base settings
+    print("Updating the settings at %s with the template at %s" % (settings_path, template_settings_path))
+    with open(template_settings_path, 'r') as template, open(settings_path, 'w') as target:
+        target.write(template.read())
+
+    print("Successfully updated Alliance Auth settings.")
+
+
+COMMANDS = {
+    'start': create_project,
+    'update': update_settings,
+}
+
+
+def main():
+    # Parse options
+    parser = OptionParser(usage="Usage: %prog [start|update] project_name [directory]")
+    (options, args) = parser.parse_args()
+
+    # Find command
+    try:
+        command = args[0]
+    except IndexError:
+        parser.print_help()
+        return
+
+    if command in COMMANDS:
+        COMMANDS[command](parser, options, args)
+    else:
+        parser.error("Unrecognised command: " + command)
+
+
+if __name__ == "__main__":
+    main()

allianceauth/celery.py

@@ -0,0 +1,16 @@
+import os
+from celery import Celery
+
+# set the default Django settings module for the 'celery' program.
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'allianceauth.project_template.project_name.settings.base')
+
+from django.conf import settings  # noqa
+
+app = Celery('alliance_auth')
+
+# Using a string here means the worker don't have to serialize
+# the configuration object to child processes.
+app.config_from_object('django.conf:settings')
+
+# Load task modules from all registered Django app configs.
+app.autodiscover_tasks(lambda: settings.INSTALLED_APPS)

allianceauth/corputils/tasks.py

@@ -1,4 +1,4 @@
-from allianceauth.celeryapp import app
+from allianceauth.celery import app
 from allianceauth.corputils import CorpStats
 
 

allianceauth/eveonline/tasks.py

@@ -1,6 +1,6 @@
 import logging
 
-from allianceauth.celeryapp import app
+from allianceauth.celery import app
 from .models import EveAllianceInfo
 from .models import EveCharacter
 from .models import EveCorporationInfo

allianceauth/log/.gitignore

@@ -1,2 +0,0 @@
-!.gitignore
-*

allianceauth/project_template/celeryapp.py

@@ -2,11 +2,11 @@ import os
 from celery import Celery
 
 # set the default Django settings module for the 'celery' program.
-os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'alliance_auth.settings')
+os.environ.setdefault('DJANGO_SETTINGS_MODULE', '{{ project_name }}.settings.local')
 
 from django.conf import settings  # noqa
 
-app = Celery('alliance_auth')
+app = Celery('{{ project_name }}')
 
 # Using a string here means the worker don't have to serialize
 # the configuration object to child processes.

allianceauth/project_template/manage.py

@@ -0,0 +1,22 @@
+#!/usr/bin/env python
+import os
+import sys
+
+if __name__ == "__main__":
+    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "{{ project_name}}.settings.local")
+    try:
+        from django.core.management import execute_from_command_line
+    except ImportError:
+        # The above import may fail for some other reason. Ensure that the
+        # issue is really that Django is missing to avoid masking other
+        # exceptions on Python 2.
+        try:
+            import django
+        except ImportError:
+            raise ImportError(
+                "Couldn't import Django. Are you sure it's installed and "
+                "available on your PYTHONPATH environment variable? Did you "
+                "forget to activate a virtual environment?"
+            )
+        raise
+    execute_from_command_line(sys.argv)

allianceauth/project_template/project_name/settings/base.py

@@ -61,7 +61,8 @@ CELERYBEAT_SCHEDULE = {
 }
 
 # Build paths inside the project like this: os.path.join(BASE_DIR, ...)
-BASE_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+PROJECT_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+BASE_DIR = os.path.dirname(PROJECT_DIR)
 
 MIDDLEWARE = [
     'django.middleware.security.SecurityMiddleware',
@@ -149,7 +150,6 @@ USE_TZ = True
 # https://docs.djangoproject.com/en/1.10/howto/static-files/
 
 STATIC_URL = '/static/'
-STATIC_ROOT = os.path.join(BASE_DIR, "static")
 
 # Bootstrap messaging css workaround
 MESSAGE_TAGS = {
@@ -172,7 +172,7 @@ ALLOWED_HOSTS = ['*']
 DATABASES = {
     'default': {
         'ENGINE': 'django.db.backends.sqlite3',
-        'NAME': str(os.path.join(BASE_DIR, 'alliance_auth.sqlite')),
+        'NAME': str(os.path.join(BASE_DIR, 'alliance_auth.sqlite3')),
     },
 }
 
@@ -255,14 +255,3 @@ LOGGING = {
         },
     }
 }
-
-
-def add_auth_apps(APPS):
-    """
-    Merges required auth apps with a list of custom user apps for project settings.
-    Leaves order of passed INSTALLED_APPS unchanged (passed apps come first) to allow overriding templates/static/etc
-    https://docs.djangoproject.com/en/2.0/ref/settings/#installed-apps
-    :param APPS: INSTALLED_APPS list
-    :return: Merged INSTALLED_APPS
-    """
-    APPS += [app for app in INSTALLED_APPS if app not in APPS]

allianceauth/project_template/project_name/settings/local.py

@@ -0,0 +1,68 @@
+from .base import *
+
+# These are required for Django to function properly
+ROOT_URLCONF = '{{ project_name }}.urls'
+WSGI_APPLICATION = '{{ project_name }}.wsgi.application'
+STATICFILES_DIRS = [
+    os.path.join(PROJECT_DIR, 'static'),
+]
+STATIC_ROOT = "/var/www/{{ project_name }}/static/"
+TEMPLATES[0]['DIRS'] += [os.path.join(PROJECT_DIR, 'templates')]
+SECRET_KEY = '{{ secret_key }}'
+
+# Change this to change the name of the auth site
+SITE_NAME = '{{ project_name }}'
+
+# Change this to enable/disable debug mode
+DEBUG = False
+
+#######################################
+#         Database Settings           #
+#######################################
+# Uncomment and change the database name
+# and credentials to use MySQL/MariaDB.
+# Leave commented to use sqlite3
+#######################################
+"""
+DATABASES['default'] = {
+    'ENGINE': 'django.db.backends.mysql',
+    'NAME': 'alliance_auth',
+    'USER': os.environ.get('AA_DB_DEFAULT_USER', ''),
+    'PASSWORD': os.environ.get('AA_DB_DEFAULT_PASSWORD', ''),
+    'HOST': os.environ.get('AA_DB_DEFAULT_HOST', '127.0.0.1'),
+    'PORT': os.environ.get('AA_DB_DEFAULT_PORT', '3306'),
+}
+"""
+
+######################################
+#            SSO Settings            #
+######################################
+# Register an application at
+# https://developers.eveonline.com
+# and fill out these settings.
+# Be sure to set the callback URL to
+# https://example.com/sso/callback
+# substituting your domain for example.com
+######################################
+ESI_SSO_CLIENT_ID = ''
+ESI_SSO_CLIENT_SECRET = ''
+ESI_SSO_CALLBACK_URL = ''
+
+######################################
+#           Email Settings           #
+######################################
+# Alliance Auth validates emails before
+# new users can log in.
+# It's recommended to use a free service
+# like SparkPost or Mailgun to send email.
+# https://www.sparkpost.com/docs/integrations/django/
+#################
+EMAIL_HOST = ''
+EMAIL_PORT = 587
+EMAIL_HOST_USER = ''
+EMAIL_HOST_PASSWORD = ''
+EMAIL_USE_TLS = True
+
+######################################
+# Add any custom settings below here #
+######################################

allianceauth/project_template/project_name/urls.py

@@ -0,0 +1,6 @@
+from django.conf.urls import include, url
+from allianceauth import urls
+
+urlpatterns = [
+    url(r'', include(urls)),
+]

allianceauth/project_template/project_name/wsgi.py

@@ -0,0 +1,14 @@
+"""
+WSGI config for {{ project_name }} project.
+It exposes the WSGI callable as a module-level variable named ``application``.
+For more information on this file, see
+https://docs.djangoproject.com/en/{{ docs_version }}/howto/deployment/wsgi/
+"""
+
+import os
+
+from django.core.wsgi import get_wsgi_application
+
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "{{ project_name }}.settings.local")
+
+application = get_wsgi_application()

allianceauth/project_template/supervisor.conf

@@ -0,0 +1,36 @@
+[program:beat]
+command={{ pythonpath}}/celery -A {{ project_name }} beat
+directory={{ project_directory }}
+user=allianceserver
+stdout_logfile={{ project_directory }}/log/beat.log
+stderr_logfile={{ project_directory }}/log/beat.log
+autostart=true
+autorestart=true
+startsecs=10
+priority=998
+
+[program:worker]
+command={{ pythonpath}}/celery -A {{ project_name }} worker
+directory={{ project_directory }}
+user=allianceserver
+numprocs=1
+stdout_logfile={{ project_directory }}/log/worker.log
+stderr_logfile={{ project_directory }}/log/worker.log
+autostart=true
+autorestart=true
+startsecs=10
+stopwaitsecs = 600
+killasgroup=true
+priority=998
+
+[program:gunicorn]
+user = allianceserver
+directory={{ project_directory }}
+command={{ pythonpath}}/gunicorn {{ project_name}}.wsgi --workers=3 --timeout 120
+autostart=true
+autorestart=true
+stopsignal=INT
+
+[group:{{ project_name }}]
+programs=beat,worker,gunicorn
+priority=999

allianceauth/services/modules/discord/tasks.py

@@ -5,7 +5,7 @@ from django.contrib.auth.models import User
 from django.core.exceptions import ObjectDoesNotExist
 from allianceauth.notifications import notify
 
-from allianceauth.celeryapp import app
+from allianceauth.celery import app
 from .manager import DiscordOAuthManager, DiscordApiBackoff
 from .models import DiscordUser
 

allianceauth/services/modules/discourse/tasks.py

@@ -3,7 +3,7 @@ import logging
 from django.contrib.auth.models import User
 from django.core.exceptions import ObjectDoesNotExist
 
-from allianceauth.celeryapp import app
+from allianceauth.celery import app
 from allianceauth.notifications import notify
 from .manager import DiscourseManager
 from .models import DiscourseUser

allianceauth/services/modules/mumble/tasks.py

@@ -3,7 +3,7 @@ import logging
 from django.contrib.auth.models import User
 from django.core.exceptions import ObjectDoesNotExist
 
-from allianceauth.celeryapp import app
+from allianceauth.celery import app
 from .manager import MumbleManager
 from .models import MumbleUser
 

allianceauth/services/modules/openfire/tasks.py

@@ -4,7 +4,7 @@ from django.contrib.auth.models import User
 from django.core.exceptions import ObjectDoesNotExist
 from allianceauth.notifications import notify
 
-from allianceauth.celeryapp import app
+from allianceauth.celery import app
 from allianceauth.services.modules.openfire.manager import OpenfireManager
 from .models import OpenfireUser
 

allianceauth/services/modules/phpbb3/tasks.py

@@ -3,7 +3,7 @@ import logging
 from django.contrib.auth.models import User
 from django.core.exceptions import ObjectDoesNotExist
 
-from allianceauth.celeryapp import app
+from allianceauth.celery import app
 from allianceauth.notifications import notify
 from .manager import Phpbb3Manager
 from .models import Phpbb3User

allianceauth/services/modules/seat/tasks.py

@@ -3,7 +3,7 @@ import logging
 from django.contrib.auth.models import User
 from django.core.exceptions import ObjectDoesNotExist
 
-from allianceauth.celeryapp import app
+from allianceauth.celery import app
 from allianceauth.notifications import notify
 from .manager import SeatManager
 from .models import SeatUser

allianceauth/services/modules/smf/tasks.py

@@ -3,7 +3,7 @@ import logging
 from django.contrib.auth.models import User
 from django.core.exceptions import ObjectDoesNotExist
 
-from allianceauth.celeryapp import app
+from allianceauth.celery import app
 from allianceauth.notifications import notify
 from .manager import SmfManager
 from .models import SmfUser

allianceauth/services/modules/teamspeak3/tasks.py

@@ -3,7 +3,7 @@ import logging
 from django.contrib.auth.models import User
 from django.core.exceptions import ObjectDoesNotExist
 
-from allianceauth.celeryapp import app
+from allianceauth.celery import app
 from allianceauth.notifications import notify
 from .manager import Teamspeak3Manager
 from .models import AuthTS, TSgroup, UserTSgroup, Teamspeak3User

allianceauth/services/tasks.py

@@ -2,7 +2,7 @@ import logging
 
 import redis
 
-from allianceauth.celeryapp import app
+from allianceauth.celery import app
 from .hooks import ServicesHook
 
 REDIS_CLIENT = redis.Redis()

allianceauth/wsgi.py

@@ -1,20 +0,0 @@
-"""
-WSGI config for alliance_auth project.
-
-It exposes the WSGI callable as a module-level variable named ``application``.
-
-For more information on this file, see
-https://docs.djangoproject.com/en/1.6/howto/deployment/wsgi/
-"""
-
-import os
-from django.core.wsgi import get_wsgi_application
-
-os.environ.setdefault("DJANGO_SETTINGS_MODULE", "allianceauth.settings.base")
-
-# virtualenv wrapper, uncomment below to activate
-# activate_env=os.path.join(os.path.dirname(os.path.abspath(__file__)), 'env/bin/activate_this.py')
-# execfile(activate_env, dict(__file__=activate_env))
-
-
-application = get_wsgi_application()

docs/installation/auth/allianceauth.md

@@ -0,0 +1,194 @@
+# Alliance Auth Installation
+
+```eval_rst
+.. tip::
+   Installation is easiest as the root user. Log in as root or a user with sudo powers.
+```
+
+## Dependencies
+
+Alliance Auth can be installed on any operating system. Dependencies are provided below for two of the most popular server platforms, Ubuntu and CentOS. To install on your favourite flavour of linux, identify and install equivalent packages to the ones listed here.
+
+```eval_rst
+.. hint::
+   CentOS: A few packages are included in a non-default repository. Add it and update the package lists. ::
+   
+      yum -y install https://centos7.iuscommunity.org/ius-release.rpm
+      yum update
+```
+
+### Python
+
+Alliance Auth requires python3.4 or higher. Ensure it is installed on your server before proceeding.
+
+Ubuntu:
+
+    apt-get install python3 python3-dev python3-venv python3-setuptools python3-pip
+
+CentOS:
+
+    yum install python36u python36u-devel python36u-setuptools python36u-pip
+
+### Database
+
+It's recommended to use a database service instead of sqlite. Many options are available, but this guide will use MariaDB.
+
+Ubuntu:
+
+    apt-get install mariadb-server mysql-client libmysqlclient-dev
+
+CentOS:
+
+    yum install mariadb-server mariadb-devel mariadb
+
+### Redis and Other Tools
+
+A few extra utilities are also required for installation of packages.
+
+Ubuntu:
+
+    apt-get install unzip git redis-server curl libssl-dev libbz2-dev libffi-dev
+
+CentOS:
+
+    yum install gcc gcc-c++ unzip git redis curl bzip2-devel
+
+```eval_rst
+.. important::
+   CentOS: Make sure redis is running before continuing. ::
+   
+      systemctl enable redis.service
+      systemctl start redis.service
+```
+
+## Database Setup
+
+Alliance Auth needs a MySQL user account and database. Open an SQL shell with `mysql -u root -p` and create them as follows, replacing `PASSWORD` with an actual secure password:
+
+    CREATE USER 'allianceserver'@'localhost' IDENTIFIED BY 'PASSWORD';
+    CREATE DATABASE alliance_auth;
+    GRANT ALL PRIVILEGES ON alliance_auth . * TO 'allianceserver'@'localhost';
+
+Close the SQL shell and secure your database server with the `mysql_secure_installation` command.
+
+## Auth Install
+
+### User Account
+
+For security and permissions, it’s highly recommended you create a separate user to install under.
+
+Ubuntu:
+
+    adduser --disabled-login allianceserver
+
+CentOS:
+
+    useradd -s /bin/nologin allianceserver
+
+### Virtual Environment
+
+Create a Python virtual environment and put it somewhere convenient (e.g. `/home/allianceserver/venv/auth/`)
+
+    python3 -m venv /home/allianceserver/venv/auth/
+
+```eval_rst
+.. tip::
+   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.
+.. _Python: https://docs.python.org/3/library/venv.html
+```
+    
+Activate the virtualenv using `source /home/allianceserver/venv/auth/bin/activate`. Note the `/bin/activate` on the end of the path.
+
+```eval_rst
+.. hint::
+   Each time you come to do maintenance on your Alliance Auth installation, you should activate your virtual environment first. When finished, deactivate it with the 'deactivate' command.
+```
+
+### Alliance Auth Project
+
+You can install the library using `pip install allianceauth`. This will install Alliance Auth and all its python dependencies.
+
+Now you need to create the application that will run the Alliance Auth install. Ensure you are in the allianceserver home directory by issuing `cd /home/allianceserver`.
+
+The `allianceauth start myauth` command will bootstrap a Django project which will run Alliance Auth. You can rename it from `myauth` to anything you'd like: this name is shown by default as the site name but that can be changed later.
+
+The settings file needs configuring. Edit the template at `myauth/myauth/settings/local.py`. Be sure to configure the EVE SSO and Email settings.
+
+Django needs to install models to the database before it can start.
+
+    python /home/allianceserver/myauth/manage.py migrate
+
+Now we need to round up all the static files required to render templates. Make a directory to serve them from and populate it.
+    
+    mkdir /var/www/myauth/static
+    python /home/allianceserver/myauth/manage.py collectstatic
+    chown -R www-data:www-data /var/www/myauth/static
+
+Check to ensure your settings are valid.
+
+    python /home/allianceserver/myauth/manage.py check
+
+And finally ensure the allianceserver user has read/write permissions to this directory before proceeding.
+
+    chown -R allianceserver:allianceserver /home/allianceserver/myauth
+
+## Background Tasks
+
+### Gunicorn
+
+To run the auth website a [WSGI Server](https://www.fullstackpython.com/wsgi-servers.html) is required. [Gunicorn](http://gunicorn.org/) is highly recommended for its ease of configuring. Installation is simple: `pip install gunicorn`. It can be manually called with `gunicorn myauth.wsgi` or automatically run using supervisor.
+
+Additional information is available in the [gunicorn](gunicorn.md) doc.
+
+### Supervisor
+
+[Supervisor](http://supervisord.org/) is a process watchdog service: it makes sure other processes are started automatically and kept running. It can be used to automatically start the WSGI server and celery workers for background tasks. Installation varies by OS:
+
+Ubuntu:
+
+    apt-get install supervisor
+
+CentOS:
+
+    yum install supervisor
+    systemctl enable supervisord.service
+    systemctl start supervisord.service
+
+Once installed it needs a configuration file to know which processes to watch. Your Alliance Auth project comes with a ready-to-use template which will ensure the celery workers, celery task scheduler and gunicorn are all running.
+
+    ln /home/allianceserver/myauth/supervisor.conf /etc/supervisor/conf.d/myauth.conf
+    supervisorctl reload
+
+You can check the status of the processes with `supervisorctl status`. Logs from these processes are available in `/home/allianceserver/myauth/log` named by process.
+
+```eval_rst
+.. note::
+   Any time the code or your settings change you'll need to restart gunicorn and celery. ::
+   
+       supervisorctl restart myauth:
+```
+
+## Webserver
+
+Once installed, decide on whether you're going to use [NGINX](nginx.md) or [Apache](apache.md) and follow the respective guide.
+
+## Superuser
+
+Before using your auth site it is essential to create a superuser account. This account will have all permissions in Alliance Auth. It's OK to use this as your personal auth account.
+
+    python /home/allianceserver/myauth/manage.py createsuperuser
+
+```eval_rst
+.. important::
+   Be sure to add a main character to this account before attempting to activate services with it.
+```
+
+## Updating
+
+Periodically [new releases](https://github.com/allianceauth/allianceauth/releases/) are issued with bug fixes and new features. To update your install, simply activate your virtual environment and update with `pip install --upgrade allianceauth`. Be sure to read the release notes which will highlight changes.
+
+Some releases come with changes to settings: update your project's settings with `allianceauth update /home/allianceserver/myauth`.
+
+Some releases come with new or changed models. Update your database to reflect this with `python /home/allianceserver/myauth/manage.py migrate`.
+ 
+Always restart celery and gunicorn after updating.

docs/installation/auth/centos.md

@@ -1,80 +0,0 @@
-# CentOS Installation
-
-It's recommended to update all packages before proceeding.
-    `sudo yum update`
-    `sudo yum upgrade`
-    `sudo reboot`
-
-Now install all [dependencies](dependencies.md).
-
-    sudo yum install xxxxxxx
-
-replacing the x's with the list of packages.
-
-Make sure redis is running before continuing:
-
-    systemctl enable redis.service
-    systemctl start redis.service
-
-For security and permissions, it's highly recommended you create a user to install under who is not the root account.
-
-    sudo adduser allianceserver
-    sudo passwd allianceserver
-
-This user needs sudo powers. Add them by editing the sudoers file:
-
-    sudo nano /etc/sudoers
-
-Find the line which says `root    ALL=(ALL)       ALL` - beneath it add another line `allianceserver ALL=(ALL)       ALL` - now reboot.
-
-**From this point on you need to be logged in as the allianceserver user**
-
-Start your mariadb server `sudo systemctl start mariadb`
-
-Secure your MYSQL / Maria-db server by typing `mysql_secure_installation `
-
-AllianceAuth needs a MySQL user account. Create one as follows, replacing `PASSWORD` with an actual secure password:
-
-    mysql -u root -p
-    CREATE USER 'allianceserver'@'localhost' IDENTIFIED BY 'PASSWORD';
-    GRANT ALL PRIVILEGES ON * . * TO 'allianceserver'@'localhost';
-
-Now we need to make the requisite database.
-
-    create database alliance_auth;
-
-Create a Python virtual environment and put it somewhere convenient (e.g. `~/venv/aauth/`)
-
-    python3.6 -m venv /path/to/new/virtual/environment
-
-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.
-
-Now you can install the library using `pip install allianceauth`. This will install Alliance Auth and all its python dependencies.
-
-Ensure you are in the allianceserver home directory by issuing `cd ~`.
-
-Now you need to create the application that will run the Alliance Auth install.
-
-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.
-
-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](settings.md) for specifics.
-
-Django needs to install models to the database before it can start.
-
-    python manage.py migrate
-
-Now we need to round up all the static files required to render templates. Answer ‘yes’ when prompted.
-
-    python manage.py collectstatic
-
-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 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/cloudflare.md

@@ -1,35 +0,0 @@
-# Cloudflare
-
-CloudFlare offers free SSL and DDOS mitigation services. Why not take advantage of it?
-
-## Setup
-
-You’ll need to register an account on [CloudFlare’s site.](https://www.cloudflare.com/)
-
-Along the top bar, select `Add Site`
-
-Enter your domain name. It will scan records and let you know you can add the site. Continue setup.
-
-On the next page you should see an A record for example.com pointing at your server IP. If not, manually add one:
-
-    A    example.com     my.server.ip.address     Automatic TTL
-
-Add the record and ensure the cloud under Status is orange. If not, click it. This ensures traffic gets screened by CloudFlare.
-
-If you want forums or kb on a subdomain, and want these to be protected by CloudFlare, add an additional record for for each subdomain in the following format, ensuring the cloud is orange:
-
-    CNAME     subdomain         example.com       Automatic TTL
-
-CloudFlare blocks ports outside 80 and 443 on hosts it protects. This means, if the cloud is orange, only web traffic will get through. We need to reconfigure AllianceAuth to provide services under a subdomain. Configure these subdomains as above, but ensure the cloud is not orange (arrow should go around a grey cloud).
-
-## Redirect to HTTPS
-
-Now we need to configure the https redirect to force all traffic to https. Along the top bar of CloudFlare, select `Page Rules`. Add a new rule, Pattern is example.com, toggle the `Always use https` to ON, and save. It’ll take a few minutes to propagate. 
-
-![infographic](/_static/images/installation/auth/cloudflare/page_rules.jpg)
-
-## Update Auth URLs
-
-Edit settings.py and replace everything that has a HTTP with HTTPS (except anything with a port on the end, like `OPENFIRE_ADDRESS`)
-
-And there we have it. You’re DDOS-protected with free SSL.

docs/installation/auth/dependencies.md

@@ -1,44 +0,0 @@
-# Dependencies
-
-## Ubuntu
-
-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
-
-    python3 python3-dev python3-setuptools python3-pip
-
-#### MySQL
-
-    mariadb-server mysql-client libmysqlclient-dev
-
-#### Utilities
-
-    unzip git redis-server curl libssl-dev libbz2-dev libffi-dev
-
-## CentOS 7
-
-Tested on CentOS 7
-
-### Add The IUS Repository
-
-    sudo yum -y install https://centos7.iuscommunity.org/ius-release.rpm
-    yum update
-
-### Core
-Required for base auth site
-
-#### Python
-
-    python36u python36u-devel python36u-setuptools python36u-pip bzip2-devel
-
-#### MySQL
-
-    mariadb-server mariadb-devel mariadb
-
-#### Utilities
-
-    gcc gcc-c++ unzip git redis curl nano

docs/installation/auth/gunicorn.md

@@ -15,30 +15,30 @@ Check out the full [Gunicorn docs](http://docs.gunicorn.org/en/latest/index.html
 
 Install Gunicorn using pip, `pip install gunicorn`.
 
-In your `allianceauth` base directory, try running `gunicorn --bind 0.0.0.0:8000 alliance_auth.wsgi`. You should be able to browse to http://yourserver:8000 and see your Alliance Auth installation running. Images and styling will be missing, but dont worry, your web server will provide them.
+In your `myauth` base directory, try running `gunicorn --bind 0.0.0.0:8000 myauth.wsgi`. You should be able to browse to http://yourserver:8000 and see your Alliance Auth installation running. Images and styling will be missing, but dont worry, your web server will provide them.
 
 Once you validate its running, you can kill the process with Ctrl+C and continue.
 
 ## Running Gunicorn with Supervisor
 
-You should use [Supervisor](supervisor.md) to keep all of Alliance Auth components running (instead of using screen). You don't _have to_ but we will be using it to start and run Gunicorn so you might as well.
+You should use [Supervisor](allianceauth.md#supervisor) to keep all of Alliance Auth components running (instead of using screen). You don't _have to_ but we will be using it to start and run Gunicorn so you might as well.
 
 ### Sample Supervisor config
-You'll want to edit `/etc/supervisor/conf.d/aauth_gunicorn.conf` (or whatever you want to call the config file)
+You'll want to edit `/etc/supervisor/conf.d/myauth_gunicorn.conf` (or whatever you want to call the config file)
 ```
-[program:aauth-gunicorn]
-user = www-data
-directory=/home/allianceserver/allianceauth/
-command=gunicorn alliance_auth.wsgi --workers=3 --timeout 120
+[program:myauth-gunicorn]
+user = allianceserver
+directory=/home/allianceserver/myauth/
+command=gunicorn myauth.wsgi --workers=3 --timeout 120
 autostart=true
 autorestart=true
 stopsignal=INT
 ```
 
-- `[program:aauth-gunicorn]` - Change aauth-gunicorn to whatever you wish to call your process in Supervisor.
-- `user = www-data` - Change to whatever user you wish Gunicorn to run as. You could even set this as allianceserver if you wished. I'll leave the question security of that up to you.
-- `directory=/home/allianceserver/allianceauth/` - Needs to be the path to your Alliance Auth install.
-- `command=gunicorn alliance_auth.wsgi --workers=3 --timeout 120` - Running Gunicorn and the options to launch with. This is where you have some decisions to make, we'll continue below.
+- `[program:myauth-gunicorn]` - Change myauth-gunicorn to whatever you wish to call your process in Supervisor.
+- `user = allianceserver` - Change to whatever user you wish Gunicorn to run as. You could even set this as allianceserver if you wished. I'll leave the question security of that up to you.
+- `directory=/home/allianceserver/myauth/` - Needs to be the path to your Alliance Auth project.
+- `command=gunicorn myauth.wsgi --workers=3 --timeout 120` - Running Gunicorn and the options to launch with. This is where you have some decisions to make, we'll continue below.
 
 #### Gunicorn Arguments
 
@@ -118,4 +118,4 @@ Any web server capable of proxy passing should be able to sit in front of Gunico
 ## Restarting Gunicorn
 In the past when you made changes you restarted the entire Apache server. This is no longer required. When you update or make configuration changes that ask you to restart Apache, instead you can just restart Gunicorn:
 
-`sudo supervisorctl restart aauth-gunicorn`, or the service name you chose for it.
+`sudo supervisorctl restart myauth-gunicorn`, or the service name you chose for it.

docs/installation/auth/index.md

@@ -3,14 +3,8 @@
 ```eval_rst
 .. toctree::
 
-    dependencies
-    ubuntu
-    centos
-    settings
+    allianceauth
+    gunicorn
     nginx
     apache
-    gunicorn
-    cloudflare
-    supervisor
-    quickstart
 ```

docs/installation/auth/quickstart.md

@@ -1,11 +0,0 @@
-# Quick Start
-
-Once you’ve installed AllianceAuth, perform these steps to get yourself up and running.
-
-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. 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 you should utilise [supervisor](supervisor.md). Previously screen was suggested to keep these tasks running, however this is no longer the preferred method.

docs/installation/auth/settings.md

@@ -1,376 +0,0 @@
-# Settings Overview
-
-The `alliance_auth/settings.py` file is used to pass settings to the django app needed to run.
-
-### Words of Warning
-
-Certain fields are quite sensitive to leading `http://` and trailing `/` - if you see these present in the default text, be sure to include them in your values.
-
-Every variable value is opened and closed with a single apostrophe `'` - please do not include these in your values or it will break things. If you absolutely must, replace them at the opening and closing of the value with double quotes `"`.
-
-Certain variables are booleans, and come in a form that looks like this:
-
-    MEMBER_CORP_GROUPS = 'True' == os.environ.get('AA_MEMBER_CORP_GROUPS', 'True')
-
-They're handled as strings because when settings are exported from shell commands (eg `export AA_MEMBER_CORP_GROUPS False`) they're interpreted as strings, so a string comparison is done.
-
-When changing these booleans, edit the setting within the brackets (eg `('AA_MEMBER_CORP_GROUPS', 'True')` vs `('AA_MEMBER_CORP_GROUPS', 'False')`) and not the `True` earlier in the statement. Otherwise these will have unexpected behaviours.
-
-# Fields to Modify
-
-## Required
- - [SECRET_KEY](#secret-key)
-   - Use [this tool](http://www.miniwebtool.com/django-secret-key-generator/) to generate a key on initial install
- - [DEBUG](#debug)
-   - If issues are encountered, set this to `True` to view a more detailed error report, otherwise set `False`
- - [ALLOWED_HOSTS](#allowed-hosts)
-   - This restricts web addresses auth will answer to. Separate with commas. 
-   - Should include localhost `127.0.0.1` and `example.com`
-   - To allow from all, include `'*'`
- - [DATABASES](#databases)
-   - Fill out the database name and user credentials to manage the auth database.
- - [DOMAIN](#domain)
-   - Set to the domain name AllianceAuth will be accessible under
- - [EMAIL_HOST_USER](#email-host-user)
-   - Username to send emails from. If gmail account, the full gmail address.
- - [EMAIL_HOST_PASSWORD](#email-host-password)
-   - Password for the email user.
- - [CORP_IDS](#corp-ids)
-   - List of corp IDs who are members. Exclude if their alliance is in `ALLIANCE_IDS`
- - [ALLIANCE_IDS](#alliance-ids)
-   - List of alliance IDs who are members.
- - [ESI_SSO_CLIENT_ID](#esi-sso-client_id)
-   - EVE application ID from the developers site. See the [SSO Configuration Instruction](#sso-settings)
- - [ESI_SSO_CLIENT_SECRET](#esi-sso-client-secret)
-   - EVE application secret from the developers site.
- - [ESI_SSO_CALLBACK_URL](#esi-sso-callback-url)
-   - OAuth callback URL. Should be `https://mydomain.com/sso/callback`
-
-## Services
-### IPBoard
-If using IPBoard, the following need to be set in accordance with the [install instructions](../services/ipboard3.md)
- - [IPBOARD_ENDPOINT](#ipboard-endpoint)
- - [IPBOARD_APIKEY](#ipboard-apikey)
- - [IPBOARD_APIMODULE](#ipboard-apimodule)
-
-### XenForo
-If using XenForo, the following need to be set in accordance with the [install instructions](../services/xenforo.md)
- - [XENFORO_ENDPOINT](#xenforo-endpoint)
- - [XENFORO_APIKEY](#xenforo-apikey)
-
-### Openfire
-If using Openfire, the following need to be set in accordance with the [install instructions](../services/openfire.md)
- - [JABBER_URL](#jabber-url)
- - [JABBER_PORT](#jabber-port)
- - [JABBER_SERVER](#jabber-server)
- - [OPENFIRE_ADDRESS](#openfire-address)
- - [OPENFIRE_SECRET_KEY](#openfire-secret-key)
- - [BROADCAST_USER](#broadcast-user)
- - [BROADCAST_USER_PASSWORD](#broadcast-user-password)
- - [BROADCAST_SERVICE_NAME](#broadcast-service-name)
- - [BROADCAST_IGNORE_INVALID_CERT](#broadcast-ignore-invalid-cert)
-
-### Mumble
-If using Mumble, the following needs to be set to the address of the mumble server:
- - [MUMBLE_URL](#mumble-url)
-
-### PHPBB3
-If using phpBB3, the database needs to be defined.
-
-### Teamspeak3
-If using Teamspeak3, the following need to be set in accordance with the [install instrictions](../services/teamspeak3.md)
- - [TEAMSPEAK3_SERVER_IP](#teamspeak3-server-ip)
- - [TEAMSPEAK3_SERVER_PORT](#teamspeak3-server-port)
- - [TEAMSPEAK3_SERVERQUERY_USER](#teamspeak3-serverquery-user)
- - [TEAMSPEAK3_SERVERQUERY_PASSWORD](#teamspeak3-serverquery-password)
- - [TEAMSPEAK3_VIRTUAL_SERVER](#teamspeak3-virtual-server)
- - [TEAMSPEAK3_PUBLIC_URL](#teamspeak3-public-url)
-
-### Discord
-If connecting to a Discord server, set the following in accordance with the [install instructions](../services/discord.md)
- - [DISCORD_GUILD_ID](#discord-guild-id)
- - [DISCORD_BOT_TOKEN](#discord-bot-token)
- - [DISCORD_INVITE_CODE](#discord-invite-code)
- - [DISCORD_APP_ID](#discord-app-id)
- - [DISCORD_APP_SECRET](#discord-app-secret)
- - [DISCORD_CALLBACK_URL](#discord-callback-url)
- - [DISCORD_SYNC_NAMES](#discord-sync-names)
-
-### Discourse
-If connecting to Discourse, set the following in accordance with the [install instructions](../services/discourse.md)
- - [DISCOURSE_URL](#discourse-url)
- - [DISCOURSE_API_USERNAME](#discourse-api-username)
- - [DISCOURSE_API_KEY](#discourse-api-key)
- - [DISCOURSE_SSO_SECRET](#discourse-sso-secret)
-
-### IPSuite4
-If using IPSuite4 (aka IPBoard4) the following are required:
- - [IPS4_URL](#ips4-url)
- - the database needs to be defined
-
-### SMF
-If using SMF the following are required:
- - [SMF_URL](#smf-url)
- - the database needs to be defined
-
-## Optional
-### Standings
-To allow access to blues, a corp API key is required to pull standings from. Corp does not need to be owning corp or in owning alliance. Required mask is 16 (Communications/ContactList)
- - [CORP_API_ID](#corp-api-id)
- - [CORP_API_VCODE](#corp-api-vcode)
-
-### API Key Audit URL
-To define what happens when an API is clicked, set according to [these instructions](#hr-configuration)
- - [API_KEY_AUDIT_URL](#api-key-audit-url)
-
-### Auto Groups
-Groups can be automatically assigned based on a user's corp or alliance. Set the following to `True` to enable this feature.
- - [MEMBER_CORP_GROUPS](#member-corp-groups)
- - [MEMBER_ALLIANCE_GROUPS](#member-alliance-groups)
- - [BLUE_CORP_GROUPS](#blue-corp-groups)
- - [BLUE_ALLIANCE_GROUPS](#blue-alliance-groups)
-
-### Fleet-Up
-Fittings and operations can be imported from Fleet-Up. Define the following to do so.
- - [FLEETUP_APP_KEY](#fleetup-app-key)
- - [FLEETUP_USER_ID](#fleetup-user-id)
- - [FLEETUP_API_ID](#fleetup-api-id)
- - [FLEETUP_GROUP_ID](#fleetup-group-id)
-
-### CAPTCHA
-To help prevent bots from registering and brute forcing the login. Get the reCaptcha keys from [here](https://www.google.com/recaptcha/intro/index.html)
- - [CAPTCHA_ENABLED](#captcha_enabled)
- - [RECAPTCHA_PUBLIC_KEY](#recaptcha_public_key)
- - [RECAPTCHA_PRIVATE_KEY](#recaptcha_private_key)
- - [NOCAPTCHA](#nocaptcha)
-
-# Description of Settings
-## Django
-### SECRET_KEY
-A random string used in cryptographic functions, such as password hashing. Changing after installation will render all sessions and password reset tokens invalid.
-### DEBUG
-Replaces the generic `SERVER ERROR (500)` page when an error is encountered with a page containing a traceback and variables. May expose sensitive information so not recommended for production.
-### ALLOWED_HOSTS
-A list of addresses used to validate headers: AllianceAuth will block connection coming from any other address. This should be a list of URLs and IPs to allow. In most cases, just adding `'example.com'` is sufficient. This also accepts the `'*'` wildcard for testing purposes.
-### DATABASES
-List of databases available. Contains the Django database, and may include service ones if enabled. Service databases are defined in their individual sections and appended as needed automatically.
-### LANGUAGE_CODE
-Friendly name of the local language.
-### TIME_ZONE
-Friendly name of the local timezone.
-### CAPTCHA_ENABLED
-Enable Google reCaptcha
-### RECAPTCHA_PUBLIC_KEY
-Google reCaptcha public key
-### RECAPTCHA_PRIVATE_KEY
-Google reCaptcha private key
-### NOCAPTCHA
-Enable New No Captcha reCaptcha
-### STATIC_URL
-Absolute URL to serve static files from.
-### STATIC_ROOT
-Root folder to store static files in.
-### SUPERUSER_STATE_BYPASS
-Overrides superuser account states to always return True on membership tests. If issues are encountered, or you want to test access to certain portions of the site, set to False to respect true states of superusers.
-## EMAIL SETTINGS
-### DOMAIN
-The URL to which emails will link.
-### EMAIL_HOST
-The host address of the email server.
-### EMAIL_PORT
-The host port of the email server.
-### EMAIL_HOST_USER
-The username to authenticate as on the email server. For GMail, this is the full address.
-### EMAIL_HOST_PASSWORD
-The password of the user used to authenticate on the email server.
-### EMAIL_USE_TLS
-Enable TLS connections to the email server. Default is True.
-## Front Page Links
-### KILLBOARD_URL
-Link to a killboard.
-### EXTERNAL_MEDIA_URL
-Link to another media site, eg YouTube channel.
-### FORUM_URL
-Link to forums. Also used as the phpbb3 URL if enabled.
-### SITE_NAME
-Name to show in the top-left corner of auth.
-## SSO Settings
-An application will need to be created on the developers site. Please select `Authenticated API Access`, and choose all scopes starting with `esi`.
-### ESI_SSO_CLIENT_ID
-The application cliend ID generated from the [developers site.](https://developers.eveonline.com)
-### ESI_SSO_CLIENT_SECRET
-The application secret key generated from the [developers site.](https://developers.eveonline.com)
-### ESI_SSO_CALLBACK_URL
-The callback URL for authentication handshake. Should be `https://example.com/sso/callback`.
-## Default Group Settings
-### DEFAULT_AUTH_GROUP
-Name of the group members of the owning corp or alliance are put in.
-### DEFAULT_BLUE_GROUP
-Name of the group blues of the owning corp or alliance are put in.
-### MEMBER_CORP_GROUPS
-If `True`, add members to groups with their corp name, prefixed with `Corp_`
-### MEMBER_ALLIANCE_GROUPS
-If `True`, add members to groups with their alliance name, prefixed with `Alliance_`
-### BLUE_CORP_GROUPS
-If `True`, add blues to groups with their corp name, prefixed with `Corp_`
-### BLUE_ALLIANCE_GROUPS
-If `True`, add blues to groups with their alliance name, prefixed with `Alliance_`
-## Tenant Configuration
-Characters of any corp or alliance with their ID here will be treated as a member.
-### CORP_IDS
-EVE corp IDs of member corps. Separate with a comma.
-### ALLIANCE_IDS
-EVE alliance IDs of member alliances. Separate with a comma.
-## Standings Configuration
-To allow blues to access auth, standings must be pulled from a corp-level API. This API needs access mask 16 (ContactList).
-### CORP_API_ID
-The ID of an API key for a corp from which to pull standings, if desired. Needed for blues to gain access.
-### CORP_API_VCODE
-The verification code of an API key for a corp from which to pull standings, if desired. Needed for blues to gain access.
-### BLUE_STANDING
-The minimum standing value to consider blue. Default is 5.0
-### STANDING_LEVEL
-Standings from the API come at two levels: `corp` and `alliance`. Select which level to consider here.
-## API Configuration
-### MEMBER_API_MASK
-Required access mask for members' API keys to be considered valid.
-### MEMBER_API_ACCOUNT
-If `True`, require API keys from members to be account-wide, not character-restricted.
-### BLUE_API_MASK
-Required access mask for blues' API keys to be considered valid.
-### BLUE_API_ACCOUNT
-If `True`, require API keys from blues to be account-wide, not character-restricted.
-### REJECT_OLD_APIS
-Require each submitted API be newer than the latest submitted API. Protects against recycled or stolen API keys.
-### REJECT_OLD_APIS_MARGIN
-Allows newly submitted APIs to have their ID this value lower than the highest API ID on record and still be accepted. Default is 50, 0 is safest.
-## EVE Provider Settings
-Data about EVE objects (characters, corps, alliances) can come from two sources: the XML API or the EVE Swagger Interface.
-These settings define the default source.
-
-For most situations, the EVE Swagger Interface is best. But if it goes down or experiences issues, these can be reverted to the XML API.
-
-Accepted values are `esi` and `xml`.
-### EVEONLINE_CHARACTER_PROVIDER
-The default data source to get character information. Default is `esi`
-### EVEONLINE_CORP_PROVIDER
-The default data source to get corporation information. Default is `esi`
-### EVEONLINE_ALLIANCE_PROVIDER
-The default data source to get alliance information. Default is `esi`
-### EVEONLINE_ITEMTYPE_PROVIDER
-The default data source to get item type information. Default is `esi`
-## Alliance Market
-### MARKET_URL
-The web address to access the Evernus Alliance Market application.
-### MARKET_DB
-The Evernus Alliance Market database connection information.
-## HR Configuration
-### API_KEY_AUDIT_URL
-This setting defines what happens when someone clicks on an API key (such as in corpstats or an application).
-
-Default behaviour is to show the verification code in a popup, but this can be set to link out to a website.
-
-The URL set here uses python string formatting notation. Variable names are enclosed in `{}` brackets. Three variable names are available: `api_id`, `vcode`, and `pk` (which is the primary key of the API in the database - only useful on the admin site).
-
-Example URL structures are provided. Jacknife can be installed on your server following [its setup guide.](../services/jacknife.md)
-## IPBoard3 Configuration
-### IPBOARD_ENDPOINT
-URL to the `index.php` file of a IPBoard install's API server.
-### IPBOARD_APIKEY
-API key for accessing an IPBoard install's API
-### IPBOARD_APIMODULE
-Module to access while using the API
-## XenForo Configuration
-### XENFORO_ENDPOINT
-The address of the XenForo API. Should look like `https://example.com/forum/api.php`
-### XENFORO_DEFAULT_GROUP
-The group ID of the group to assign to member. Default is 0.
-### XENFORO_APIKEY
-The API key generated from XenForo to allow API access.
-## Jabber Configuration
-### JABBER_URL
-Address to instruct members to connect their jabber clients to, in order to reach an Openfire install. Usually just `example.com`
-### JABBER_PORT
-Port to instruct members to connect their jabber clients to, in order to reach an Openfire install. Usually 5223.
-### JABBER_SERVER
-Server name of an Openfire install. Usually `example.com`
-### OPENFIRE_ADDRESS
-URL of the admin web interface for an Openfire install. Usually `http://example.com:9090`. If HTTPS is desired, change port to 9091: `https://example.com:9091`
-### OPENFIRE_SECRET_KEY
-Secret key used to authenticate with an Openfire admin interface.
-### BROADCAST_USER
-Openfire user account used to send broadcasts from. Default is `Broadcast`.
-### BROADCAST_USER_PASSWORD
-Password to use when authenticating as the `BROADCAST_USER`
-### BROADCAST_SERVICE_NAME
-Name of the broadcast service running on an Openfire install. Usually `broadcast`
-## Mumble Configuration
-### MUMBLE_URL
-Address to instruct members to connect their Mumble clients to.
-### MUMBLE_SERVER_ID
-Depreciated. We're too scared to delete it.
-## Teamspeak3 Configuration
-### TEAMSPEAK3_SERVER_IP
-IP of a Teamspeak3 server on which to manage users. Usually `127.0.0.1`
-### TEAMSPEAK3_SERVER_PORT
-Port on which to connect to a Teamspeak3 server at the `TEAMSPEAK3_SERVER_IP`. Usually `10011`
-### TEAMSPEAK3_SERVERQUERY_USER
-User account with which to authenticate on a Teamspeak3 server. Usually `serveradmin`.
-### TEAMSPEAK3_SERVERQUERY_PASSWORD
-Password to use when authenticating as the `TEAMSPEAK3_SERVERQUERY_USER`. Provided during first startup or when you define a custom serverquery user.
-### TEAMSPEAK3_VIRTUAL_SERVER
-ID of the server on which to manage users. Usually `1`.
-### TEAMSPEAK3_PUBLIC_URL
-Address to instruct members to connect their Teamspeak3 clients to. Usually `example.com`
-## Discord Configuration
-### DISCORD_GUILD_ID
-The ID of a Discord server on which to manage users.
-### DISCORD_BOT_TOKEN
-The bot token obtained from defining a bot on the [Discord developers site.](https://discordapp.com/developers/applications/me)
-### DISCORD_INVITE_CODE
-A no-limit invite code required to add users to the server. Must be generated from the Discord server itself (instant invite).
-### DISCORD_APP_ID
-The application ID obtained from defining an application on the [Discord developers site.](https://discordapp.com/developers/applications/me)
-### DISCORD_APP_SECRET
-The application secret key obtained from defining an application on the [Discord developers site.](https://discordapp.com/developers/applications/me)
-### DISCORD_CALLBACK_URL
-The callback URL used for authenticaiton flow. Should be `https://example.com/discord_callback`. Must match exactly the one used when defining the application.
-### DISCORD_SYNC_NAMES
-Override usernames on the server to match the user's main character.
-## Discourse Configuration
-### DISCOURSE_URL
-The web address of the Discourse server to direct users to.
-### DISCOURSE_API_USERNAME
-Username of the account which generated the API key on Discourse.
-### DISCOURSE_API_KEY
-API key defined on Discourse.
-### DISCOURSE_SSO_SECRET
-The SSO secret key defined on Discourse.
-## IPS4 Configuration
-### IPS4_URL
-URL of the IPSuite4 install to direct users to.
-### IPS4_API_KEY
-Depreciated. We're too scared to delete it.
-### IPS4_DB
-The database connection to manage users on.
-## SMF Configuration
-### SMF_URL
-URL of the SMF install to direct users to.
-### SMF_DB
-The database connection to manage users on.
-## Fleet-Up Configuration
-### FLEETUP_APP_KEY
-Application key as [defined on Fleet-Up.](http://fleet-up.com/Api/MyApps)
-### FLEETUP_USER_ID
-API user ID as [defined on Fleet-Up.](http://fleet-up.com/Api/MyKeys)
-### FLEETUP_API_ID
-API ID as [defined on Fleet-Up.](http://fleet-up.com/Api/MyKeys)
-### FLEETUP_GROUP_ID
-The group ID from which to pull data. Can be [retrieved from Fleet-Up](http://fleet-up.com/Api/Endpoints#groups_mygroupmemberships)
-## Logging Configuration
-This section is used to manage how logging messages are processed.
-
-To turn off logging notifications, change the `handlers` `notifications` `class` to `logging.NullHandler`
-
-## Danger Zone
-Everything below logging is magic. **Do not touch.**

docs/installation/auth/supervisor.md

@@ -1,81 +0,0 @@
-# Supervisor
-
->Supervisor is a client/server system that allows its users to control a number of processes on UNIX-like operating systems.
-
-What that means is supervisor will take care of ensuring the celery workers are running (and mumble authenticator) and start the automatically on reboot. Handy, eh?
-
-## Installation
-
-Most OSes have a supervisor package available in their distribution.
-
-Ubuntu:
-
-    sudo apt-get install supervisor
-
-CentOS:
-
-    sudo yum install supervisor
-    sudo systemctl enable supervisord.service
-    sudo systemctl start supervisord.service
-
-## Configuration
-
-Auth provides example config files for the celery workers, the periodic task scheduler (celery beat), and the mumble authenticator. All of these are available in `thirdparty/Supervisor`.
-
-For most users, all you have to do is copy the config files to `/etc/supervisor/conf.d` then restart the service. Copy `auth.conf` for the celery workers, and `auth-mumble.conf` for the mumble authenticator. For all three just use a wildcard:
-
-    sudo cp thirdparty/Supervisor/* /etc/supervisor/conf.d
-
-Ubuntu:
-
-    sudo service supervisor restart
-
-CentOS:
-
-    sudo systemctl restart supervisor.service
-
-## Checking Status
-
-To ensure the processes are working, check their status:
-
-    sudo supervisorctl status
-
-Processes will be `STARTING`, `RUNNING`, or `ERROR`. If an error has occurred, check their log files:
- - celery workers: `log/worker.log`
- - celery beat: `log/beat.log`
- - authenticator: `log/authenticator.log`
- 
-## Restarting Processes
-
-To restart the celery group:
-
-    sudo supervisorctl restart auth:*
-
-To restart just celerybeat:
-
-    sudo supervisorctl restart auth:celerybeat
-
-To restart just celeryd:
-
-    sudo supervisorctl restart auth:celeryd
-
-To restart just mumble authenticator:
-
-    sudo supervisorctl restart auth-mumble
-
-## Customizing Config Files
-
-The only real customization needed is if running in a virtual environment. The python path will have to be changed in order to start in the venv.
-
-Edit the config files and find the line saying `command`. Replace `python` with `/path/to/venv/bin/python`. For Celery replace `celery` with `/path/to/venv/bin/celery`. This can be relative to the `directory` specified in the config file.
-
-Note that for config changes to be loaded, the supervisor service must be restarted.
-
-## Troubleshooting
-
-### auth-celerybeat fails to start
-Most often this is caused by a permissions issue on the allianceauth directory (the error will talk about `celerybeat.pid`). The easiest fix is to edit its config file and change the `user` from `allianceserver` to `root`.
-
-### Workers are using old settings
-
-Every time the codebase is updated or settings file changed, workers will have to be restarted. Easiest way is to restart the supervisor service (see configuration above for commands)

docs/installation/auth/ubuntu.md

@@ -1,71 +0,0 @@
-# Ubuntu Installation
-
-It’s recommended to update all packages before proceeding.
-
-    sudo apt-get update
-    sudo apt-get upgrade
-    sudo reboot
-
-Now install all [dependencies](dependencies.md).
-
-    sudo apt-get install xxxxxxx
-replacing the xs with the list of packages.
-
-For security and permissions, it’s highly recommended you create a user to install under who is not the root account.
-
-    sudo adduser allianceserver
-
-This user needs sudo powers. Add them by editing the sudoers file:
-
-    sudo nano /etc/sudoers
-
-Find the line which says `root ALL=(ALL:ALL) ALL` - beneath it add another line `allianceserver ALL=(ALL:ALL) ALL` - now reboot.
-
-**From this point on you need to be logged in as the allianceserver user**
-
-AllianceAuth needs a MySQL user account. Create one as follows, replacing `PASSWORD` with an actual secure password:
-
-    mysql -u root -p
-    CREATE USER 'allianceserver'@'localhost' IDENTIFIED BY 'PASSWORD';
-    GRANT ALL PRIVILEGES ON * . * TO 'allianceserver'@'localhost';
-
-Now we need to make the requisite database.
-
-    create database alliance_auth;
-    
-    
-Create a Python virtual environment and put it somewhere convenient (e.g. `~/venv/aauth/`)
-
-    python3 -m venv /path/to/new/virtual/environment
-
-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.
-
-Now you can install the library using `pip install allianceauth`. This will install Alliance Auth and all its python dependencies.
-
-Ensure you are in the allianceserver home directory by issuing `cd ~`.
-
-Now you need to create the application that will run the Alliance Auth install.
-
-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.
-
-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](settings.md) for specifics.
-
-Django needs to install models to the database before it can start.
-
-    python manage.py migrate
-
-Now we need to round up all the static files required to render templates. Answer ‘yes’ when prompted.
-
-    python manage.py collectstatic
-
-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 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.

manage.py

@@ -3,7 +3,7 @@ import os
 import sys
 
 if __name__ == "__main__":
-    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "allianceauth.settings.base")
+    os.environ.setdefault("DJANGO_SETTINGS_MODULE", "allianceauth.project_template.project_name.settings.base")
     try:
         from django.core.management import execute_from_command_line
     except ImportError:

setup.py

@@ -51,4 +51,8 @@ setup(
     url='https://github.com/allianceauth/allianceauth',
     zip_safe=False,
     include_package_data=True,
+    entry_points="""
+            [console_scripts]
+            allianceauth=allianceauth.bin.allianceauth:main
+    """,
 )

tests/settings.py

@@ -2,7 +2,7 @@
 Alliance Auth Test Suite Django settings.
 """
 
-from allianceauth.settings.base import *
+from allianceauth.project_template.project_name.settings.base import *
 
 # Use nose to run all tests
 TEST_RUNNER = 'django_nose.NoseTestSuiteRunner'
@@ -16,7 +16,7 @@ NOSE_ARGS = [
 # Celery configuration
 CELERY_ALWAYS_EAGER = True  # Forces celery to run locally for testing
 
-INSTALLED_APPS = [
+INSTALLED_APPS += [
     'allianceauth.hrapplications',
     'allianceauth.timerboard',
     'allianceauth.srp',
@@ -39,8 +39,6 @@ INSTALLED_APPS = [
     'django_nose',
 ]
 
-add_auth_apps(INSTALLED_APPS)
-
 ROOT_URLCONF = 'tests.urls'
 
 CACHES['default'] = {'BACKEND': 'django.core.cache.backends.db.DatabaseCache'}