Documentation overhaul

docs/_static/images/features/apps/permissions_tool/audit.png:Zone.Identifier

@@ -0,0 +1,4 @@
+[ZoneTransfer]
+ZoneId=3
+ReferrerUrl=https://i.imgur.com/6dXZ5BH.png
+HostUrl=https://i.imgur.com/6dXZ5BH.png

docs/_static/images/features/apps/permissions_tool/overview.png:Zone.Identifier

@@ -0,0 +1,4 @@
+[ZoneTransfer]
+ZoneId=3
+ReferrerUrl=https://i.imgur.com/Er1g02v.png
+HostUrl=https://i.imgur.com/Er1g02v.png

docs/conf.py

@@ -54,7 +54,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Alliance Auth'
-copyright = u'2018, Alliance Auth'
+copyright = u'2018-2020, Alliance Auth'
 author = u'R4stl1n'
 
 # The version info for the project you're documenting, acts as replacement for

docs/development/aa_core/documentation.md

@@ -1,4 +1,4 @@
-# Documentation
+# Alliance Auth documentation
 
 The documentation for Alliance Auth uses [Sphinx](http://www.sphinx-doc.org/) to build documentation. When a new commit
  to specific branches is made (master, primarily), the repository is automatically pulled, docs built and deployed on

docs/development/aa_core/index.md

@@ -0,0 +1,10 @@
+# Developing AA Core
+
+This section contains important information on how to develop Alliance Auth itself.
+
+```eval_rst
+.. toctree::
+    :maxdepth: 1
+
+    documentation
+```

docs/development/custom/index.md

@@ -0,0 +1,12 @@
+# Custom apps and services
+
+This section describes how to extend **Alliance Auth** with custom apps and services.
+
+```eval_rst
+.. toctree::
+    :maxdepth: 1
+
+    integrating-services
+    menu-hooks
+    url-hooks
+```

docs/development/index.md

@@ -1,10 +1,11 @@
 # Development
 
+**Alliance Auth** is designed to be extended easily. Learn how to develop your own apps and services for AA or to develop for AA core in the development chapter.
+
 ```eval_rst
 .. toctree::
+    :maxdepth: 1
 
-    documentation
+    custom/index
-    integrating-services
+    aa_core/index
-    menu-hooks
-    url-hooks
 ```

docs/features/apps/autogroups.md

@@ -7,17 +7,17 @@
 
 Auto groups allows you to automatically place users of certain states into Corp or Alliance based groups. These groups are created when the first user is added to them and removed when the configuration is deleted.
 
-
 ## Installation
 
-Add `'allianceauth.eveonline.autogroups',` to your `INSTALLED_APPS` list and run migrations. All other settings are controlled via the admin panel under the `Eve_Autogroups` section.
+This is an optional app that needs to be installed.
 
+To install this app add `'allianceauth.eveonline.autogroups',` to your `INSTALLED_APPS` list and run migrations. All other settings are controlled via the admin panel under the `Eve_Autogroups` section.
 
 ## Configuring a group
 
 When you create an autogroup config you will be given the following options:
 
-![Create Autogroup page](/_static/images/features/autogroups/group-creation.png)
+![Create Autogroup page](/_static/images/features/apps/autogroups/group-creation.png)
 
 ```eval_rst
 .. warning::
@@ -28,7 +28,7 @@ When you create an autogroup config you will be given the following options:
 
 - Corp/Alliance groups checkbox toggles Corp/Alliance autogroups on or off for this config.
 
-- Corp/Alliance group prefix sets the prefix for the group name, e.g. if your Corp was called `MyCorp` and your prefix was `Corp `, your autogroup name would be created as `Corp MyCorp`. This field accepts leading/trailing spaces.
+- Corp/Alliance group prefix sets the prefix for the group name, e.g. if your Corp was called `MyCorp` and your prefix was `Corp`, your autogroup name would be created as `Corp MyCorp`. This field accepts leading/trailing spaces.
 
 - Corp/Alliance name source sets the source of the Corp/Alliance name used in creating the group name. Currently the options are Full name and Ticker.
 

docs/features/apps/corpstats.md

@@ -1,7 +1,9 @@
-# Corp Stats
+# Corporation Stats
 
 This module is used to check the registration status of Corp members and to determine character relationships, being mains or alts.
 
+![corpstats](https://i.imgur.com/9lZhf5g.png)
+
 ## Installation
 
 Corp Stats requires access to the `esi-corporations.read_corporation_membership.v1` SSO scope. Update your application on the [EVE Developers site](https://developers.eveonline.com) to ensure it is available.
@@ -12,17 +14,17 @@ Add `'allianceauth.corputils',` to your `INSTALLED_APPS` list in your auth proje
 
 Upon initial install, nothing will be visible. For every Corp, a model will have to be created before data can be viewed.
 
-![nothing is visible](/_static/images/features/corpstats/blank_header.png)
+![nothing is visible](/_static/images/features/apps/corpstats/blank_header.png)
 
 If you are a superuser, the add button will be immediate visible to you. If not, your user account requires the `add_corpstats` permission.
 
 Corp Stats requires an EVE SSO token to access data from the EVE Swagger Interface. Upon pressing the Add button, you will be prompted to authenticated. Please select the character who is in the Corporation you want data for.
 
-![authorize from the EVE site](/_static/images/features/corpstats/eve_sso_authorization.png)
+![authorize from the EVE site](/_static/images/features/apps/corpstats/eve_sso_authorization.png)
 
 You will return to auth where you are asked to select a token with the green arrow button. If you want to use a different character, press the `LOG IN with EVE Online` button.
 
-![select an SSO token to create with](/_static/images/features/corpstats/select_sso_token.png)
+![select an SSO token to create with](/_static/images/features/apps/corpstats/select_sso_token.png)
 
 If this works (and you have permission to view the Corp Stats you just created) you'll be returned to a view of the Corp Stats.
 If it fails an error message will be displayed.
@@ -31,7 +33,7 @@ If it fails an error message will be displayed.
 
 ### Navigation Bar
 
-![navigation bar](/_static/images/features/corpstats/navbar.png)
+![navigation bar](/_static/images/features/apps/corpstats/navbar.png)
 
 This bar contains a dropdown menu of all available Corporations. If the user has the `add_corpstats` permission, a button to add a Corp Stats will be shown.
 
@@ -39,52 +41,51 @@ On the right of this bar is a search field. Press enter to search. It checks all
 
 ### Last Update
 
-![last update and update button](/_static/images/features/corpstats/last_update.png)
+![last update and update button](/_static/images/features/apps/corpstats/last_update.png)
 
 An update can be performed immediately by pressing the update button. Anyone who can view the Corp Stats can update it.
 
 ### Character Lists
 
-![lists](/_static/images/features/corpstats/lists.png)
+![lists](/_static/images/features/apps/corpstats/lists.png)
 
 Three views are available:
- - main characters and their alts
+
- - registered characters and their main character
+- main characters and their alts
- - unregistered characters
+- registered characters and their main character
+- unregistered characters
 
 Each view contains a sortable and searchable table. The number of listings shown can be increased with a dropdown selector. Pages can be changed using the controls on the bottom-right of the table. Each list is searchable at the top-right. Tables can be re-ordered by clicking on column headings.
 
-![table control locations](/_static/images/features/corpstats/table_controls.png)
+![table control locations](/_static/images/features/apps/corpstats/table_controls.png)
 
 #### Main List
 
-![main list](/_static/images/features/corpstats/main_list.png)
+![main list](/_static/images/features/apps/corpstats/main_list.png)
 
 This list contains all main characters in registered in the selected Corporation and their alts. Each character has a link to [zKillboard](https://zkillboard.com).
 
-
 #### Member List
 
-![member list](/_static/images/features/corpstats/member_list.png)
+![member list](/_static/images/features/apps/corpstats/member_list.png)
 
 The list contains all characters in the Corporation. Red backgrounds means they are not registered in auth. A link to [zKillboard](https://zkillboard.com) is present for all characters.
 If registered, the character will also have a main character, main Corporation, and main Alliance field.
 
 #### Unregistered List
 
-![unregistered_list](/_static/images/features/corpstats/unregistered_list.png)
+![unregistered_list](/_static/images/features/apps/corpstats/unregistered_list.png)
 
 This list contains all characters not registered on auth. Each character has a link to [zKillboard](https://zkillboard.com).
 
 ## Search View
 
-![search results](/_static/images/features/corpstats/search_view.png)
+![search results](/_static/images/features/apps/corpstats/search_view.png)
 
 This view is essentially the same as the Corp Stats page, but not specific to a single Corporation.
 The search query is visible in the search box.
 Characters from all Corp Stats to which the user has view access will be displayed. APIs respect permissions.
 
-
 ## Permissions
 
 To use this feature, users will require some of the following:
@@ -108,15 +109,18 @@ To use this feature, users will require some of the following:
 
 ```
 
-Users who add a Corp Stats with their token will be granted permissions to view it regardless of the above permissions. View permissions are interpreted in the "OR" sense: a user can view their Corporations's Corp Stats without the `view_corp_corpstats` permission if they have the `view_alliance_corpstats` permission, same idea for their state. Note that these evaluate against the user's main character.
+Users who add a Corp Stats with their token will be granted permissions to view it regardless of the above permissions. View permissions are interpreted in the "OR" sense: a user can view their corporation's Corp Stats without the `view_corp_corpstats` permission if they have the `view_alliance_corpstats` permission, same idea for their state. Note that these evaluate against the user's main character.
 
 ## Automatic Updating
+
 By default Corp Stats are only updated on demand. If you want to automatically refresh on a schedule, add an entry to your project's settings file:
 
-    CELERYBEAT_SCHEDULE['update_all_corpstats'] = {
+```python
+CELERYBEAT_SCHEDULE['update_all_corpstats'] = {
     'task': 'allianceauth.corputils.tasks.update_all_corpstats',
     'schedule': crontab(minute=0, hour="*/6"),
-    }
+}
+```
 
 Adjust the crontab as desired.
 

docs/features/apps/fleetactivitytracking.md

@@ -1,5 +1,9 @@
 # Fleet Activity Tracking
 
+The Fleet Activity Tracking (FAT) app allows you to track fleet participation.
+
+![fat](/_static/images/features/apps/fat.png)
+
 ## Installation
 
 Fleet Activity Tracking requires access to the `esi-location.read_location.v1`, `esi-location.read_ship_type.v1`, and `esi-universe.read_structures.v1` SSO scopes. Update your application on the [EVE Developers site](https://developers.eveonline.com) to ensure these are available.

docs/features/apps/hrapplications.md

@@ -1,5 +1,13 @@
 # HR Applications
 
+This app allows you to manage applications for multiple corporations in your alliance. Key features include:
+
+- Define application questionnaires for corporations
+- Users can apply to corporations by filling outquestionnaires
+- Manage review and approval process of applications
+
+![hr](/_static/images/features/apps/hr.png)
+
 ## Installation
 
 Add `'allianceauth.hrapplications',` to your `INSTALLED_APPS` list in your auth project's settings file. Run migrations to complete installation.

docs/features/apps/index.md

@@ -0,0 +1,17 @@
+# Apps
+
+**Alliance Auth** comes with a set of apps (also called plugin-apps) which provide basic functions useful to many organizations in Eve Online like a fleet schedule and a timerboard. This section describes which apps are available and how to install and use them. Please note that any app need to be installed before it can be used.
+
+```eval_rst
+.. toctree::
+    :maxdepth: 1
+
+    autogroups
+    corpstats
+    fleetactivitytracking
+    hrapplications
+    optimer
+    permissions_tool
+    srp
+    timerboard
+```

docs/features/apps/optimer.md

@@ -0,0 +1,9 @@
+# Fleet Operations
+
+Fleet Operations is an app for organizing and communicating fleet schedules.
+
+![optimer](/_static/images/features/apps/optimer.png)
+
+## Installation
+
+Add `'allianceauth.optimer',` to your `INSTALLED_APPS` list in your auth project's settings file. Run migrations to complete installation.

docs/features/apps/permissions_tool.md

@@ -2,9 +2,9 @@
 
 Access to most of Alliance Auth's features are controlled by Django's permissions system. In order to help you secure your services, Alliance Auth provides a permissions auditing tool.
 
-## Installation
+This is an optional app that needs to be installed.
 
-Add `'allianceauth.permissions_tool',` to your `INSTALLED_APPS` list in your auth project's settings file.
+To install it add `'allianceauth.permissions_tool',` to your `INSTALLED_APPS` list in your auth project's settings file.
 
 ## Usage
 
@@ -14,12 +14,11 @@ In order to grant users access to the permissions auditing tool they will need t
 
 When a user has access to the tool they will see the "Permissions Audit" menu item under the "Util" sub menu.
 
-
 ### Permissions Overview
 
 The first page gives you a general overview of permissions and how many users have access to each permission.
 
-![permissions overview](/_static/images/features/permissions_tool/overview.png)
+![permissions overview](/_static/images/features/apps/permissions_tool/overview.png)
 
 **App**, **Model** and **Code Name** contain the internal details of the permission while **Name** contains the name/description you'll see in the admin panel.
 
@@ -35,6 +34,6 @@ Clicking on the **Code Name** link will take you to the [Permissions Audit Page]
 
 The permissions audit page will give you an overview of all the users who have access to this permission either directly or granted via group membership.
 
-![permissions audit](/_static/images/features/permissions_tool/audit.png)
+![permissions audit](/_static/images/features/apps/permissions_tool/audit.png)
 
 Please note that users may appear multiple times if this permission is granted via multiple sources.

docs/features/apps/srp.md

@@ -0,0 +1,9 @@
+# Ship Replacement
+
+Ship Replacement helps you to organize ship replacement programs (SRP) for your alliance.
+
+![srp](/_static/images/features/apps/srp.png)
+
+## Installation
+
+Add `'allianceauth.srp',` to your `INSTALLED_APPS` list in your auth project's settings file. Run migrations to complete installation.

docs/features/apps/timerboard.md

@@ -0,0 +1,9 @@
+# Structure Timers
+
+Structure Timers helps you keep track of both offensive and defensive structure timers in your space.
+
+![timerboard](/_static/images/features/apps/timerboard.png)
+
+## Installation
+
+Add `'allianceauth.timerboard',` to your `INSTALLED_APPS` list in your auth project's settings file. Run migrations to complete installation.

docs/features/community/index.md

@@ -0,0 +1,7 @@
+# Community Contributions
+
+Another key feature of **Alliance Auth** is that it can be easily extended. Our  great community is providing a variety of plug-in apps and services, which you can choose from to add more functions to your AA installation.
+
+Check out the [Community Creations](https://gitlab.com/allianceauth/community-creations) repo for more details.
+
+Or if you have very specific needs you can of course develop your own plugin- apps and services. Please see the [Development](/development/index.md) chapter details.

docs/features/core/dashboard.md

@@ -0,0 +1,9 @@
+# Dashboard
+
+The dashboard is the main page of the **Alliance Auth** website and the first page every logged in user will see.
+
+The content of the dashboard is specific to the logged in user. It has a sidebar, which will display the list of apps a user currently as access to based on his permissions. And it also shows which character the user has registered and to which group he belongs.
+
+For admin users the dashboard shows additional technical information about the  AA instance.
+
+![dashboard](/_static/images/features/core/dashboard/dashboard.png)

docs/features/core/groupmanagement.md

@@ -0,0 +1,41 @@
+# Group Management
+
+In order to access group management, users need to be either a superuser, granted the `auth | user | group_management ( Access to add members to groups within the alliance )` permission or a group leader (discussed later).
+
+## Group Requests
+
+When a user joins or leaves a group which is not marked as "Open", their group request will have to be approved manually by a user with the `group_management` permission or by a group leader of the group they are requesting.
+
+## Group Membership
+
+The group membership tab gives an overview of all of the non-internal groups.
+
+![Group overview](/_static/images/features/core/groupmanagement/group-membership.png)
+
+### Group Member Management
+
+Clicking on the blue eye will take you to the group member management screen. Here you can see a list of people who are in the group, and remove members where necessary.
+
+![Group overview](/_static/images/features/core/groupmanagement/group-member-management.png)
+
+### Group Audit Log
+
+Whenever a user Joins, Leaves, or is Removed from a group, this is logged. To find the audit log for a given group, click the light-blue button to the right of the Group Member Management (blue eye) button.
+
+These logs contain the Date and Time the action was taken (in EVE/UTC), the user which submitted the request being acted upon (requestor), the user's main character, the type of request (join, leave or removed), the action taken (accept, reject or remove), and the user that took the action (actor).
+
+![Audit Log Example](/_static/images/features/core/groupmanagement/group_audit_log.png)
+
+```eval_rst
+.. note::
+    There is no tracking for "Open" groups as members are able to freely join/leave these groups.
+```
+
+## Group Leaders
+
+Group leaders have the same abilities as users with the `group_management` permission, _however_, they will only be able to:
+
+- Approve requests for groups they are a leader of.
+- View the Group Membership and Group Members of groups they are leaders of.
+
+This allows you to more finely control who has access to manage which groups. Currently it is not possible to add a Group as group leaders.

docs/features/core/groups.md

@@ -1,42 +1,45 @@
 # Groups
+
 Group Management is one of the core tasks of Alliance Auth. Many of Alliance Auth's services allow for synchronising of group membership, allowing you to grant permissions or roles in services to access certain aspects of them.
 
-## User Organised Groups
+## User Organized Groups
 
 Administrators can create custom groups for users to join. Examples might be groups like `Leadership`, `CEO` or `Scouts`.
 
 When you create a `Group` additional settings are available beyond the normal Django group model. The admin page looks like this:
 
-![AuthGroup Admin page](/_static/images/features/group-admin.png)
+![AuthGroup Admin page](/_static/images/features/core/groupmanagement/group-admin.png)
 
 Here you have several options:
 
-#### Internal
+### Internal
+
 Users cannot see, join or request to join this group. This is primarily used for Auth's internally managed groups, though can be useful if you want to prevent users from managing their membership of this group themselves. This option will override the Hidden, Open and Public options when enabled.
 
 By default, every new group created will be an internal group.
 
-#### Hidden
+### Hidden
+
 Group is hidden from the user interface, but users can still join if you give them the appropriate join link. The URL will be along the lines of `https://example.com/en/group/request_add/{group_id}`. You can get the Group ID from the admin page URL.
 
 This option still respects the Open option.
 
-
 ### Open
+
 When a group is toggled open, users who request to join the group will be immediately added to the group. 
 
 If the group is not open, their request will have to be approved manually by someone with the group management role, or a group leader of that group.
 
-
 ### Public
+
 Group is accessible to any registered user, even when they do not have permission to join regular groups.
 
 The key difference is that the group is completely unmanaged by Auth. **Once a member joins they will not be removed unless they leave manually, you remove them manually, or their account is deliberately set inactive or deleted.**
 
-Most people won't have a use for public groups, though it can be useful if you wish to allow public access to some services. You can grant service permissions on a public group to allow this behaviour.
+Most people won't have a use for public groups, though it can be useful if you wish to allow public access to some services. You can grant service permissions on a public group to allow this behavior.
-
 
 ## Permission
+
 In order to join a group other than a public group, the permission `groupmanagement.request_groups` (`Can request non-public groups` in the admin panel) must be active on their account, either via a group or directly applied to their User account.
 
 When a user loses this permission, they will be removed from all groups _except_ Public groups.
@@ -45,44 +48,3 @@ When a user loses this permission, they will be removed from all groups _except_
 .. note::
     By default, the ``groupmanagement.request_groups`` permission is applied to the ``Member`` group. In most instances this, and perhaps adding it to the ``Blue`` group, should be all that is ever needed. It is unsupported and NOT advisable to apply this permission to a public group. See #697 for more information.
 ```
-
-# Group Management
-
-In order to access group management, users need to be either a superuser, granted the `auth | user | group_management ( Access to add members to groups within the alliance )` permission or a group leader (discussed later).
-
-## Group Requests
-
-When a user joins or leaves a group which is not marked as "Open", their group request will have to be approved manually by a user with the `group_management` permission or by a group leader of the group they are requesting.
-
-## Group Membership
-
-The group membership tab gives an overview of all of the non-internal groups.
-
-![Group overview](/_static/images/features/group-membership.png)
-
-### Group Member Management
-
-Clicking on the blue eye will take you to the group member management screen. Here you can see a list of people who are in the group, and remove members where necessary.
-
-![Group overview](/_static/images/features/group-member-management.png)
-
-### Group Audit Log
-Whenever a user Joins, Leaves, or is Removed from a group, this is logged. To find the audit log for a given group, click the light-blue button to the right of the Group Member Management (blue eye) button.
-
-These logs contain the Date and Time the action was taken (in EVE/UTC), the user which submitted the request being acted upon (requestor), the user's main character, the type of request (join, leave or removed), the action taken (accept, reject or remove), and the user that took the action (actor).
-
-![Audit Log Example](/_static/images/features/group_audit_log.png)
-
-```eval_rst
-.. note::
-    There is no tracking for "Open" groups as members are able to freely join/leave these groups.
-```
-
-## Group Leaders
-
-Group leaders have the same abilities as users with the `group_management` permission, _however_, they will only be able to:
-
-- Approve requests for groups they are a leader of.
-- View the Group Membership and Group Members of groups they are leaders of.
-
-This allows you to more finely control who has access to manage which groups. Currently it is not possible to add a Group as group leaders.

docs/features/core/index.md

@@ -0,0 +1,13 @@
+# Core Features
+
+Managing access to applications and services is one of the core functions of **Alliance Auth**. The related key concepts and functionalities are describes in this section.
+
+```eval_rst
+.. toctree::
+    :maxdepth: 1
+
+    dashboard
+    states
+    groups
+    groupmanagement
+```

docs/features/core/states.md

@@ -1,38 +1,49 @@
-# The State System
+# States
 
-## Overview
+States define the basic role of a user based on his affiliation with your organization. A user that has a character in your organization (e.g. alliance) will usually have the `Member` state. And a user, that has no characters in your organization will usually have the `Guest` state.
 
-In Alliance Auth v1 admins were able to define which Corporations and Alliances were to be considered "members" with full permissions and "blues" with restricted permissions. The state system is the replacement for these static definitions: admins can now create as many states as desired, as well as extend membership to specific characters.
+States are assigned and updated automatically. So a user which character just left your organization will automatically loose his `Member` state and get the `Guest` state instead.
+
+The main purpose of states like `Member` is to have one place where you can assign all permissions that should apply to all users with that particular state. For example if all your members should have access to the SRP app you would add the permission that gives access to the SRP app to the `Member` state.
 
 ## Creating a State
+
 States are created through your installation's admin site. Upon install three states are created for you: `Member`, `Blue`, and `Guest`. New ones can be created like any other Django model by users with the appropriate permission (`authentication | state | Can add state`) or superusers.
 
 A number of fields are available and are described below.
 
 ### Name
+
 This is the displayed name of a state. Should be self-explanatory.
 
 ### Permissions
+
 This lets you select permissions to grant to the entire state, much like a group. Any user with this state will be granted these permissions.
 
 A common use case would be granting service access to a state.
 
 ### Priority
+
 This value determines the order in which states are applied to users. Higher numbers come first. So if a random user `Bob` could member of both the `Member` and `Blue` states, because `Member` has a higher priority `Bob` will be assigned to it.
 
 ### Public
+
 Checking this box means this state is available to all users. There isn't much use for this outside the `Guest` state.
 
 ### Member Characters
+
 This lets you select which characters the state is available to. Characters can be added by selecting the green plus icon.
 
 ### Member Corporations
+
 This lets you select which Corporations the state is available to. Corporations can be added by selecting the green plus icon.
 
 ### Member Alliances
+
 This lets you select which Alliances the state is available to. Alliances can be added by selecting the green plus icon.
 
 ## Determining a User's State
+
 States are mutually exclusive, meaning a user can only be in one at a time.
 
 Membership is determined based on a user's main character. States are tested in order of descending priority - the first one which allows membership to the main character is assigned to the user.
@@ -42,6 +53,7 @@ States are automatically assigned when a user registers to the site, their main
 Assigned states are visible in the `Users` section of the `Authentication` admin site.
 
 ## The Guest State
+
 If no states are available to a user's main character, or their account has been deactivated, they are assigned to a catch-all `Guest` state. This state cannot be deleted nor can its name be changed.
 
 The `Guest` state allows permissions to be granted to users who would otherwise not get any. For example access to public services can be granted by giving the `Guest` state a service access permission.

docs/features/index.md

@@ -1,20 +1,14 @@
 # Features
 
+Learn about the features of **Alliance Auth** and how to install and use them.
+
 ```eval_rst
 .. toctree::
     :maxdepth: 1
-    :caption: Features Contents
 
-    states
+    overview
-    groups
+    core/index
-    autogroups
+    services/index
-    hrapplications
+    apps/index
-    corpstats
+    community/index
-    permissions_tool
-    nameformats
-    fleetup
-    fleetactivitytracking
-    optimer
-    srp
-    timerboard
 ```

docs/features/optimer.md

@@ -1,5 +0,0 @@
-# Optimer
-
-## Installation
-
-Add `'allianceauth.optimer',` to your `INSTALLED_APPS` list in your auth project's settings file. Run migrations to complete installation.

docs/features/overview.md

@@ -0,0 +1,19 @@
+# Overview
+
+**Alliance Auth** (AA) is a web application that helps Eve Online organizations efficiently manage access to external services and web apps.
+
+It has the following key features:
+
+- Automatically grants or revokes users access to external services (e.g. Discord, Mumble) and web apps (e.g. SRP requests) based on the user's current membership to [in-game organizations](/features/core/states) and [groups](/features/core/groups)
+
+- Provides a central web site where users can directly access web apps (e.g. SRP requests) and manage their access to external services and groups.
+
+- Includes a set of connectors (called ["services"](/features/services/index)) for integrating access management with many popular external services like Discord, Mumble, Teamspeak 3, SMF and others
+
+- Includes a set of web [apps](/features/apps/index) which add many useful functions, e.g.: fleet schedule, timer board, SRP request management, fleet activity tracker
+
+- Can be easily extended with additional services and apps. Many are provided by the [community](/features/community/index).
+
+Here is an example how the main page of the web site looks:
+
+![dashboard](/_static/images/features/core/dashboard/dashboard.png)

docs/features/services/discord.md

@@ -1,5 +1,7 @@
 # Discord
+
 ## Overview
+
 Discord is a web-based instant messaging client with voice. Kind of like TeamSpeak meets Slack meets Skype. It also has a standalone app for phones and desktop.
 
 Discord is very popular amongst ad-hoc small groups and larger organizations seeking a modern technology. Alternative voice communications should be investigated for larger than small-medium groups for more advanced features.
@@ -12,11 +14,13 @@ Discord is very popular amongst ad-hoc small groups and larger organizations see
 ```
 
 ### Prepare Your Settings File
+
 In your auth project's settings file, do the following:
- - Add `'allianceauth.services.modules.discord',` to your `INSTALLED_APPS` list
- - Append the following to the bottom of the settings file:
 
+- Add `'allianceauth.services.modules.discord',` to your `INSTALLED_APPS` list
+- Append the following to the bottom of the settings file:
 
+```python
     # Discord Configuration
     DISCORD_GUILD_ID = ''
     DISCORD_CALLBACK_URL = ''
@@ -24,8 +28,10 @@ In your auth project's settings file, do the following:
     DISCORD_APP_SECRET = ''
     DISCORD_BOT_TOKEN = ''
     DISCORD_SYNC_NAMES = False
+```
 
 ### Creating a Server
+
 Navigate to the [Discord site](https://discordapp.com/) and register an account, or log in if you have one already.
 
 On the left side of the screen you’ll see a circle with a plus sign. This is the button to create a new server. Go ahead and do that, naming it something obvious.
@@ -50,14 +56,17 @@ Update your auth project's settings file, inputting this redirect address as `DI
 On the application summary page, press Create a Bot User.
 
 Update your auth project's settings file with these pieces of information from the summary page:
- - From the App Details panel, `DISCORD_APP_ID` is the Client/Application ID
+
- - From the App Details panel, `DISCORD_APP_SECRET` is the Secret
+- From the App Details panel, `DISCORD_APP_ID` is the Client/Application ID
- - From the App Bot Users panel, `DISCORD_BOT_TOKEN` is the Token
+- From the App Details panel, `DISCORD_APP_SECRET` is the Secret
+- From the App Bot Users panel, `DISCORD_BOT_TOKEN` is the Token
 
 ### Preparing Auth
+
 Before continuing it is essential to run migrations and restart Gunicorn and Celery.
 
 ### Adding a Bot to the Server
+
 Once created, navigate to the services page of your Alliance Auth install as the superuser account. At the top there is a big green button labelled Link Discord Server. Click it, then from the drop down select the server you created, and then Authorize.
 
 This adds a new user to your Discord server with a `BOT` tag, and a new role with the same name as your Discord application. Don't touch either of these. If for some reason the bot loses permissions or is removed from the server, click this button again.
@@ -67,15 +76,19 @@ To manage roles, this bot role must be at the top of the hierarchy. Edit your Di
 Note that the bot will never appear online as it does not participate in chat channels.
 
 ### Linking Accounts
+
 Instead of the usual account creation procedure, for Discord to work we need to link accounts to Alliance Auth. When attempting to enable the Discord service, users are redirected to the official Discord site to authenticate. They will need to create an account if they don't have one prior to continuing. Upon authorization, users are redirected back to Alliance Auth with an OAuth code which is used to join the Discord server.
 
 ### Syncing Nicknames
+
 If you want users to have their Discord nickname changed to their in-game character name, set `DISCORD_SYNC_NAMES` to `True`
 
 ## Managing Roles
+
 Once users link their accounts you’ll notice Roles get populated on Discord. These are the equivalent to Groups on every other service. The default permissions should be enough for members to use text and audio communications. Add more permissions to the roles as desired through the server management window.
 
 ## Troubleshooting
 
 ### "Unknown Error" on Discord site when activating service
+
 This indicates your callback URL doesn't match. Ensure the `DISCORD_CALLBACK_URL` setting exactly matches the URL entered on the Discord developers site. This includes http(s), trailing slash, etc.

docs/features/services/discourse.md

@@ -1,17 +1,19 @@
 # Discourse
 
 ## Prepare Your Settings
+
 In your auth project's settings file, do the following:
- - Add `'allianceauth.services.modules.discourse',` to your `INSTALLED_APPS` list
- - Append the following to your local.py settings file:
 
+- Add `'allianceauth.services.modules.discourse',` to your `INSTALLED_APPS` list
+- Append the following to your local.py settings file:
 
+```python
     # Discourse Configuration
     DISCOURSE_URL = ''
     DISCOURSE_API_USERNAME = ''
     DISCOURSE_API_KEY = ''
     DISCOURSE_SSO_SECRET = ''
-
+```
 
 ## Install Docker
 
@@ -31,9 +33,10 @@ In your auth project's settings file, do the following:
     nano containers/app.yml
 
 Change the following:
- - `DISCOURSE_DEVELOPER_EMAILS` should be a list of admin account email addresses separated by commas.
+
- - `DISCOUSE_HOSTNAME` should be `discourse.example.com` or something similar.
+- `DISCOURSE_DEVELOPER_EMAILS` should be a list of admin account email addresses separated by commas.
- - Everything with `SMTP` depends on your mail settings. [There are plenty of free email services online recommended by Discourse](https://github.com/discourse/discourse/blob/master/docs/INSTALL-email.md#recommended-email-providers-for-discourse) if you haven't set one up for auth already.
+- `DISCOUSE_HOSTNAME` should be `discourse.example.com` or something similar.
+- Everything with `SMTP` depends on your mail settings. [There are plenty of free email services online recommended by Discourse](https://github.com/discourse/discourse/blob/master/docs/INSTALL-email.md#recommended-email-providers-for-discourse) if you haven't set one up for auth already.
 
 To install behind Apache/Nginx, look for this section:
 
@@ -109,16 +112,18 @@ Follow prompts, being sure to answer `y` when asked to allow admin privileges.
 Navigate to `discourse.example.com` and log on. Top right press the 3 lines and select `Admin`. Go to API tab and press `Generate Master API Key`.
 
 Add the following values to your auth project's settings file:
- - `DISCOURSE_URL`: `https://discourse.example.com` (do not add a trailing slash!)
+
- - `DISCOURSE_API_USERNAME`: the username of the admin account you generated the API key with
+- `DISCOURSE_URL`: `https://discourse.example.com` (do not add a trailing slash!)
- - `DISCOURSE_API_KEY`: the key you just generated
+- `DISCOURSE_API_USERNAME`: the username of the admin account you generated the API key with
+- `DISCOURSE_API_KEY`: the key you just generated
 
 ### Configure SSO
 
 Navigate to `discourse.example.com` and log in. Back to the admin site, scroll down to find SSO settings and set the following:
- - `enable_sso`: True
+
- - `sso_url`: `http://example.com/discourse/sso`
+- `enable_sso`: True
- - `sso_secret`: some secure key
+- `sso_url`: `http://example.com/discourse/sso`
+- `sso_secret`: some secure key
 
 Save, now set `DISCOURSE_SSO_SECRET` in your auth project's settings file to the secure key you just put in Discourse.
 

docs/features/services/index.md

@@ -0,0 +1,29 @@
+# Services
+
+**Alliance Auth** supports managing access to many 3rd party services and apps. This section describes which services are supported and how to install and configure them. Please note that any service need to be installed and configured before it can be used.
+
+## Supported Services
+
+```eval_rst
+.. toctree::
+    :maxdepth: 1
+
+    discord
+    discourse
+    mumble
+    openfire
+    phpbb3
+    smf
+    teamspeak3
+    xenforo
+```
+
+## Tools
+
+```eval_rst
+.. toctree::
+    :maxdepth: 1
+
+    nameformats
+    permissions
+```

docs/features/services/mumble.md

@@ -5,9 +5,10 @@ In your auth project's settings file, do the following:
  - Add `'allianceauth.services.modules.mumble',` to your `INSTALLED_APPS` list
  - Append the following to your local.py settings file:
 
-
+```python
     # Mumble Configuration
     MUMBLE_URL = ""
+```
 
 ## 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.

docs/features/services/nameformats.md

@@ -1,11 +1,8 @@
 # Services Name Formats
 
-```eval_rst
+This app allows you to customize how usernames for services are created.
-.. note::
-    New in 2.0
-```
 
-Each service's username or nickname, depending on which the service supports, can be customised through the use of the Name Formatter config provided the service supports custom formats. This config can be found in the admin panel under **Services -> Name format config**
+Each service's username or nickname, depending on which the service supports, can be customized through the use of the Name Formatter config provided the service supports custom formats. This config can be found in the admin panel under **Services -> Name format config**
 
 Currently the following services support custom name formats:
 
@@ -35,24 +32,24 @@ Currently the following services support custom name formats:
 
 ```eval_rst
 .. note::
-    It's important to note here, before we get into what you can do with a name formatter, that before the generated name is passed off to the service to create an account it will be sanitised to remove characters (the letters and numbers etc.) that the service cannot support. This means that, despite what you configured, the service may display something different. It is up to you to test your formatter and understand how your format may be disrupted by a certain services sanitisation function.
+    It's important to note here, before we get into what you can do with a name formatter, that before the generated name is passed off to the service to create an account it will be sanitized to remove characters (the letters and numbers etc.) that the service cannot support. This means that, despite what you configured, the service may display something different. It is up to you to test your formatter and understand how your format may be disrupted by a certain services sanitization function.
 ```
 
 ## Available format data
 
 The following fields are available from a users account and main character:
 
- - `username` - Alliance Auth username
+- `username` - Alliance Auth username
- - `character_id`
+- `character_id`
- - `character_name`
+- `character_name`
- - `corp_id`
+- `corp_id`
- - `corp_name`
+- `corp_name`
- - `corp_ticker`
+- `corp_ticker`
- - `alliance_id`
+- `alliance_id`
- - `alliance_name`
+- `alliance_name`
- - `alliance_ticker`
+- `alliance_ticker`
- - `alliance_or_corp_name` (defaults to Corporation name if there is no Alliance)
+- `alliance_or_corp_name` (defaults to Corporation name if there is no Alliance)
- - `alliance_or_corp_ticker` (defaults to Corporation ticker if there is no Alliance)
+- `alliance_or_corp_ticker` (defaults to Corporation ticker if there is no Alliance)
 
 ## Building a formatter string
 
@@ -61,6 +58,7 @@ The name formatter uses the advanced string formatting specified by [PEP-3101](h
 A more digestible documentation of string formatting in Python is available on the [PyFormat](https://pyformat.info/) website.
 
 Some examples of strings you could use:
+
 ```eval_rst
 +------------------------------------------+---------------------------+
 | Formatter                                | Result                    |

docs/features/services/openfire.md

@@ -3,10 +3,11 @@
  Openfire is a Jabber (XMPP) server.
 
 ## Prepare Your Settings
- - Add `'allianceauth.services.modules.openfire',` to your `INSTALLED_APPS` list
- - Append the following to your auth project's settings file:
 
+- Add `'allianceauth.services.modules.openfire',` to your `INSTALLED_APPS` list
+- Append the following to your auth project's settings file:
 
+```python
     # Jabber Configuration
     JABBER_URL = ""
     JABBER_PORT = 5223
@@ -16,6 +17,7 @@
     BROADCAST_USER = ""
     BROADCAST_USER_PASSWORD = ""
     BROADCAST_SERVICE_NAME = "broadcast"
+```
 
 ## Dependencies
 Openfire require a Java 8 runtime environment.

docs/features/services/phpbb3.md

@@ -11,7 +11,7 @@ In your auth project's settings file, do the following:
  - Add `'allianceauth.services.modules.phpbb3',` to your `INSTALLED_APPS` list
  - Append the following to the bottom of the settings file:
 
-
+```python
     # PHPBB3 Configuration
     PHPBB3_URL = ''
     DATABASES['phpbb3'] = {
@@ -22,6 +22,7 @@ In your auth project's settings file, do the following:
         'HOST': '127.0.0.1',
         'PORT': '3306',
     }
+```
 
 ## Setup
 ### Prepare the Database
@@ -136,14 +137,11 @@ Before users can see the forums, we need to remove the install directory
     rm -rf /var/www/forums/install
 
 ### Enabling Avatars
+
 AllianceAuth sets user avatars to their character portrait when the account is created or password reset. We need to allow external URLs for avatars for them to behave properly. Navigate to the admin control panel for phpbb3, and under the `General` tab, along the left navigation bar beneath `Board Configuration`, select `Avatar Settings`. Set `Enable Remote Avatars` to `Yes` and then `Submit`.
 
-![location of the remote avatar setting](/_static/images/installation/services/phpbb3/avatar_settings.png)
-
 You can allow members to overwrite the portrait with a custom image if desired. Navigate to `Users and Groups`, `Group Permissions`, select the appropriate group (usually `Member` if you want everyone to have this ability), expand `Advanced Permissions`, under the `Profile` tab, set `Can Change Avatars` to `Yes`, and press `Apply Permissions`.
 
-![location of change avatar setting](/_static/images/installation/services/phpbb3/avatar_permissions.png)
-
 ## Setting the default theme
 
 Users generated via Alliance Auth do not have a default theme set. You will need to set this on the phpbb_users table in SQL

docs/features/services/smf.md

@@ -11,7 +11,7 @@ In your auth project's settings file, do the following:
  - Add `'allianceauth.services.modules.smf',` to your `INSTALLED_APPS` list
  - Append the following to the bottom of the settings file:
 
-
+```python
     # SMF Configuration
     SMF_URL = ''
     DATABASES['smf'] = {
@@ -22,6 +22,7 @@ In your auth project's settings file, do the following:
         'HOST': '127.0.0.1',
         'PORT': '3306',
     }
+```
 
 ## Setup
 ### Download SMF

docs/features/services/teamspeak3.md

@@ -13,7 +13,7 @@ In your auth project's settings file, do the following:
  - Add `'allianceauth.services.modules.teamspeak3',` to your `INSTALLED_APPS` list
  - Append the following to the bottom of the settings file:
 
-
+```python
     # Teamspeak3 Configuration
     TEAMSPEAK3_SERVER_IP = '127.0.0.1'
     TEAMSPEAK3_SERVER_PORT = 10011
@@ -26,6 +26,7 @@ In your auth project's settings file, do the following:
         'task': 'allianceauth.services.modules.teamspeak3.tasks.run_ts3_group_update',
         'schedule': crontab(minute='*/30'),
     }
+```
 
 ### Download Installer
 To install we need a copy of the server. You can find the latest version from [this dl server](http://dl.4players.de/ts/releases/) (I’d recommend getting the latest stable version – find this version number from the [TeamSpeak site](https://www.teamspeak.com/downloads#)). Be sure to get a link to the Linux version.

docs/features/services/xenforo.md

@@ -8,11 +8,12 @@ In your auth project's settings file, do the following:
  - Add `'allianceauth.services.modules.xenforo',` to your `INSTALLED_APPS` list
  - Append the following to your local.py settings file:
 
-
+```python
     # XenForo Configuration
     XENFORO_ENDPOINT = 'example.com/api.php'
     XENFORO_DEFAULT_GROUP = 0
     XENFORO_APIKEY   = 'yourapikey'
+```
 
 ## XenAPI
 

docs/features/srp.md

@@ -1,5 +0,0 @@
-# SRP
-
-## Installation
-
-Add `'allianceauth.srp',` to your `INSTALLED_APPS` list in your auth project's settings file. Run migrations to complete installation.

docs/features/timerboard.md

@@ -1,5 +0,0 @@
-# Timerboard
-
-## Installation
-
-Add `'allianceauth.timerboard',` to your `INSTALLED_APPS` list in your auth project's settings file. Run migrations to complete installation.

docs/index.md

@@ -1,28 +1,18 @@
 
 # Alliance Auth
 
-An auth system for EVE Online to help in-game organizations manage online service access. 
+Welcome to the official documentation for **Alliance Auth**!
-
-# Installing
-
-[Setup Guide](installation/auth/allianceauth.md)
-
-# Using
-
-Learn about individual [features.](features/index.md)
-
-# Troubleshooting
-
-Read the [list of common problems.](maintenance/troubleshooting.md)
 
+**Alliance Auth** is a web application that helps Eve Online organizations efficiently manage access to external services and web apps.
 
 ```eval_rst
 .. toctree::
-    :maxdepth: 3
+    :maxdepth: 2
     :caption: Contents
 
-    features/index
     installation/index
+    features/index
     maintenance/index
     development/index
+    support/index
 ```

docs/installation/allianceauth.md

@@ -0,0 +1,339 @@
+# Alliance Auth
+
+This document describes how to install **Alliance Auth** from scratch.
+
+```eval_rst
+.. tip::
+   If you are uncomfortable with Linux permissions follow the steps below as the root user.
+```
+
+```eval_rst
+.. note::
+   There are additional installation steps for activating services and apps that come with **Alliance Auth**. Please see the page for the respective service or apps in chapter [Features](/features/index) for details.
+```
+
+## Dependencies
+
+### Operating System
+
+Alliance Auth can be installed on any Unix like operating system. Dependencies are provided below for two of the most popular Linux platforms: Ubuntu and CentOS. To install on your favorite 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.5 or higher. Ensure it is installed on your server before proceeding.
+
+Ubuntu:
+
+```bash
+apt-get install python3 python3-dev python3-venv python3-setuptools python3-pip
+```
+
+CentOS:
+
+```bash
+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. Note that Alliance Auth requires Maria DB 10.2.x or higher.
+
+Ubuntu:
+
+```bash
+apt-get install mariadb-server mariadb-client libmysqlclient-dev
+```
+
+CentOS:
+
+```bash
+yum install mariadb-server mariadb-devel mariadb-shared mariadb
+```
+
+```eval_rst
+.. note::
+   If you don't plan on running the database on the same server as auth you still need to install the libmysqlclient-dev package on Ubuntu or mariadb-devel package on CentOS.
+```
+
+### Redis and Other Tools
+
+A few extra utilities are also required for installation of packages.
+
+Ubuntu:
+
+```bash
+apt-get install unzip git redis-server curl libssl-dev libbz2-dev libffi-dev
+```
+
+CentOS:
+
+```bash
+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:
+
+```sql
+CREATE USER 'allianceserver'@'localhost' IDENTIFIED BY 'PASSWORD';
+CREATE DATABASE alliance_auth CHARACTER SET utf8mb4;
+GRANT ALL PRIVILEGES ON alliance_auth . * TO 'allianceserver'@'localhost';
+```
+
+Add timezone tables to your mysql installation:
+
+```bash
+mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root -p mysql
+```
+
+```eval_rst
+.. note::
+   You may see errors when you add the timezone tables. To make sure that they were correctly added run the following commands and check for the ``time_zone`` tables::
+   
+     mysql -u root -p
+     use mysql;
+     show tables;
+```
+
+Close the SQL shell and secure your database server with this command:
+
+```bash
+mysql_secure_installation
+```
+
+## Auth Install
+
+### User Account
+
+For security and permissions, it’s highly recommended you create a separate user to install auth under. Do not log in as this account.
+
+Ubuntu:
+
+```bash
+adduser --disabled-login allianceserver
+```
+
+CentOS:
+
+```bash
+useradd -s /bin/nologin allianceserver
+```
+
+### Virtual Environment
+
+Create a Python virtual environment and put it somewhere convenient (e.g. `/home/allianceserver/venv/auth/`)
+
+```bash
+python3 -m venv /home/allianceserver/venv/auth/
+```
+
+```eval_rst
+.. warning::
+   The python3 command may not be available on all installations. Try a specific version such as ``python3.6`` if this is the case.
+```
+
+```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 virtual environment with (Note the `/bin/activate` on the end of the path):
+
+```bash
+source /home/allianceserver/venv/auth/bin/activate
+```
+
+```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.
+```
+
+### Eve Online SSO
+
+You need to have a dedicated Eve SSO app for Alliance auth. Please go to [EVE Developer](https://developers.eveonline.com/applications) to create one.
+
+For **scopes** your SSO app needs to have at least `publicData`. Additional scopes depends on which Alliance Auth apps you will be using. For convenience we recommend adding all available ESO scopes to your SSO app. Note that Alliance Auth will always ask the users to approve specific scopes before they are used.
+
+As **callback URL** you want to define the URL of your Alliance Auth site plus the route: `/sso/callback`. Example for a valid callback URL: `https://auth.example.com/sso/callback`
+
+### Alliance Auth Project
+
+Ensure wheel is available before continuing:
+
+```bash
+pip install wheel
+```
+
+You can install **Alliance Auth** with the following command. This will install AA and all its Python dependencies.
+
+```bash
+pip install allianceauth
+```
+
+Now you need to create the application that will run the **Alliance Auth** install. Ensure you are in the allianceserver home directory by issuing:
+
+```bash
+cd /home/allianceserver
+```
+
+The following command bootstraps a Django project which will run your **Alliance Auth** instance. You can rename it from `myauth` to anything you'd like. Note that this name is shown by default as the site name but that can be changed later.
+
+```bash
+allianceauth start myauth
+```
+
+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.
+
+```bash
+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.
+
+```bash
+mkdir -p /var/www/myauth/static
+python /home/allianceserver/myauth/manage.py collectstatic
+```
+
+Check to ensure your settings are valid.
+
+```bash
+python /home/allianceserver/myauth/manage.py check
+```
+
+And finally ensure the allianceserver user has read/write permissions to this directory before proceeding.
+
+```bash
+chown -R allianceserver:allianceserver /home/allianceserver/myauth
+```
+
+## Services
+
+Alliance Auth needs some additional services to run, which we will setup and configure next.
+
+### Gunicorn
+
+To run the **Alliance Auth** website a [WSGI Server](https://www.fullstackpython.com/wsgi-servers.html) is required. For this [Gunicorn](http://gunicorn.org/) is highly recommended for its ease of configuring. It can be manually run from within your `myauth` base directory with `gunicorn --bind 0.0.0.0 myauth.wsgi` or automatically run using Supervisor.
+
+The default configuration is good enough for most installations. Additional information is available in the [gunicorn](gunicorn.md) doc.
+
+Use this command to install Gunicorn:
+
+```bash
+pip install gunicorn
+```
+
+### 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:
+
+```bash
+apt-get install supervisor
+```
+
+CentOS:
+
+```bash
+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.
+
+Ubuntu:
+
+```bash
+ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisor/conf.d/myauth.conf
+```
+
+CentOS:
+
+```bash
+ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisord.d/myauth.ini
+```
+
+And activate it with `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.
+
+Note that Alliance Auth is designed to run with web servers on HTTPS. While running on HTTP is technically possible, it is not recommended for production use and some functions (e.g. Email confirmation links) will not work properly.
+
+## 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.
+
+```bash
+python /home/allianceserver/myauth/manage.py createsuperuser
+```
+
+The superuser account is accessed by logging in via the admin site at `https://example.com/admin`.
+
+If you intend to use this account as your personal auth account you need to add a main character. Navigate to the normal user dashboard (at `https://example.com`) after logging in via the admin site and select `Change Main`. Once a main character has been added it is possible to use SSO to login to this account.
+
+## Updating
+
+Periodically [new releases](https://gitlab.com/allianceauth/allianceauth/tags) are issued with bug fixes and new features. Be sure to read the [release notes](https://gitlab.com/allianceauth/allianceauth/-/releases) which will highlight changes.
+
+To update your install, simply activate your virtual environment and update with:
+
+```bash
+pip install --upgrade allianceauth
+```
+
+Some releases come with changes to the base settings. Update your project's settings with:
+
+```bash
+allianceauth update /home/allianceserver/myauth
+```
+
+Some releases come with new or changed models. Update your database to reflect this with:
+
+```bash
+python /home/allianceserver/myauth/manage.py migrate
+```
+
+Finally some releases come with new or changed static files. Run the following command to update your static files folder:
+
+```bash
+python /home/allianceserver/myauth/manage.py collectstatic
+```
+
+Always restart AA, Celery and Gunicorn after updating:
+
+```bash
+supervisorctl restart myauth:
+```

docs/installation/auth/allianceauth.md

@@ -1,224 +0,0 @@
-# Alliance Auth Installation
-
-```eval_rst
-.. tip::
-   If you are uncomfortable with Linux permissions follow the steps below as the root user.
-```
-
-## 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.5 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 mariadb-client libmysqlclient-dev
-
-CentOS:
-
-    yum install mariadb-server mariadb-devel mariadb-shared mariadb
-
-```eval_rst
-.. note::
-   If you don't plan on running the database on the same server as auth you still need to install the libmysqlclient-dev package on Ubuntu or mariadb-devel package on CentOS.
-```
-
-### 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 CHARACTER SET utf8mb4;
-    GRANT ALL PRIVILEGES ON alliance_auth . * TO 'allianceserver'@'localhost';
-
-Add timezone tables to your mysql installation:
-
-    mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root -p mysql
-    
-```eval_rst
-.. note::
-   You may see errors when you add the timezone tables. To make sure that they were correctly added run the following commands and check for the ``time_zone`` tables::
-   
-     mysql -u root -p
-     use mysql;
-     show tables;
-```
-
-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 auth under. Do not log in as this account.
-
-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
-.. warning::
-   The python3 command may not be available on all installations. Try a specific version such as ``python3.6`` if this is the case.
-```
-
-```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.
-```
-
-Ensure wheel is available with `pip install wheel` before continuing.
-
-### Alliance Auth Project
-
-You can install the library using `pip install allianceauth`. This will install Alliance Auth and all its python dependencies. You should also install Gunicorn with `pip install gunicorn` before proceeding.
-
-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 bootstraps 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 -p /var/www/myauth/static
-    python /home/allianceserver/myauth/manage.py collectstatic
-
-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. It can be manually run from within your `myauth` base directory with `gunicorn --bind 0.0.0.0 myauth.wsgi` or automatically run using Supervisor.
-
-The default configuration is good enough for most installations. 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.
-
-Ubuntu:
-
-    ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisor/conf.d/myauth.conf
-
-CentOS:
-
-    ln -s /home/allianceserver/myauth/supervisor.conf /etc/supervisord.d/myauth.ini
-
-And activate it with `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
-
-The superuser account is accessed by logging in via the admin site at `https://example.com/admin`.
-
-If you intend to use this account as your personal auth account you need to add a main character. Navigate to the normal user dashboard (at `https://example.com`) after logging in via the admin site and select `Change Main`. Once a main character has been added it is possible to use SSO to login to this account.
-
-## Updating
-
-Periodically [new releases](https://gitlab.com/allianceauth/allianceauth/tags) 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/index.md

@@ -1,11 +0,0 @@
-# Auth
-
-```eval_rst
-.. toctree::
-
-    allianceauth
-    upgradev1
-    gunicorn
-    nginx
-    apache
-```

docs/installation/gunicorn.md

@@ -6,6 +6,11 @@ If you find Apache's `mod_wsgi` to be a headache or want to use NGINX (or some o
 
 Check out the full [Gunicorn docs](http://docs.gunicorn.org/en/latest/index.html).
 
+```eval_rst
+.. note::
+   The page contains additional steps on how to setup and configure Gunicorn that are not required for users who decide to stick with the default Gunicorn configuration as described in the main installation guide for AA.
+```
+
 ## Setting up Gunicorn
 
 ```eval_rst
@@ -24,8 +29,10 @@ Once you validate its running, you can kill the process with Ctrl+C and continue
 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/myauth_gunicorn.conf` (or whatever you want to call the config file)
-```
+
+```text
 [program:myauth-gunicorn]
 user = allianceserver
 directory=/home/allianceserver/myauth/
@@ -45,6 +52,7 @@ stopsignal=INT
 See the [Commonly Used Arguments](http://docs.gunicorn.org/en/latest/run.html#commonly-used-arguments) or [Full list of settings](http://docs.gunicorn.org/en/stable/settings.html) for more information.
 
 ##### Where to bind Gunicorn to?
+
 What address are you going to use to reference it? By default, without a bind parameter, Gunicorn will bind to `127.0.0.1:8000`. This might be fine for your application. If it clashes with another application running on that port you will need to change it. I would suggest using UNIX sockets too, if you can.
 
 For UNIX sockets add `--bind=unix:/run/allianceauth.sock` (or to a path you wish to use). Remember that your web server will need to be able to access this socket file.
@@ -54,11 +62,13 @@ For a TCP address add `--bind=127.0.0.1:8001` (or to the address/port you wish t
 Whatever you decide to use, remember it because we'll need it when configuring your webserver.
 
 ##### Number of workers
+
 By default Gunicorn will spawn only one worker. The number you set this to will depend on your own server environment, how many visitors you have etc. Gunicorn suggests between 2-4 workers per core. Really you could probably get away with 2-4 in total for most installs.
 
 Change it by adding `--workers=2` to the command.
 
 ##### Running with a virtual environment
+
 If you're running with a virtual environment, you'll need to add the path to the `command=` config line.
 
 e.g. `command=/path/to/venv/bin/gunicorn myauth.wsgi`
@@ -67,13 +77,12 @@ e.g. `command=/path/to/venv/bin/gunicorn myauth.wsgi`
 
 Once you have your configuration all sorted, you will need to reload your supervisor config `service supervisor reload` and then you can start the Gunicorn server via `supervisorctl start aauth-gunicorn` (or whatever you renamed it to). You should see something like the following `aauth-gunicorn: started`. If you get some other message, you'll need to consult the Supervisor log files, usually found in `/var/log/supervisor/`.
 
-
 ## Configuring your webserver
 
 Any web server capable of proxy passing should be able to sit in front of Gunicorn. Consult their documentation armed with your `--bind=` address and you should be able to find how to do it relatively easy.
 
-
 ## 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:
 
 `supervisorctl restart myauth-gunicorn`, or the service name you chose for it.

docs/installation/index.md

@@ -1,10 +1,16 @@
 # Installation
 
+This chapter contains the main installation guides for **Alliance Auth**.
+
+In addition to main guide for installation Alliance Auth you also find guides for configuring web servers (Apache, NGINX) and the recommended WSGI server (Gunicorn).
+
 ```eval_rst
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
-
-    auth/index
-    services/index
 
+    allianceauth
+    nginx
+    apache
+    gunicorn
+    upgradev1
 ```

docs/installation/services/index.md

@@ -1,18 +0,0 @@
-# Services
-
-```eval_rst
-.. toctree::
-
-    permissions
-    discord
-    discourse
-    mumble
-    openfire
-    phpbb3
-    smf
-    teamspeak3
-    xenforo
-    jacknife
-    pathfinder
-
-```

docs/installation/upgradev1.md

@@ -1,4 +1,4 @@
-# Upgrading from v1.15
+# Upgrading from AA v1.15
 
 It's possible to preserve a v1 install's database and migrate it to v2. This will retain all service accounts, user accounts with their main character, but will purge API keys and alts.
 
@@ -44,19 +44,21 @@ Because character ownership is tracked separately of main character it is not po
 
 ### Members and Blues
 
-The new [state system](../../features/states.md) allows configuring dynamic membership states through the admin page. Unfortunately if you make a change after migrating it will immediately assess user states and see that no one should be a member. You can add additional settings to your auth project's settings file to generate the member and blue states as you have them defined in v1:
+The new [state system](../../features/core/states.md) allows configuring dynamic membership states through the admin page. Unfortunately if you make a change after migrating it will immediately assess user states and see that no one should be a member. You can add additional settings to your auth project's settings file to generate the member and blue states as you have them defined in v1:
- - `ALLIANCE_IDS = []` a list of member alliance IDs
+
- - `CORP_IDS = []` a list of member corporation IDs
+- `ALLIANCE_IDS = []` a list of member alliance IDs
- - `BLUE_ALLIANCE_IDS = []` a list of blue alliance IDs
+- `CORP_IDS = []` a list of member corporation IDs
- - `BLUE_CORP_IDS = []` a list of blue corporation IDs
+- `BLUE_ALLIANCE_IDS = []` a list of blue alliance IDs
+- `BLUE_CORP_IDS = []` a list of blue corporation IDs
 
 Put comma-separated IDs into the brackets and the migration will create states with the members and blues you had before. This will prevent unexpected state purging when you edit states via the admin site.
 
 ### Default Groups
 
 If you used member/blue group names other than the standard "Member" and "Blue" you can enter settings to have the member/blue states created through this migration take these names.
- - `DEFAULT_AUTH_GROUP = ""` the desired name of the "Member" state
+
- - `DEFAULT_BLUE_GROUP = ""` the desired name of the "Blue" state
+- `DEFAULT_AUTH_GROUP = ""` the desired name of the "Member" state
+- `DEFAULT_BLUE_GROUP = ""` the desired name of the "Blue" state
 
 Any permissions assigned to these groups will be copied to the state replacing them. Because these groups are no longer managed they pose a security risk and so are deleted at the end of the migration automatically.
 

docs/maintenance/apps.md

@@ -0,0 +1,10 @@
+# Adding and Removing Apps
+
+Your auth project is just a regular Django project - you can add in [other Django apps](https://djangopackages.org/) as desired. Most come with dedicated setup guides, but here is the general procedure:
+
+1. add `'appname',` to your `INSTALLED_APPS` setting in `local.py`
+2. run `python manage.py migrate`
+3. run `python manage.py collectstatic`
+4. restart AA with `supervisorctl restart myauth:`
+
+If you ever want to remove an app, you should first clear it from the database to avoid dangling foreign keys: `python manage.py migrate appname zero`. Then you can remove it from your auth project's `INSTALLED_APPS` list.

docs/maintenance/customizing.md

@@ -0,0 +1,64 @@
+# Customizing
+
+It is possible to customize your **Alliance Auth** instance.
+
+```eval_rst
+.. warning::
+   Keep in mind that you may need to update some of your customizations manually after new release (e.g. when replacing AA templates).
+```
+
+## Site name
+
+You can replace the default name shown on the web site with your own, e.g. the name of your Alliance.
+
+Just update `SITE_NAME` in your `local.py` settings file accordingly, e.g.:
+
+```python
+SITE_NAME = 'Awesome Alliance'
+```
+
+## Custom Static and Templates
+
+Within your auth project exists two folders named `static` and `templates`. These are used by Django for rendering web pages. Static refers to content Django does not need to parse before displaying, such as CSS styling or images. When running via a WSGI worker such as Gunicorn static files are copied to a location for the web server to read from. Templates are always read from the template folders, rendered with additional context from a view function, and then displayed to the user.
+
+You can add extra static or templates by putting files in these folders. Note that changes to static requires running the `python manage.py collectstatic` command to copy to the web server directory.
+
+It is possible to overload static and templates shipped with Django or Alliance Auth by including a file with the exact path of the one you wish to overload. For instance if you wish to add extra links to the menu bar by editing the template, you would make a copy of the `allianceauth/templates/allianceauth/base.html` file to `myauth/templates/allinceauth/base.html` and edit it there. Notice the paths are identical after the `templates/` directory - this is critical for it to be recognized. Your custom template would be used instead of the one included with Alliance Auth when Django renders the web page. Similar idea for static: put CSS or images at an identical path after the `static/` directory and they will be copied to the web server directory instead of the ones included.
+
+## Custom URLs and Views
+
+It is possible to add or override URLs with your auth project's URL config file. Upon install it is of the form:
+
+```python
+import allianceauth.urls
+
+urlpatterns = [
+    url(r'', include(allianceauth.urls)),
+]
+```
+
+This means every request gets passed to the Alliance Auth URL config to be interpreted.
+
+If you wanted to add a URL pointing to a custom view, it can be added anywhere in the list if not already used by Alliance Auth:
+
+```python
+import allianceauth.urls
+import myauth.views
+
+urlpatterns = [
+    url(r'', include(allianceauth.urls)),
+    url(r'myview/$', myauth.views.myview, name='myview'),
+]
+```
+
+Additionally you can override URLs used by Alliance Auth here:
+
+```python
+import allianceauth.urls
+import myauth.views
+
+urlpatterns = [
+    url(r'account/login/$', myauth.views.login, name='auth_login_user'),
+    url(r'', include(allianceauth.urls)),
+]
+```

docs/maintenance/index.md

@@ -1,9 +1,13 @@
-# Maintenance
+# Maintenance & Customizing
+
+In the maintenance chapter you find details about where important log files are found, how you can customize your AA installation and how to solve common issues.
 
 ```eval_rst
 .. toctree::
     :maxdepth: 1
 
+    apps
+    customizing
     project
     troubleshooting
 

docs/maintenance/project.md

@@ -1,28 +1,28 @@
-# Your Auth Project
+# Folder structure
-
-## Overview
 
 When installing Alliance Auth you are instructed to run the `allianceauth start` command which generates a folder containing your auth project. This auth project is based off Alliance Auth but can be customized how you wish.
 
-### The myauth Folder
+## The myauth folder
 
 The first folder created is the root directory of your auth project. This folder contains:
- - the `manage.py` management script used to interact with Django
- - a preconfigured `supervisor.conf` Supervisor config for running Celery (and optionally Gunicorn) automatically
- - a `log` folder which contains log files generated by Alliance Auth
 
-### The myauth Subfolder
+- the `manage.py` management script used to interact with Django
+- a preconfigured `supervisor.conf` Supervisor config for running Celery (and optionally Gunicorn) automatically
+- a `log` folder which contains log files generated by Alliance Auth
+
+## The myauth subfolder
 
 Within your auth project root folder is another folder of the same name (a quirk of Django project structures). This folder contains:
- - a Celery app definition in `celery.py` for registering tasks with the background workers
+
- - a web server gateway interface script `wsgi.py` for processing web requests
+- a Celery app definition in `celery.py` for registering tasks with the background workers
- - the root URL config `urls.py` which Django uses to direct requests to the appropriate view
+- a web server gateway interface script `wsgi.py` for processing web requests
+- the root URL config `urls.py` which Django uses to direct requests to the appropriate view
 
 There are also two subfolders for `static` and `templates` which allow adding new content and overriding default content shipped with Alliance Auth or Django.
 
 And finally the settings folder.
 
-### Settings Files
+## Settings Files
 
 With the settings folder lives two settings files: `base.py` and `local.py`
 
@@ -34,64 +34,9 @@ The local settings file is referred to as "your auth project's settings file" an
 
 Your auth project comes with four log file definitions by default. These are created in the `myauth/log/` folder at runtime.
 
- - `allianceauth.log` contains all `INFO` level and above logging messages from Alliance Auth. This is useful for tracking who is making changes to the site, what is happening to users, and debugging any errors that may occur.
+- `allianceauth.log` contains all `INFO` level and above logging messages from Alliance Auth. This is useful for tracking who is making changes to the site, what is happening to users, and debugging any errors that may occur.
- - `worker.log` contains logging messages from the Celery background task workers. This is useful for monitoring background processes such as group syncing to services.
+- `worker.log` contains logging messages from the Celery background task workers. This is useful for monitoring background processes such as group syncing to services.
- - `beat.log` contains logging messages from the background task scheduler. This is of limited use unless the scheduler isn't starting.
+- `beat.log` contains logging messages from the background task scheduler. This is of limited use unless the scheduler isn't starting.
- - `gunicorn.log` contains logging messages from Gunicorn workers. This contains all web-sourced messages found in `allianceauth.log` as well as runtime errors from the workers themselves.
+- `gunicorn.log` contains logging messages from Gunicorn workers. This contains all web-sourced messages found in `allianceauth.log` as well as runtime errors from the workers themselves.
 
 When asking for assistance with your auth project be sure to first read the logs, and share any relevant entries.
-
-## Custom Static and Templates
-
-Within your auth project exists two folders named `static` and `templates`. These are used by Django for rendering web pages. Static refers to content Django does not need to parse before displaying, such as CSS styling or images. When running via a WSGI worker such as Gunicorn static files are copied to a location for the web server to read from. Templates are always read from the template folders, rendered with additional context from a view function, and then displayed to the user.
-
-You can add extra static or templates by putting files in these folders. Note that changes to static requires running the `python manage.py collectstatic` command to copy to the web server directory.
-
-It is possible to overload static and templates shipped with Django or Alliance Auth by including a file with the exact path of the one you wish to overload. For instance if you wish to add extra links to the menu bar by editing the template, you would make a copy of the `allianceauth/templates/allianceauth/base.html` file to `myauth/templates/allinceauth/base.html` and edit it there. Notice the paths are identical after the `templates/` directory - this is critical for it to be recognized. Your custom template would be used instead of the one included with Alliance Auth when Django renders the web page. Similar idea for static: put CSS or images at an identical path after the `static/` directory and they will be copied to the web server directory instead of the ones included.
-
-## Custom URLs and Views
-
-It is possible to add or override URLs with your auth project's URL config file. Upon install it is of the form:
-
-```
-import allianceauth.urls
-
-urlpatterns = [
-    url(r'', include(allianceauth.urls)),
-]
-```
-
-This means every request gets passed to the Alliance Auth URL config to be interpreted.
-
-If you wanted to add a URL pointing to a custom view, it can be added anywhere in the list if not already used by Alliance Auth:
-
-```
-import allianceauth.urls
-import myauth.views
-
-urlpatterns = [
-    url(r'', include(allianceauth.urls)),
-    url(r'myview/$', myauth.views.myview, name='myview'),
-]
-```
-
-Additionally you can override URLs used by Alliance Auth here:
-
-```
-import allianceauth.urls
-import myauth.views
-
-urlpatterns = [
-    url(r'account/login/$', myauth.views.login, name='auth_login_user'),
-    url(r'', include(allianceauth.urls)),
-]
-```
-
-## Adding and Removing Apps
-
-Your auth project is just a regular Django project - you can add in [other Django apps](https://djangopackages.org/) as desired. Most come with dedicated setup guides, but in general:
- - add `'appname',` to your `INSTALLED_APPS` setting
- - run `python manage.py migrate`
- - run `python manage.py collectstatic`
-
-If you ever want to remove an app, you should first clear it from the database to avoid dangling foreign keys: `python manage.py migrate appname zero`. Then you can remove it from your auth project's `INSTALLED_APPS` list.

docs/maintenance/troubleshooting.md

@@ -1,13 +1,5 @@
 # Troubleshooting
 
-## Something broken? Stuck on an issue? Can't get it set up?
-
-Start by checking the [issues](https://gitlab.com/allianceauth/allianceauth/issues?scope=all&utf8=%E2%9C%93&state=all&search=my+issue) - especially closed ones.
-
-No answer?
- - open an [issue](https://gitlab.com/allianceauth/allianceauth/issues)
- - harass us on [gitter](https://gitter.im/R4stl1n/allianceauth)
-
 ## Logging
 
 In its default configuration your auth project logs INFO and above messages to myauth/log/allianceauth.log. If you're encountering issues it's a good idea to view DEBUG messages as these greatly assist the troubleshooting process. These are printed to the console with manually starting the webserver via `python manage.py runserver`.
@@ -32,8 +24,10 @@ Make sure the background processes are running: `supervisorctl status myauth:`.
 
 Stop celery workers with `supervisorctl stop myauth:worker` then clear the queue:
 
+```bash
     redis-cli FLUSHALL
     celery -A myauth worker --purge
+```
 
 Press Control+C once.
 
@@ -50,3 +44,15 @@ This is likely due to a permissions mismatch. Check the setup guide for your web
 ### Unable to execute 'gunicorn myauth.wsgi' or ImportError: No module named 'myauth.wsgi'
 
 Gunicorn needs to have context for its running location, `/home/alllianceserver/myauth/gunicorn myauth.wsgi` will not work, instead `cd /home/alllianceserver/myauth` then `gunicorn myauth.wsgi` is needed to boot Gunicorn. This is handled in the Supervisor config, but this may be encountered running Gunicorn manually for testing.
+
+### Specified key was too long error
+
+Migrations may about with the following error message:
+
+```bash
+Specified key was too long; max key length is 767 bytes
+```
+
+This error will occur if one is trying to use Maria DB prior to 10.2.x, which is not compatible with Alliance Auth.
+
+Install a never Maria DB version to fix this issue another DBMS supported by Django 2.2.

docs/support/index.md

@@ -0,0 +1,11 @@
+# Support
+
+If you encounter any AA related issues during installation or otherwise please first check the following resources:
+
+- See the section on [troubleshooting](/maintenance/troubleshooting.md) your AA instance, e.g. the list of common problems
+- Search the AA [issue list](https://gitlab.com/allianceauth/allianceauth/issues?scope=all&utf8=%E2%9C%93&state=all&search=my+issue) (especially the closed ones)
+
+No solution?
+
+- Open an [issue](https://gitlab.com/allianceauth/allianceauth/issues)
+- Ask for help on our [Discord](https://discord.gg/fjnHAmk)