Alliance Auth Documentation
Release
R4stl1n
Feb 24, 2018
Contents
1
Installing
3
2
Using
5
3
Troubleshooting
3.1 Features . . . . . . . . . . . . .
3.1.1
The State System . . .
3.1.2
Groups . . . . . . . .
3.1.3
Group Management . .
3.1.4
Auto Groups . . . . .
3.1.5
HR Applications . . .
3.1.6
Corp Stats . . . . . . .
3.1.7
Permissions Auditing .
3.1.8
Services Name Formats
3.1.9
Fleetup . . . . . . . .
3.1.10 Fleet Activity Tracking
3.1.11 Optimer . . . . . . . .
3.1.12 SRP . . . . . . . . . .
3.1.13 Timerboard . . . . . .
3.2 Installation . . . . . . . . . . .
3.2.1
Auth . . . . . . . . . .
3.2.2
Services . . . . . . . .
3.3 Maintenance . . . . . . . . . .
3.3.1
Changelog . . . . . . .
3.3.2
Troubleshooting . . . .
3.4 Development . . . . . . . . . .
3.4.1
Documentation . . . .
3.4.2
Integrating Services . .
3.4.3
Menu Hooks . . . . .
3.4.4
URL Hooks . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
7
7
7
8
10
12
14
16
22
24
25
26
26
26
26
27
27
37
60
60
68
69
69
70
76
77
i
ii
Alliance Auth Documentation, Release
Alliance service auth to help large scale alliances manage services. Built for “The 99 Percent” open for anyone to use
Contents
1
Alliance Auth Documentation, Release
2
Contents
CHAPTER 1
Installing
Setup Guide
3
Alliance Auth Documentation, Release
4
Chapter 1. Installing
CHAPTER 2
Using
Learn about individual features.
5
Alliance Auth Documentation, Release
6
Chapter 2. Using
CHAPTER 3
Troubleshooting
Read the list of common problems.
Features
The State System
Overview
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.
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.
7
Alliance Auth Documentation, Release
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 gree 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.
States are automatically assigned when a user registers to the site, their main character changes, they are activated or
deactivated, or states are edited. Note that editing states triggers lots of state checks so it can be a very slow process.
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.
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.
8
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
User Organised 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:
Here you have several options:
3.1. Features
9
Alliance Auth Documentation, Release
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
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.
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.
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).
10
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
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 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 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.
3.1. Features
11
Alliance Auth Documentation, Release
Auto Groups
Note: New in 2.0
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 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:
12
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
Warning: After creating a group you wont be able to change the Corp and Alliance group prefixes, name source
and the replace spaces settings. Make sure you configure these the way you want before creating the config. If you
need to change these you will have to create a new autogroup config.
3.1. Features
13
Alliance Auth Documentation, Release
• States selects which states will be added to automatic corp/alliance groups
• 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 name source sets the source of the corp/alliance name used in creating the group name. Currently
the options are Full name and Ticker.
• Replace spaces allows you to replace spaces in the autogroup name with the value in the Replace spaces with
field. This can be blank.
HR Applications
Installation
Add
allianceauth.hrapplications
myauth/settings/local.py:
to
your
INSTALLED_APPS
setting.
In
INSTALLED_APPS += ['allianceauth.hrapplications']
Run migrations to complete installation.
Management
Creating Forms
The most common task is creating ApplicationForm models for corps. Only when such models exist will a corp be
listed as a choice for applicants. This occurs in the django admin site, so only staff have access.
The first step is to create questions. This is achieved by creating ApplicationQuestion models, one for each question.
Titles are not unique.
Next step is to create the actual ApplicationForm model. It requires an existing EveCorporationInfo model to which
it will belong. It also requires the selection of questions. ApplicationForm models are unique per corp: only one may
exist for any given corp concurrently.
You can adjust these questions at any time. This is the preferred method of modifying the form: deleting and recreating
will cascade the deletion to all received applications from this form which is usually not intended.
Once completed the corp will be available to receive applications.
Reviewing Applications
Superusers can see all applications, while normal members with the required permission can view only those to their
corp.
Selecting an application from the management screen will provide all the answers to the questions in the form at the
time the user applied.
When a reviewer assigns themselves an application, they mark it as in progress. This notifies the applicant and
permanently attached the reviewer to the application.
Only the assigned reviewer can approve/reject/delete the application if they possess the appropriate permission.
14
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
Any reviewer who can see the application can view the applicant’s APIs if they possess the appropriate permission.
Permissions
The following permissions have an effect on the website above and beyond their usual admin site functions.
Permission
auth.human_resources
hrapplications.approve_application
hrapplications.delete_application
hrapplications.reject_applications
hrapplications.view_apis
hrapplications.add_applicationcomment
Admin Site
None
None
Can delete model
None
None
Can create model
Auth Site
Can view applications and mark in progress
Can approve applications
Can delete applications
Can reject applications
Can view applicant API keys, and audit in Jacknife
Can comment on applications
Best
practice
is
to
bundle
the
auth.human_resources
permission
alongside
hrapplications.approve_application and hrapplications.reject_application
missions, as in isolation these don’t make much sense.
the
per-
Models
ApplicationQuestion
This is the model representation of a question. It contains a title, and a field for optional “helper” text. It is referenced
by ApplicationForm models but acts independently. Modifying the question after it has been created will not void
responses, so it’s not advisable to edit the title or the answers may not make sense to reviewers.
ApplicationForm
This is the template for an application. It points at a corp, with only one form allowed per corp. It also points at
ApplicationQuestion models. When a user creates an application, they will be prompted with each question the form
includes at the given time. Modifying questions in a form after it has been created will not be reflected in existing
applications, so it’s perfectly fine to adjust them as you see fit. Changing corps however is not advisable, as existing
applications will point at the wrong corp after they’ve been submitted, confusing reviewers.
Application
This is the model representation of a completed application. It references an ApplicationForm from which it was
spawned which is where the corp specificity comes from. It points at a user, contains info regarding its reviewer,
and has a status. Shortcut properties also provide the applicant’s main character, the applicant’s APIs, and a string
representation of the reviewer (for cases when the reviewer doesn’t have a main character or the model gets deleted).
ApplicationResponse
This is an answer to a question. It points at the Application to which it belongs, to the ApplicationQuestion which it is
answering, and contains the answer text. Modifying any of these fields in dangerous.
3.1. Features
15
Alliance Auth Documentation, Release
ApplicationComment
This is a reviewer’s comment on an application. Points at the application, points to the user, and contains the comment
text. Modifying any of these fields is dangerous.
Troubleshooting
No corps accepting applications
Ensure there are ApplicationForm models in the admin site. Ensure the user does not already have an application to
these corps. If the users wishes to re-apply they must first delete their completed application
Reviewer unable to complete application
Reviewers require a permission for each of the three possible outcomes of an application, Approve Reject or Delete.
Any user with the human resources permission can mark an application as in-progress, but if they lack these permissions then the application will get stuck. Either grant the user the required permissions or change the assigned reviewer in the admin site. Best practice is to bundle the auth.human_resources permission alongside
the hrapplications.approve_application and hrapplications.reject_application permissions, as in isolation these don’t serve much purpose.
Corp Stats
This module is used to check the registration status of corp members and to determine character relationships, being
mains or alts.
Installation
Add allianceauth.corputils to your INSTALLED_APPS setting and run migrations.
myauth/settings/local.py:
In
INSTALLED_APPS += ['allianceauth.corputils']
Run migrations to complete installation.
Creating a Corp Stats
Upon initial install, nothing will be visible. For every corp, a model will have to be created before data can be viewed.
If you are a superuser, the add button will be immediate visible to you. If not, your user account requires the
add_corpstats permission.
16
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
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 corp you want data for.
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.
3.1. Features
17
Alliance Auth Documentation, Release
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.
Corp Stats View
Navigation Bar
This bar contains a dropdown menu of all available corps. If the user has the add_corpstats permission, a button
to add a Corp Stats will be shown.
On the right of this bar is a search field. Press enter to search. It checks all characters in all Corp Stats you have view
permission to and returns search results.
Last Update
An update can be performed immediately by pressing the update button. Anyone who can view the Corp Stats can
update it.
18
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
Character Lists
Three views are available:
• main characters and their alts
• 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.
Main List
This list contains all main characters in registered in the selected corporation and their alts. Each character has a link
to zKillboard.
3.1. Features
19
Alliance Auth Documentation, Release
Member List
The list contains all characters in the corp. Red backgrounds means they are not registered in auth. A link to zKillboard
is present for all characters. If registered, the character will also have a main character, main corporation, and main
alliance field.
Unregistered List
This list contains all characters not registered on auth. Each character has a link to zKillboard.
20
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
Search View
This view is essentially the same as the Corp Stats page, but not specific to a single corp. 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:
Permission
corpstats.view_corp_corpstats
corpstats.view_alliance_corpstats
corpstats.view_state_corpstats
corpstats.add_corpstats
corpstats.change_corpstats
corpstats.remove_corpstats
Admin Site
None
None
None
Can create model
Can edit model
Can delete model
Auth Site
Can view corp stats of their corporation.
Can view corp stats of members of their alliance.
Can view corp stats of members of their auth state.
Can add new corpstats using an SSO token.
None.
None.
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 corp’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'] = {
'task': 'allianceauth.corputils.tasks.update_all_corpstats',
'schedule': crontab(minute=0, hour="*/6"),
},
Adjust the crontab as desired.
Troubleshooting
3.1. Features
21
Alliance Auth Documentation, Release
Failure to create Corp Stats
Unrecognized corporation. Please ensure it is a member of the alliance or a blue.
Corp Stats can only be created for corporations who have a model in the database. These only exist for tenant corps,
corps of tenant alliances, blue corps, and members of blue alliances.
Selected corp already has a statistics module.
Only one Corp Stats may exist at a time for a given corporation.
Failed to gather corporation statistics with selected token.
During initial population, the EVE Swagger Interface did not return any member data. This aborts the creation process.
Please wait for the API to start working before attempting to create again.
Failure to update Corp Stats
Any of the following errors will result in a notification to the owning user, and deletion of the Corp Stats model.
Your token has expired or is no longer valid. Please add a new one to create a new CorpStats.
This occurs when the SSO token is invalid, which can occur when deleted by the user, the character is transferred
between accounts, or the API is having a bad day.
CorpStats for (corp name) cannot update with your ESI token as you have left corp.
The SSO token’s character is no longer in the corp which the Corp Stats is for, and therefore membership data cannot
be retrieved.
HTTPForbidden
The SSO token lacks the required scopes to update membership data.
Permissions Auditing
Note: New in 1.15
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
Add
allianceauth.permissions_tool
myauth/settings/local.py:
to
your
INSTALLED_APPS
setting.
In
INSTALLED_APPS += ['allianceauth.permissions_tool']
Usage
Access
In order to grant users access to the permissions auditing tool they will need to be granted the
permissions_tool.audit_permissions permission or be a superuser.
22
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
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.
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.
Users is the number of users explicitly granted this permission on their account.
Groups is the number of groups with this permission assigned.
Groups Users is the total number of users in all of the groups with this permission assigned.
Clicking on the Code Name link will take you to the Permissions Audit Page
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.
3.1. Features
23
Alliance Auth Documentation, Release
Please note that users may appear multiple times if this permission is granted via multiple sources.
Services Name Formats
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
Currently the following services support custom name formats:
Service
Discord
Discourse
IPS4
Mumble
Openfire
phpBB3
SeAT
SMF
Teamspeak 3
Xenforo
Used with
Nickname
Username
Username
Username
Username
Username
Username
Username
Nickname
Username
Default Formatter
{character_name}
{character_name}
{character_name}
[{corp_ticker}]{character_name}
{character_name}
{character_name}
{character_name}
{character_name}
[{corp_ticker}]{character_name}
{character_name}
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.
Available format data
The following fields are available from a users account and main character:
24
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
• username - Alliance Auth username
• character_id
• character_name
• corp_id
• corp_name
• corp_ticker
• alliance_id
• alliance_name
• alliance_ticker
Building a formatter string
The name formatter uses the advanced string formatting specified by PEP-3101. Anything supported by this specification is supported in a name formatter.
A more digestable documentation of string formatting in Python is available on the PyFormat website.
Some examples of strings you could use:
Formatter
{alliance_ticker} -{character_name}
[{corp_ticker}] {character_name}
{{{corp_name}}}{character_name}
Result
MYALLI -My Character
[CORP] My Character
{My Corp}My Character
Important: For most services, name formats only take effect when a user creates an account. This means if you
create or update a name formatter it wont retroactively alter the format of users names. There are some exceptions to
this where the service updates nicknames on a periodic basis. Check the service’s documentation to see which of these
apply.
Important: You must only create one formatter per service per state. E.g. don’t create two formatters for Mumble
for the Member state. In this case one of the formatters will be used and it may not be the formatter you are expecting.
Fleetup
Installation
Add allianceauth.fleetup to your auth project’s INSTALLED_APPS setting.
INSTALLED_APPS += ['allianceauth.fleetup']
Additional settings are required. Append the following settings to the end of your auth project’s settings file and fill
them out.
FLEETUP_APP_KEY = '' # The app key from http://fleet-up.com/Api/MyApps
FLEETUP_USER_ID = '' # The user id from http://fleet-up.com/Api/MyKeys
FLEETUP_API_ID = '' # The API id from http://fleet-up.com/Api/MyKeys
FLEETUP_GROUP_ID = '' # The id of the group you want to pull data from, see http://
˓→fleet-up.com/Api/Endpoints#groups_mygroupmemberships
3.1. Features
25
Alliance Auth Documentation, Release
Once filled out restart gunicorn and celery.
Permissions
The Fleetup module is only visible to users with the auth | user | view_fleeup permission.
Fleet Activity Tracking
Installation
Add allianceauth.fleetactivitytracking
myauth/settings/local.py:
to
your
INSTALLED_APPS
setting.
In
INSTALLED_APPS += ['allianceauth.fleetactivitytracking']
Run migrations to complete installation.
Optimer
Installation
Add allianceauth.optimer to your INSTALLED_APPS setting. In myauth/settings/local.py:
INSTALLED_APPS += ['allianceauth.optimer']
Run migrations to complete installation.
SRP
Installation
Add allianceauth.srp to your INSTALLED_APPS setting. In myauth/settings/local.py:
INSTALLED_APPS += ['allianceauth.srp']
Run migrations to complete installation.
Timerboard
Installation
Add allianceauth.timerboard to your INSTALLED_APPS setting. In myauth/settings/local.py:
INSTALLED_APPS += ['allianceauth.timerboard']
Run migrations to complete installation.
26
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
Installation
Auth
Alliance Auth Installation
Tip: If you are uncomfortable with linux permissions follow the steps below as the root user. Some commands do
not behave the same when run with sudo.
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.
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
3.2. Installation
27
Alliance Auth Documentation, Release
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
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 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
/home/allianceserver/venv/auth/)
and
put
it
somewhere
convenient
(e.g.
python3 -m venv /home/allianceserver/venv/auth/
28
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
Warning: The python3 command may not be available on all installations. Try a specific version such as
python3.6 if this is the case.
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.
Activate the virtualenv using source /home/allianceserver/venv/auth/bin/activate. Note the
/bin/activate on the end of the path.
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. 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
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
3.2. Installation
29
Alliance Auth Documentation, Release
Gunicorn
To run the auth website a WSGI Server is required. Gunicorn is highly recommended for its ease of configuring. It
can be manually run with gunicorn myauth.wsgi or automatically run using supervisor.
The default configuration is good enough for most installations. Additional information is available in the gunicorn
doc.
Supervisor
Supervisor 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.
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 or Apache 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.
30
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
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 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.
Gunicorn
Gunicorn is a Python WSGI HTTP Server for UNIX. The Gunicorn server is light on server resources, and fairly
speedy.
If you find Apache’s mod_wsgi to be a headache or want to use NGINX (or some other webserver), then Gunicorn
could be for you. There are a number of other WSGI server options out there and this documentation should be enough
for you to piece together how to get them working with your environment.
Check out the full Gunicorn docs.
Setting up Gunicorn
Note: If you’re using a virtual environment (and I would encourage you to do so when hosting Alliance Auth),
activate it now. source /path/to/venv/bin/activate.
Install Gunicorn using pip, pip install gunicorn.
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 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.
3.2. Installation
31
Alliance Auth Documentation, Release
Sample Supervisor config
You’ll want to edit /etc/supervisor/conf.d/myauth_gunicorn.conf (or whatever you want to call the
config file)
[program:myauth-gunicorn]
user = allianceserver
directory=/home/allianceserver/myauth/
command=gunicorn myauth.wsgi --workers=3 --timeout 120
autostart=true
autorestart=true
stopsignal=INT
• [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
See the Commonly Used Arguments or Full list of settings 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.
For a TCP address add --bind=127.0.0.1:8001 (or to the address/port you wish to use, but I would strongly
advise against binding it to an external address).
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 alliance_auth.wsgi
32
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
Starting via Supervisor
Once you have your configuration all sorted, you will need to reload your supervisor config sudo service
supervisor reload and then you can start the Gunicorn server via sudo 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
NGINX
To your server config add:
location / {
proxy_pass
proxy_read_timeout
proxy_redirect
proxy_set_header
proxy_set_header
proxy_set_header
proxy_set_header
}
http://127.0.0.1:8000;
90;
http://127.0.0.1:8000/ http://$host/;
Host $host;
X-Forwarded-For $proxy_add_x_forwarded_for;
X-Real-IP $remote_addr;
X-Forwarded-Proto $scheme;
Set proxy_pass and proxy_redirect to the address you set under --bind=. Set the second part of
proxy_redirect to the URL you’re hosting services on. Tell NGINX to reload your config, job done. Enjoy
your lower memory usage and better performance!
If PHP is stopping you moving to NGINX, check out php-fpm as a way to run your PHP applications.
Apache
If you were using mod_wsgi before, make a backup of your old config first and then strip out all of the mod_wsgi
config from your Apache VirtualHost first config.
Your config will need something along these lines:
ProxyPreserveHost On
<Location />
SSLRequireSSL
ProxyPass http://127.0.0.1:8000/
ProxyPassReverse http://127.0.0.1:8000/
RequestHeader set X-FORWARDED-PROTOCOL ssl
RequestHeader set X-FORWARDED-SSL on
</Location>
Set ProxyPass and ProxyPassReverse addresses to your --bind= address set earlier.
You will need to enable some Apache mods. sudo a2enmod http_proxy should take care of the dependencies.
Restart Apache and you should be done.
3.2. Installation
33
Alliance Auth Documentation, Release
Other web servers
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:
sudo supervisorctl restart myauth-gunicorn, or the service name you chose for it.
NGINX
Overivew
Nginx (engine x) is a HTTP server known for its high performance, stability, simple configuration, and low resource
consumption. Unlike traditional servers (i.e. Apache), Nginx doesn’t rely on threads to serve requests, rather using an
asynchronous event driven approach which permits predictable resource usage and performance under load.
If you’re trying to cram Alliance Auth into a very small VPS of say, 1-2GB or less, then Nginx will be considerably
friendlier to your resources compared to Apache.
You can read more about NGINX on the NGINX wiki.
Coming from Apache
If you’re converting from Apache, here are some things to consider.
Nginx is lightweight for a reason. It doesn’t try to do everything internally and instead concentrates on just being a
good HTTP server. This means that, unlike Apache, it wont automatically run PHP scripts via mod_php and doesn’t
have an internal WSGI server like mod_wsgi. That doesn’t mean that it can’t, just that it relies on external processes
to run these instead. This might be good or bad depending on your outlook. It’s good because it allows you to segment
your applications, restarting Alliance Auth wont impact your PHP applications. On the other hand it means more
config and more management of services. For some people it will be worth it, for others losing the centralised nature
of Apache may not be worth it.
Apache
mod_php
mod_wsgi
Nginx Replacement
php5-fpm or php7-fpm (PHP FastCGI)
Gunicorn or other external WSGI server
Your .htaccess files wont work. Nginx has a separate way of managing access to folders via the server config. Everything you can do with htaccess files you can do with Nginx config. Read more on the Nginx wiki
Setting up Nginx
Install Nginx via your preferred package manager or other method. If you need help just search, there are plenty of
guides on installing Nginx out there.
You will need to have Gunicorn or some other WSGI server setup for hosting Alliance Auth.
Create a config file in /etc/nginx/sites-available call it alliance-auth.conf or whatever your preferred name is and copy the basic config in. Make whatever changes you feel are necessary.
34
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
Create a symbolic link to enable the site sudo ln -s /etc/nginx/sites-available/alliance-auth.conf
/etc/nginx/sites-enabled/ and then reload Nginx for the config to take effect, sudo service nginx
reload for Ubuntu.
Basic config
server {
listen 80;
server_name example.com;
location = /favicon.ico { access_log off; log_not_found off; }
location /static/ {
alias /var/www/myauth/static;
autoindex off;
}
# Gunicorn config goes below
location / {
include proxy_params;
proxy_pass http://127.0.0.1:8000;
}
}
Adding TLS/SSL
With Let’s Encrypt offering free SSL certificates, there’s no good reason to not run HTTPS anymore.
Your config will need a few additions once you’ve got your certificate.
listen 443 ssl http2; # Replace listen 80; with this
ssl_certificate
ssl_certificate_key
/path/to/your/cert.crt;
/path/to/your/cert.key;
ssl on;
ssl_session_cache builtin:1000 shared:SSL:10m;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers EECDH+ECDSA+AESGCM:EECDH+aRSA+AESGCM:EECDH+ECDSA+SHA384:
˓→EECDH+ECDSA+SHA256:EECDH+aRSA+SHA384:EECDH+aRSA+SHA256:EECDH+aRSA+RC4:EECDH:
˓→EDH+aRSA:RC4:!aNULL:!eNULL:!LOW:!3DES:!MD5:!EXP:!PSK:!SRP:!DSS;
ssl_prefer_server_ciphers on;
If you want to redirect all your non-SSL visitors to your secure site, below your main configs server block, add the
following:
server {
listen 80;
server_name example.com;
# Redirect all HTTP requests to HTTPS with a 301 Moved Permanently response.
return 301 https://$host$request_uri;
}
3.2. Installation
35
Alliance Auth Documentation, Release
If you have trouble with the ssl_ciphers listed here or some other part of the SSL config, try getting the values
from Mozilla’s SSL Config Generator.
Apache Setup
Overview
Alliance Auth gets served using a Web Server Gateway Interface (WSGI) script. This script passes web requests to
Alliance Auth which generates the content to be displayed and returns it. This means very little has to be configured
in Apache to host Alliance Auth.
If you’re using a small VPS to host services with very limited memory, consider using NGINX.
Installation
Ubuntu:
apt-get install apache2
CentOS:
yum install httpd
systemctl enable httpd
systemctl start httpd
Configuration
Apache serves sites through defined virtual hosts. These are located in /etc/apache2/sites-available/ on
Ubuntu and /etc/httpd/conf.d/httpd.conf on CentOS.
A virtual host for auth need only proxy requests to your WSGI server (gunicorn if you followed the install guide) and
serve static files. Examples can be found below. Create your config in its own file eg myauth.conf.
Ubuntu
To proxy and modify headers a few mods need to be enabled.
a2enmod proxy
a2enmod proxy_http
a2enmod headers
Create a new config file for auth eg /etc/apache2/sites-available/myauth.conf and fill out the virtual
host configuration. To enable your config use a2ensite myauth.conf and then reload apache with service
apache2 reload.
CentOS
Place your virtual host configuration in the appropriate section within /etc/httpd/conf.d/httpd.conf and
restart the httpd service with systemctl restart httpd.
36
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
Sample Config File
<VirtualHost *:80>
ServerName auth.example.com
ProxyPassMatch ^/static !
ProxyPass / http://127.0.0.1:8000/
ProxyPassReverse / http://127.0.0.1:8000/
ProxyPreserveHost On
Alias "/static" "/var/www/myauth/static"
<Directory "/var/www/myauth/static">
Require all granted
</Directory>
</VirtualHost>
SSL
It’s 2018 - there’s no reason to run a site without SSL. The EFF provides free, renewable SSL certificates with an
automated installer. Visit their website for information.
After acquiring SSL the config file needs to be adjusted. Add the following lines inside the <VirtualHost> block:
RequestHeader set X-FORWARDED-PROTOCOL https
RequestHeader set X-FORWARDED-SSL On
Services
Service Permissions
Note: New in 1.15
In the past, access to services was dictated by a list of settings in settings.py, granting access to each particular
service for Members and/or Blues. This meant that granting access to a service was very broad and rigidly structured
around these two states.
Permissions based access
Instead of granting access to services by the previous rigid structure, access to services is now granted by the built in
Django permissions system. This means that service access can be more granular, allowing only certain groups, for
instance Corp CEOs, or even individual user access to each enabled service.
Important: If you grant access to an individual user, they will have access to that service regardless of whether or
not they are a member.
Each service has an access permission defined, named like Can access the <service name> service.
3.2. Installation
37
Alliance Auth Documentation, Release
To mimick the old behaviour of enabling services for all members, you would select the Member group from the
admin panel, add the required service permission to the group and save. Likewise for Blues, select the Blue group
and add the required permission.
A user can be granted the same permission from multiple sources. e.g. they may have it granted by several groups and
directly granted on their account as well. Auth will not remove their account until all instances of the permission for
that service have been revoked.
Removing access
Danger: Access removal is processed immediately after removing a permission from a user or group. If you
remove access from a large group, such as Member, it will immediately remove all users from that service.
When you remove a service permission from a user, a signal is triggered which will activate an immediate permission
check. For users this will trigger an access check for all services. For groups, due to the potential extra load, only the
services whose permissions have changed will be verified, and only the users in that group.
If a user no longer has permission to access the service when this permissions check is triggered, that service will be
immediately disabled for them.
Disabling user accounts
When you unset a user as active in the admin panel, all of that users service accounts will be immediately disabled
or removed. This is due to the built in behaviour of Djangos permissions system, which will return False for all
permissions if a users account is disabled, regardless of their actual permissions state.
Alliance Market
Dependencies
Alliance Market requires php installed in your web server. Apache has mod_php, NGINX requires php-fpm.
Prepare Your Settings
In your auth project’s settings file, do the following:
• Add 'allianceauth.services.modules.market', to your INSTALLED_APPS list
• Append the following to the bottom of the settings file
# Alliance Market
MARKET_URL = ''
DATABASES['market'] = {
'ENGINE': 'django.db.backends.mysql',
'NAME': 'alliance_market',
'USER': 'allianceserver-market',
'PASSWORD': 'password',
'HOST': '127.0.0.1',
'PORT': '3306',
}
38
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
Setup Alliance Market
Alliance Market needs a database. Create one in mysql. Default name is alliance_market:
mysql -u root -p
create database alliance_market;
grant all privileges on alliance_market . * to 'allianceserver'@'localhost';
exit;
To clone the repo, install packages:
sudo apt-get install mercurial meld
Change to the web folder:
cd /var/www
Now clone the repo
sudo hg clone https://bitbucket.org/krojew/evernus-alliance-market
Make cache and log directories
sudo
sudo
sudo
sudo
mkdir
mkdir
chmod
chmod
evernus-alliance-market/app/cache
evernus-alliance-market/app/logs
-R 777 evernus-alliance-market/app/cache
-R 777 evernus-alliance-market/app/logs
Change ownership to apache
sudo chown -R www-data:www-data evernus-alliance-market
Enter
cd evernus-alliance-market
Set environment variable
export SYMFONY_ENV=prod
Copy configuration
sudo cp app/config/parameters.yml.dist
app/config/parameters.yml
Edit, changing the following:
• database_name to alliance_market
• database_user to your MySQL user (usually allianceserver)
• database_password to your MySQL user password
• email settings, eg gmail
Edit app/config/config.yml and add the following:
services:
fos_user.doctrine_registry:
alias: doctrine
3.2. Installation
39
Alliance Auth Documentation, Release
Install composer as per these instructions.
Update dependencies.
sudo php composer.phar update --optimize-autoloader
Prepare the cache:
sudo php app/console cache:clear --env=prod --no-debug
Dump assets:
sudo php app/console assetic:dump --env=prod --no-debug
Create DB entries
sudo php app/console doctrine:schema:update --force
Install SDE:
sudo php app/console evernus:update:sde
Configure your web server to serve alliance market.
A minimal apache config might look like:
<VirtualHost *:80>
ServerName market.example.com
DocumentRoot /var/www/evernus-alliance-market/web
<Directory "/var/www/evernus-alliance-market/web/">
DirectoryIndex app.php
Require all granted
AllowOverride all
</Directory>
</VirtualHost>
A minimal nginx config might look like:
server {
listen 80;
server_name market.example.com;
root
/var/www/evernus-alliance-market/web;
index app.php;
access_log /var/logs/market.access.log;
location ~ \.php$ {
try_files $uri =404;
fastcgi_pass
unix:/tmp/php.socket;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
}
Once again, set cache permissions:
sudo chown -R www-data:www-data app/
Add a user account through auth, then make it a superuser:
40
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
sudo php app/console fos:user:promote your_username --super
Now edit your auth project’s settings file and fill in the web URL to your market as well as the database details.
Finally run migrations and restart gunicorn and celery.
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.
Setup
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:
# Discord Configuration
DISCORD_GUILD_ID = ''
DISCORD_CALLBACK_URL = ''
DISCORD_APP_ID = ''
DISCORD_APP_SECRET = ''
DISCORD_BOT_TOKEN = ''
DISCORD_SYNC_NAMES = False
Creating a Server
If you already have a Discord server, skip the creation step, but be sure to retrieve the server ID
Navigate to the Discord site 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.
Now retrieve the server ID from the URL of the page you’re on. The ID is the first of the very long numbers. For
instance my testing server’s url look like:
https://discordapp.com/channels/120631096835571712/120631096835571712
with a server ID of 120631096835571712
Update your auth project’s settings file, inputting the server ID as DISCORD_GUILD_ID
Registering an Application
Navigate to the Discord Developers site. Press the plus sign to create a new application.
3.2. Installation
41
Alliance Auth Documentation, Release
Give it a name and description relating to your auth site.
Add a redirect
https://example.com/discord/callback/, substituting your domain. Press Create Application.
to
Update your auth project’s settings file, inputting this redirect address as DISCORD_CALLBACK_URL
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 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 AllianceAuth 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.
To manage roles, this bot role must be at the top of the hierarchy. Edit your Discord server, roles, and click and drag
the role with the same name as your application to the top of the list. This role must stay at the top of the list for the bot
to work. Finally, the owner of the bot account must enable 2 Factor Authentication (this is required from discord for
kicking and modifying member roles). If you are unsure what 2FA is or how to set it up, refer to this support page. It
is also recommended to force 2fa on your server (this forces any admins or moderators to have 2fa enabled to perform
similar functions on discord).
Linking Accounts
Instead of the usual account creation procedure, for Discord to work we need to link accounts to AllianceAuth. 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
AllianceAuth 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,
DISCORD_SYNC_NAMES to True
set
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 chat and use comms. Add more
permissions to the roles as desired through the server management window.
42
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
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:
# Discourse Configuration
DISCOURSE_URL = ''
DISCOURSE_API_USERNAME = ''
DISCOURSE_API_KEY = ''
DISCOURSE_SSO_SECRET = ''
Install Docker
wget -qO- https://get.docker.io/ | sh
Get docker permissions
sudo usermod -aG docker allianceserver
Logout, then back in for changes to take effect.
Install Discourse
Download Discourse
sudo mkdir /var/discourse
sudo git clone https://github.com/discourse/discourse_docker.git /var/discourse
Configure
cd /var/discourse
sudo cp samples/standalone.yml containers/app.yml
sudo 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 127.0.0.1
• Everything with SMTP depends on your mail settings. Account created through auth do not require email
validation, so to ignore everything email (NOT RECOMMENDED), just change the SMTP address to something
random so it’ll install. Note that not setting up email means any password resets emails won’t be sent, and auth
cannot reset these. There are plenty of free email services online recommended by Discourse.
3.2. Installation
43
Alliance Auth Documentation, Release
To install behind apache, look for this secion:
...
## which TCP/IP ports should this container expose?
expose:
- "80:80"
# fwd host port 80
to container port 80 (http)
...
Change it to this:
...
## which TCP/IP ports should this container expose?
expose:
- "7890:80"
# fwd host port 7890
to container port 80 (http)
...
Or any other port will do, if taken. Remember this number.
Build and launch
sudo nano /etc/default/docker
Uncomment this line:
DOCKER_OPTS="--dns 8.8.8.8 --dns 8.8.4.4"
Restart docker:
sudo service docker restart
Now build:
sudo ./launcher bootstrap app
sudo ./launcher start app
Web Server Configuration
You will need to configure your web server to proxy requests to Discourse.
A minimal apache config might look like:
<VirtualHost *:80>
ServerName discourse.example.com
ProxyPass / http://0.0.0.0:7890/
ProxyPassReverse / http://0.0.0.0:7890/
</VirtualHost>
A minimal nginx config might look like:
server {
listen 80;
server_name discourse.example.com;
location / {
include proxy_params;
proxy_pass http://127.0.0.1:7890;
44
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
}
}
Configure API
Generate admin account
From the /var/discourse folder,
./launcher enter app
rake admin:create
Follow prompts, being sure to answer y when asked to allow admin privileges.
Create API key
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: 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_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
• 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.
Finally run migrations and restart gunicorn and celery.
Mumble
Prepare Your Settings
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:
# Mumble Configuration
MUMBLE_URL = ""
3.2. Installation
45
Alliance Auth Documentation, Release
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.
Dependencies
The mumble server package can be retrieved from a repository we need to add, mumble/release.
sudo apt-add-repository ppa:mumble/release
sudo apt-get update
Now two packages need to be installed:
sudo apt-get install python-software-properties mumble-server
Download the appropriate authenticator release from https://github.com/allianceauth/mumble-authenticator and install
the python dependencies for it:
pip install -r requirements.txt
Configuring Mumble
Mumble ships with a configuration file that needs customization. By default it’s located at /etc/mumble-server.ini.
Open it with your favourite text editor:
sudo nano /etc/mumble-server.ini
REQUIRED: To enable the ICE authenticator, edit the following:
• icesecretwrite=MY_CLEVER_PASSWORD, obviously choosing a secure password
By default mumble operates on sqlite which is fine, but slower than a dedicated MySQL server. To customize the
database, edit the following:
• uncomment the database line, and change it to database=alliance_mumble
• dbDriver=QMYSQL
• dbUsername=allianceserver or whatever you called the AllianceAuth MySQL user
• dbPassword= that user’s password
• dbPort=3306
• dbPrefix=murmur_
To name your root channel, uncomment and set registerName= to whatever cool name you want
Save and close the file (control + O, control + X).
To get mumble superuser account credentials, run the following:
sudo dpkg-reconfigure mumble-server
Set the password to something you’ll remember and write it down. This is needed to manage ACLs.
Now restart the server to see the changes reflected.
46
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
sudo service mumble-server restart
That’s it! Your server is ready to be connected to at example.com:64738
Configuring the Authenticator
The ICE authenticator lives in the mumble-authenticator repository, cd to the directory where you cloned it.
Make a copy of the default config:
cp authenticator.ini.example authenticator.ini
Edit authenticator.ini and change these values:
• [database]
– user = your allianceserver MySQL user
– password = your allianceserver MySQL user’s password
• [ice]
– secret = the icewritesecret password set earlier
Test your configuration by starting it: python authenticator.py
Running the Authenticator
The authenticator needs to be running 24/7 to validate users on Mumble. You should check the supervisor docs on
how to achieve this.
Note that groups will only be created on Mumble automatically when a user joins who is in the group.
Making and Managing Channels
ACL is really above the scope of this guide. Once AllianceAuth creates your groups, go ahead and follow one of the
wonderful web guides available on how to set up channel ACL properly.
Prepare Auth
In your project’s settings file, set MUMBLE_URL to the public address of your mumble server. Do not include any
leading http:// or mumble://.
Run migrations and restart gunicorn and celery to complete setup.
Openfire
Openfire is a jabber (XMPP) server.
3.2. Installation
47
Alliance Auth Documentation, Release
Prepare Your Settings
• Add 'allianceauth.services.modules.openfire', to your INSTALLED_APPS list
• Append the following to your auth project’s settings file:
# Jabber Configuration
JABBER_URL = ""
JABBER_PORT = 5223
JABBER_SERVER = ""
OPENFIRE_ADDRESS = ""
OPENFIRE_SECRET_KEY = ""
BROADCAST_USER = ""
BROADCAST_USER_PASSWORD = ""
BROADCAST_SERVICE_NAME = "broadcast"
Overview
Openfire is a java-based xmpp server (jabber).
Dependencies
One additional package is required - openjdk8
Ubuntu:
sudo add-apt-repository ppa:webupd8team/java -y
sudo apt-get update
sudo apt-get install oracle-java8-installer
CentOS:
sudo yum -y install java-1.8.0-openjdk java-1.8.0-openjdk-devel
Setup
Download Installer
Openfire is not available through repositories so we need to get a debian from the developer.
On your PC, naviage to the Ignite Realtime downloads section, and under Openfire select Linux, click on the debian
file (2nd from bottom of list, ends with .deb).
Retrieve the file location by copying the url from the “click here” link.
In the console, ensure you’re in your user’s home directory: cd ~
Now download the package. Replace the link below with the link you got earlier.
wget https://www.igniterealtime.org/downloadServlet?filename=openfire/openfire_4.1.1_
˓→all.deb
Now install from the debian. Replace the filename with your file name (the last part of the download url is the file
name)
48
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
sudo dpkg -i openfire_4.1.1_all.deb
Create Database
Performance is best when working from a SQL database. If you installed MySQL or MariaDB alongside your auth
project, go ahead and create a database for openfire:
mysql -u root -p
create database alliance_jabber;
grant all privileges on alliance_jabber . * to 'allianceserver'@'localhost';
exit;
Web Configuration
The remainder of the setup occurs through Openfire’s web interface. Navigate to http://example.com:9090, or if you’re
behind CloudFlare, go straight to your server’s IP:9090.
Select your language. I sure hope it’s english if you’re reading this guide.
Under Server Settings, set the Domain to example.com replacing it with your actual domain. Don’t touch the rest.
Under Database Settings, select Standard Database Connection
On the next page, select MySQL from the dropdown list and change the following:
• [server] is replaced by 127.0.0.1
• [database] is replaced by the name of the database to be used by Openfire
• enter the login details for your auth project’s database user
If Openfire returns with a failed to connect error, re-check these settings. Note the lack of square brackets.
Under Profile Settings, leave Default selected.
Create an administrator account. The actual name is irrelevant, just don’t lose this login information.
Finally, log in to the console with your admin account.
Edit your auth project’s settings file and enter the values you just set:
• JABBER_URL is the pubic address of your jabber server
• JABBER_PORT is the port for clients to connect to (usually 5223)
• JABBER_SERVER is the name of the jabber server. If you didn’t alter it during install it’ll usually be your
domain (eg example.com)
• OPENFIRE_ADDRESS is the web address of Openfire’s web interface. Use http:// with port 9090 or https://
with port 9091 if you configure SSL in Openfire
REST API Setup
Navigate to the plugins tab, and then Available Plugins on the left navigation bar. You’ll need to fetch the
list of available plugins by clicking the link.
Once loaded, press the green plus on the right for REST API.
Navigate the Server tab, Sever Settings subtab. At the bottom of the left navigation bar select REST API.
3.2. Installation
49
Alliance Auth Documentation, Release
Select Enabled, and Secret Key Auth.
OPENFIRE_SECRET_KEY.
Update your auth project’s settings with this secret key as
Broadcast Plugin Setup
Navigate to the Users/Groups tab and select Create New User from the left navigation bar.
Pick a username (eg broadcast) and password for your ping user. Enter these in your auth project’s settings file as
BROADCAST_USER and BROADCAST_USER_PASSWORD. Note that BROADCAST_USER needs to be in the format
user@example.com matching your jabber server name. Press Create User to save this user.
Broadcasting requires a plugin. Navigate to the plugins tab, press the green plus for the Broadcast plugin.
Navigate to the Server tab, Server Manager subtab, and select System Properties. Enter the following:
• Name: plugin.broadcast.disableGroupPermissions
– Value: True
– Do not encrypt this property value
• Name: plugin.broadcast.allowedUsers
– Value: broadcast@example.com, replacing the domain name with yours
– Do not encrypt this property value
If you have troubles getting broadcasts to work, you can try setting the optional (you will need to add it)
BROADCAST_IGNORE_INVALID_CERT setting to True. This will allow invalid certificates to be used when connecting to the Openfire server to send a broadcast.
Preparing Auth
Once all settings are entered, run migrations and restart gunicorn and celery.
Group Chat
Channels are available which function like a chat room. Access can be controlled either by password or ACL (not
unlike mumble).
Navigate to the Group Chat tab and select Create New Room from the left navigation bar.
• Room ID is a short, easy-to-type version of the room’s name users will connect to
• Room Name is the full name for the room
• Description is short text describing the room’s purpose
• Set a password if you want password authentication
• Every other setting is optional. Save changes.
Now select your new room. On the left navigation bar, select Permissions.
ACL is achieved by assigning groups to each of the three tiers: Owners, Admins and Members. Outcast is the
blacklist. You’ll usually only be assigning groups to the Member category.
50
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
phpBB3
and run migrations before continuing with this guide to ensure the service is installed.
Overview
phpBB is a free php-based forum. It’s the default forum for AllianceAuth.
Dependencies
PHPBB3 requires php installed in your web server. Apache has mod_php, NGINX requires php-fpm. See the
official guide for php package requirements.
Prepare Your Settings
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:
# PHPBB3 Configuration
PHPBB3_URL = ''
DATABASES['phpbb3'] = {
'ENGINE': 'django.db.backends.mysql',
'NAME': 'alliance_forum',
'USER': 'allianceserver-phpbb3',
'PASSWORD': 'password',
'HOST': '127.0.0.1',
'PORT': '3306',
}
Setup
Prepare the Database
Create a database to install phpbb3 in.
mysql -u root -p
create database alliance_forum;
grant all privileges on alliance_forum . * to 'allianceserver'@'localhost';
exit;
Edit your auth project’s settings file and fill out the DATABASES['phpbb3'] part.
Download Phpbb3
phpBB is available as a zip from their website. Navigate to the website’s downloads section using your PC browser
and copy the URL for the latest version zip.
In the console, navigate to your user’s home directory: cd ~
3.2. Installation
51
Alliance Auth Documentation, Release
Now download using wget, replacing the url with the url for the package you just retrieved
wget https://www.phpbb.com/files/release/phpBB-3.2.0.zip
This needs to be unpackaged. Unzip it, replacing the file name with that of the file you just downloaded
unzip phpBB-3.2.0.zip
Now we need to move this to our web directory. Usually /var/www/forums.
sudo mv phpBB3 /var/www/forums
The web server needs read/write permission to this folder
sudo chown -R www-data:www-data /var/www/forums
Configuring Web Server
You will need to configure you web server to serve PHPBB3 before proceeding with installation.
A minimal apache config file might look like:
<VirtualHost *:80>
ServerName forums.example.com
DocumentRoot /var/www/forums
<Directory /var/www/forums>
Require all granted
DirectoryIndex index.php
</Directory>
</VirtualHost>
A minimal nginx config file might look like:
server {
listen 80;
server_name forums.example.com;
root
/var/www/forums;
index index.php;
access_log /var/logs/forums.access.log;
˓→
location ~ /(config\.php|common\.php|cache|files|images/avatars/
upload|includes|store) {
deny all;
return 403;
}
location ~* \.(gif|jpe?g|png|css)$ {
expires
30d;
}
location ~ \.php$ {
try_files $uri =404;
fastcgi_pass
unix:/tmp/php.socket;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
52
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
}
}
Enter your forum’s web address as the PHPBB3_URL setting in your auth project’s settings file.
Web Install
Navigate to your forums web address where you will be presented with an installer.
Click on the Install tab.
All the requirements should be met. Press Start Install.
Under Database Settings, set the following:
• Database Type is MySQL
• Database Server Hostname is 127.0.0.1
• Database Server Port is left blank
• Database Name is alliance_forum
• Database Username is your auth MySQL user, usually allianceserver
• Database Password is this user’s password
You should see Succesful Connection and proceed.
Enter administrator credentials on the next page.
Everything from here should be intuitive.
phpBB will then write its own config file.
Open the Forums
Before users can see the forums, we need to remove the install directory
sudo 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.
_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),
3.2. Installation
53
Alliance Auth Documentation, Release
expand Advanced Permissions, under the Profile tab, set Can Change Avatars to Yes, and press
Apply Permissions.
_static/images/installation/services/phpbb3/avatar_permissions.png
Prepare Auth
Once settings have been configured, run migrations and restart gunicorn and celery.
SMF
Overview
SMF is a free php-based forum.
Dependencies
SMF requires php installed in your web server. Apache has mod_php, NGINX requires php-fpm. More details can
be found in the SMF requirements page.
Prepare Your Settings
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:
# SMF Configuration
SMF_URL = ''
DATABASES['smf'] = {
'ENGINE': 'django.db.backends.mysql',
'NAME': 'alliance_smf',
'USER': 'allianceserver-smf',
'PASSWORD': 'password',
'HOST': '127.0.0.1',
'PORT': '3306',
}
Setup
Download SMF
Using your browser, you can download the latest version of SMF to your desktop computer. All SMF
downloads can be found at SMF Downloads. The latest recommended version will always be available at
http://www.simplemachines.org/download/index.php/latest/install/.
54
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
Download using wget, replacing the url with the url for the package you just retrieved
wget http://download.simplemachines.org/index.php?thanks;filename=smf_2-0-13_install.
˓→zip
This needs to be unpackaged. Unzip it, replacing the file name with that of the file you just downloaded
unzip smf_2-0-13_install.zip
Now we need to move this to our web directory. Usually /var/www/forums.
sudo mv smf /var/www/forums
The web server needs read/write permission to this folder
sudo chown -R www-data:www-data /var/www/forums
Database Preparation
SMF needs a database. Create one:
mysql -u root -p
create database alliance_smf;
grant all privileges on alliance_smf . * to 'allianceserver'@'localhost';
exit;
Enter the database information into the DATABASES['smf'] section of your auth project’s settings file.
Web Server Configuration
Your web server needs to be configured to serve Alliance Market.
A minimal apache config might look like:
<VirtualHost *:80>
ServerName forums.example.com
DocumentRoot /var/www/forums
<Directory "/var/www/forums">
DirectoryIndex index.php
</Directory>
</VirtualHost>
A minimal nginx config might look like:
server {
listen 80;
server_name forums.example.com;
root
/var/www/forums;
index app.php;
access_log /var/logs/forums.access.log;
location ~ \.php$ {
try_files $uri =404;
fastcgi_pass
unix:/tmp/php.socket;
fastcgi_index index.php;
3.2. Installation
55
Alliance Auth Documentation, Release
fastcgi_param SCRIPT_FILENAME
include fastcgi_params;
$document_root$fastcgi_script_name;
}
}
Enter the web address to your forums into the SMF_URL setting in your auth project’s settings file.
Preparing Auth
Once settings are entered, apply migrations and restart gunicorn and celery.
Web Install
Navigate to your forums address where you will be presented with an installer.
Click on the Install tab.
All the requirements should be met. Press Start Install.
Under Database Settings, set the following:
• Database Type is MySQL
• Database Server Hostname is 127.0.0.1
• Database Server Port is left blank
• Database Name is alliance_smf
• Database Username is your auth MySQL user, usually allianceserver
• Database Password is this user’s password
Follow the directions in the installer.
Teamspeak 3
Overview
Teamspeak3 is the most popular VOIP program for gamers.
But have you considered using Mumble? Not only is it free, but it has features and performance far superior to
Teamspeak3.
Setup
Sticking with TS3? Alright, I tried.
Prepare Your Settings
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:
56
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
# Teamspeak3 Configuration
TEAMSPEAK3_SERVER_IP = '127.0.0.1'
TEAMSPEAK3_SERVER_PORT = 10011
TEAMSPEAK3_SERVERQUERY_USER = 'serveradmin'
TEAMSPEAK3_SERVERQUERY_PASSWORD = ''
TEAMSPEAK3_VIRTUAL_SERVER = 1
TEAMSPEAK3_PUBLIC_URL = ''
CELERYBEAT_SCHEDULE['run_ts3_group_update'] = {
'task': '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 (I’d recommed getting the
latest stable version – find this version number from the TeamSpeak site). Be sure to get a link to the linux version.
Download the server, replacing the link with the link you got earlier.
http://dl.4players.de/ts/releases/3.1.0/teamspeak3-server_linux_amd64-3.1.0.tar.bz2
Now we need to extract the file.
tar -xf teamspeak3-server_linux_amd64-3.1.0.tar.bz2
Create User
Teamspeak needs its own user.
sudo adduser --disabled-login teamspeak
Install Binary
Now we move the server binary somewhere more accessible and change its ownership to the new user.
sudo mv teamspeak3-server_linux_amd64 /usr/local/teamspeak
sudo chown -R teamspeak:teamspeak /usr/local/teamspeak
Startup
Now we generate a startup script so teamspeak comes up with the server.
sudo ln -s /usr/local/teamspeak/ts3server_startscript.sh /etc/init.d/teamspeak
sudo update-rc.d teamspeak defaults
Finally we start the server.
sudo service teamspeak start
3.2. Installation
57
Alliance Auth Documentation, Release
Update Settings
The console will spit out a block of text. If it does not appear, it can be found with sudo service teamspeak
status. SAVE THIS.
If you plan on claiming the ServerAdmin token, do so with a different TeamSpeak client profile than the one used for
your auth account, or you will lose your admin status.
Edit the settings you added to your auth project’s settings file earlier, entering the following:
• TEAMSPEAK3_SERVERQUERY_USER is loginname from that block of text it just spat out (usually
serveradmin)
• TEAMSPEAK3_SERVERQUERY_PASSWORD is password from that block of text it just spat out
• TEAMSPEAK_VIRTUAL_SERVER is the virtual server ID of the server to be managed - it will only ever not be
1 if your server is hosted by a professional company
• TEAMSPEAK3_PUBLIC_URL is the public address of your teamspeak server. Do not include any leading
http:// or teamspeak://
Once settings are entered, run migrations and restart gunicorn and celery.
Generate User Account
And now we can generate ourselves a user account. Navigate to the services in AllianceAuth for your user account
and press the checkmark for TeamSpeak 3.
Click the URL provided to automatically connect to our server. It will prompt you to redeem the serveradmin token,
enter the token from startup.
Groups
Now we need to make groups. AllianceAuth handles groups in teamspeak differently: instead of creating groups it
creates an association between groups in TeamSpeak and groups in AllianceAuth. Go ahead and make the groups you
want to associate with auth groups, keeping in mind multiple TeamSpeak groups can be associated with a single auth
group.
Navigate back to the AllianceAuth admin interface (example.com/admin) and under Services, select Auth / TS
Groups. In the top-right corner click Add.
The dropdown box provides all auth groups. Select one and assign TeamSpeak groups from the panels below. If these
panels are empty, wait a minute for the database update to run, or see the troubleshooting section below.
Troubleshooting
Insufficient client permissions (failed on Invalid permission:
0x26)
Using the advanced permissions editor, ensure the Guest group has the permission Use Privilege Keys to
gain permissions (under Virtual Server expand the Administration section)
To enable advanced permissions, on your client go to the Tools menu, Application, and under the Misc section,
tick Advanced permission system
58
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
TS group models not populating on admin site
The method which populates these runs every 30 minutes. To populate manually, start a django shell:
python manage.py shell
And execute the update:
from services.modules.teamspeak3.tasks import Teamspeak3Tasks
Teamspeak3Tasks.run_ts3_group_update()
Ensure that command does not return an error.
2564 access to default group is forbidden
This usually occurs because auth is trying to remove a user from the Guest group (group ID 8). The guest group is
only assigned to a user when they have no other groups, unless you have changed the default teamspeak server config.
Teamspeak servers v3.0.13 and up are especially susceptible to this. Ensure the Channel Admin Group is not set to
Guest (8). Check by right clicking on the server name, Edit virtual server, and in the middle of the panel
select the Misc tab.
TypeError:
string indices must be integers, not str
This error generally means teamspeak returned an error message that went unhandled. The full traceback is required
for proper debugging, which the logs do not record. Please check the superuser notifications for this record and get in
touch with a developer.
3331 flood ban
This most commonly happens when your teamspeak server is externally hosted. You need to add the auth server IP to
the teamspeak serverquery whitelist. This varies by provider.
If you have SSH access to the server hosting it, you need to locate the teamspeak server folder and add the auth server
IP on a new line in server_query_whitelist.txt
520 invalid loginname or password
The serverquery account login specified in local.py is incorrect. Please verify TEAMSPEAK3_SERVERQUERY_USER
and TEAMSPEAK3_SERVERQUERY_PASSWORD. The installation section describes where to get them.
2568 insufficient client permissions
This usually occurs if you’ve created a separate serverquery user to use with auth. It has not been assigned sufficient
permissions to complete all the tasks required of it. The full list of required permissions is not known, so assign
liberally.
3.2. Installation
59
Alliance Auth Documentation, Release
XenForo
Overview
XenForo is a popular paid forum. This guide will assume that you already have XenForo installed with a valid license
(please keep in mind that XenForo is not free nor open-source, therefore you need to purchase a license first). If you
come across any problems related with the installation of XenForo please contact their support service.
Prepare Your Settings
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:
# XenForo Configuration
XENFORO_ENDPOINT = 'example.com/api.php'
XENFORO_DEFAULT_GROUP = 0
XENFORO_APIKEY
= 'yourapikey'
XenAPI
By default XenForo does not support any kind of API, however there is a third-party package called XenAPI which
provides a simple REST interface by which we can access XenForo’s functions in order to create and edit users.
The installation of XenAPI is pretty straight forward. The only thing you need to do is to download the api.php
from the official repository and upload it in the root folder of your XenForo installation. The final result should look
like this: forumswebsite.com/ api.php
Now that XenAPI is installed the only thing left to do is to provide a key.
$restAPI = new RestAPI('REPLACE_THIS_WITH_AN_API_KEY');
Configuration
The settings you created earlier now need to be filled out.
XENFORO_ENDPOINT is the address to the API you added. No leading http://, but be sure to include the
/api.php at the end.
XENFORO_DEFAULT_GROUP is the ID of the group in XenForo auth users will be added to. Unfortunately XenAPI
cannot create new groups, therefore you have to create a group manually and then get its ID.
XENFORO_API_KEY is the API key value you set earlier.
Once these are entered, run migrations and restart gunicorn and celery.
Maintenance
Changelog
60
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
From now on all changelogs will be included as release notes.
https://github.com/allianceauth/allianceauth/releases
547
Oct 16
Golly this is a big one. Upgrading takes a bit of work. For full instructions click here.
• Update django version to 1.10
• Remove member/blue permissions
– implement user states
• implement Django’s messaging framework for site feedback
• remove pathfinder support
• remove fleet fits page
• remove wormhole tracker
• do not store service passwords
• supervisor configs for celery tasks and authenticator
• buttons on admin site to sync service groups
• show number of notifications
• fix all button css
• rewrite and centralize API checks
• bulk mark read / delete for notifications
• replace hard-coded urls with reverse by name
• python 3 compatibility
• correct navbar active link with translated urls
468
June 12
• XenForo integration added
• Discord integration updated to use OAuth and official API
• FleetUp fixes for empty responses
441
May 27
• Added option to require new API keys
– Reduces threat of stolen keys being used to create accounts
– Requires two new settings:
3.3. Maintenance
61
Alliance Auth Documentation, Release
* REJECT_OLD_APIS, default False
* REJECT_OLD_APIS_MARGIN, default 50
423
May 9
• Added statistics to fleet activity tracking
• Capture teamspeak error codes in logs from failed account creation
401
Apr 29
• Added FleetUp integration
• Added Fleet Activity Tracking links
– settings.py has new entries and will have to be updated
394
Apr 17
• Added Discourse integration
• Added Pathfinder integration
– settings.py has new entries and will have to be updated
386
Apr 15 2016
• Corrected Teamspeak group sync triggers
• Modified username sanitization to reduce username collisions
369
Apr 7 2016
• Added Evernus Alliance Market Integration
– Requires libffi-devel (centos) or libffi-dev (ubuntu) and pip install bcrypt
365
Apr 6 2016
• Added SMF2 Forums integration
– Requires a settings.py file update for existing installs
62
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
360
Apr 4 2016
• Added a countdown / local time to the fleet operations timers
• Fixed the corporation structure timers so the countdown shows up correctly
340
Mar 31 2016
• Added Support for IP Board 4 / IP Suite 4
– You must update settings.py accordingly if updating form a previous version.
– only allows for the member group to sync. Additional groups must be manually added
• Fixed a bug with corporation stats not showing correct users and numbers
328
Mar 24 2016
• Added Enhancements to the SRP Management
– Users can now enable and disable srp links.
– The Approve and Reject buttons will show up depending on the srp status.
– Fixed an issue where SRP Requests were not getting the proper status assigned.
321
Mar 23 2016
• Added Ship types and kill board data to the SRP management.
– These are automatically pulled from zKillboard.
– zKillboard is the only killboard links that the SRP Manager Accepts Now.
314
Mar 22 2016
• Revamp of the Human Resources Application and Management System
– see the docs for how to use the new system
– a completely untested conversion script exists. If you want to view your old models, contact Adarnof to
try it out
• Moved Error Handling for the API Keys to the API Calls to better handle API server outages
• Removed the infamous database update task
– implemented a receiver to update service groups as they change
3.3. Maintenance
63
Alliance Auth Documentation, Release
To remove the database update task from the scheduler, navigate to your django admin site, and delete the
run_databaseUpdate model from the periodic tasks. Restart celery.
Mumble now uses an ICE authenticator. This requires an additional dependency. Please install libbz2-dev and
libssl-dev prior to running the update script:
sudo apt-get install libbz2-dev libssl-dev
Now run the update script.
Old Mumble accounts are incompatible. Users will need to recreate them (sorry). To clear the old ones out:
python manage.py shell
from services.tasks import disable_mumble
disable_mumble()
To set up the authenticator, follow the Mumble setup guide.
Optional: you can delete the entire mumble database block in settings.py
304
Mar 8 2016
• Repurposed Signature Tracker for Wormhole Use. Combat sites are a ever changing thing therefore removed.
• Increased run_databaseUpdate time to 10 minutes to address stability problems for larger alliances.
296
Feb 27 2016
• corrected an issue with populating corp stats for characters with missing api keys
• moved log files to dedicated folder to allow apache access so it can rotate them
• merged Corp Stats and Member Tracking apps
– corp_stats and corputils permissions have been depreciated
– assign either of corp_apis or alliance_apis to get access to Corp Stats app
* corp_apis populates APIs of user’s main corp
* alliance_apis populates APIs of user’s main alliance
289
Feb 25 2016
• Changed the start time format on the fleet operations board to use the 24 hour format
– Fixed an issue when updating the fleet operations timers the date time picker would not work.
64
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
286
Feb 23 2016
• Added ability to remove notifications
278
Feb 18 2016
• notifications for events:
– api failed validation during refresh
– group request accepted/rejected
– corp application accepted/rejected
– services disabled
• logging notifications include traceback
• automatically assign alliance groups of the form “Alliance_NAME”
• parallel corp model updates via celery broker for performance improvements
• new functions to clear service info for decommissioning a service
settings.py will need to be updated to include the new settings.
265
Feb 13 2016
• prototype notification system
• logging errors as notifications based on new permission logging_notifications
The logging configuration in settings.py has changed. Please update.
263
Feb 12 2016
• revamped run_corp_update function which actually works
• fixed group syncing in discord and openfire
259
Feb 11 2016
• Added ability to edit structure timers
• Added ability to edit fleet operations timers
• Added ability to edit Signatures
3.3. Maintenance
65
Alliance Auth Documentation, Release
245
Feb 7 2016
• ability to toggle assigning corp groups
• users able to manually trigger api refresh
Two new settings in settings.py - MEMBER_CORP_GROUPS and BLUE_CORP_GROUPS - be sure to add them.
226
Jan 31 2016
Been a while since one of these was written so a big list.
• corrected user permission caching for Phpbb3
• open groups which don’t require application approval
• additional weblink data for TS3 to encourage proper usernames
• corp-restricted timers
• signature tracker
• tolerate random 221 errors from EVE api servers till CCP FoxFour gets it sorted
• new corp member auditing app
• fleet operation timers
• revamped member status checking and assignment
Loads of new permissions. See the readme for descriptions.
Need to install new requirements - sudo pip install -r requirements.txt
Incompatible with Python2.6 or older. Please update. Please. It’s 2016 people.
Settings.py got nuked. Backup your current settings.py, copy the example, and repopulate.
New caching directory for requests - if you’re using apache to serve the site, cache/ needs to be writable by the
webserver. Easiest way is to chown -R www-data:www-data cache from within the allianceauth install dir.
145
Jan 6 2016
• complete logging system for all apps
• custom service passwords
• Discord token caching to prevent locking out users
• Jabber broadcast group restrictions
• Password reset email contains domain
• Index page only renders forums/killboard/media if url specified
• timestamps on hrapplication comments
• corrected corp/alliance model creation logic
66
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
• corrected typecasting of access masks during api checks
• prevent TS3 from attempting to sync groups if not installed
New permissions - see readme.
Need to install new requirements.
Settings.py has changed. Make a new one from the example.
118
Dec 2 2015
• add timers by time remaining
• Discord support
• corrected celerytask logic
• handle many 500s thrown in views
New settings.py again. Need to reinstall requirements.
107
Nov 28 2015
• added broadcast plugin support for openfire
• timer addition by remaining time, not fixed date
• corrected alliance model deletion logic
• corrected name rendering on templates
Openfire setup guide has been updated for the new plugin.
102
Nov 25 2015
• variable API requirements
• api access mask validation during refresh
• support for customization of templates
• celery task resource reduction
• vagrant support
All templates and staticfiles have been moved. If you’ve customized any of these, make a backup before pulling
changes.
New command python manage.py collectstatic added to install guide. Should be run after every update.
New settings.py template. Make a backup of the old one, copy the example, and populate.
3.3. Maintenance
67
Alliance Auth Documentation, Release
87
Nov 15 2015
A couple quality-of-life improvements.
• corrected an error in the Teamspeak3 Manager improperly parsing responses
• added the ability to hide groups from the web interface
• added a feature for phpbb avatars to be set to the character portrait
New permissions for the HiddenGroup model only affect the admin site (default model permissions)
The Phpbb3 setup guide has been updated to reflect avatars.
72
Nov 5th 2015
On November 5th we performed two major pulls from Adarnof’s and Kaezon’s forks.
Improvements include:
• ability to deploy for either corp or alliance
• improved logic for member status transitions
• group syncing to TS3
• template corrections
Migration to the new version is a bit trickier because of changes to settings.py - it’s easiest to archive the old one, make
a copy of the new template, and repopulate it.
Troubleshooting
Something broken? Stuck on an issue? Can’t get it set up?
Start here:
• check the issues - especially closed ones
• check the forums
No answer?
• open an issue
• harass us on gitter
• post to the forums
Common Problems
pip install -r requirements.txt is failing
Either you need to sudo that command, or it’s a missing dependency. Check the list, reinstall, and try again.
68
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
I’m getting an error 500 trying to connect to the website on a new install
Read the apache error log: sudo less /var/log/apache2/error.log. Press Shift+G to go to the end of
the file.
If it talks about failing to import something, google its name and install it.
If it whines about being unable to configure logger, see below.
Failed to configure log handler
Make sure the log directory is write-able: chmod -R 777 /home/allianceserver/allianceauth/log,
then reload apache/celery/supervisor/etc.
Groups aren’t syncing to services
Make sure the background processes are running: ps aux | grep celery should return more than 1 line. More
lines if you have more cores on your server’s processor. If there are more than two lines starting with SCREEN, kill
all of them with kill # where # is the process ID (second column), then restart with these background process
commands from the allianceauth directory. You can’t start these commands as root.
If that doesn’t do it, try clearing the worker queue. First kill all celery processes as described above, then do the
following:
redis-cli FLUSHALL
celery -A alliance_auth worker --purge
Press Control+C once.
Now start celery again with these background process commands.
While debugging, it is useful to see if tasks are being executed.
The easiest tool is flower.
Install it with this:
sudo pip install flower, then start it with this:
celery flower
--broker=amqp://guest:guest@localhost:5672//. To view the status, navigate to your server
IP, port 5555.
Development
Documentation
The documentation for Alliance Auth uses Sphinx to build documentation. When a new commit to specific branches
is made (master, primarily), the repository is automatically pulled, docs built and deployed on readthedocs.org.
Documentation was migrated from the Github wiki pages and into the repository to allow documentation changes to
be included with pull requests. This means that documentation can be guaranteed to be updated when a pull request
is accepted rather than hoping documentation is updated afterwards or relying on maintainers to do the work. It also
allows for documentation to be maintained at different versions more easily.
Building Documentation
If you’re developing new documentation, its likely you’ll want or need to test build it before committing to your
branch. To achieve this you can use Sphinx to build the documentation locally as it appears on Read the Docs.
3.4. Development
69
Alliance Auth Documentation, Release
Activate your virtual environment (if you’re using one) and install the documentation requirements found in
docs/requirements.txt using pip, e.g. pip install -r docs/requirements.txt.
You can then build the docs by changing to the docs/ directory and running make html or make dirhtml,
depending on how the Read the Docs project is configured. Either should work fine for testing. You can now find the
output of the build in the /docs/_build/ directory.
Occasionally you may need to fully rebuild the documents by running make clean first, usually when you add or
rearrange toctrees.
Documentation Format
CommonMark Markdown is the current preferred format, via recommonmark. reStructuredText is supported if required, or you can execute snippets of reST inside Markdown by using a code block:
```eval_rst
reStructuredText here
```
Markdown is used elsewhere on Github so it provides the most portability of documentation from Issues and Pull
Requests as well as providing an easier initial migration path from the Github wiki.
Integrating Services
One of the primary roles of Alliance Auth is integrating with external services in order to authenticate and manage
users. This is achieved through the use of service modules.
The Service Module
Each service module is its own self contained Django app. It will likely contain views, models, migrations and
templates. Anything that is valid in a Django app is valid in a service module.
Normally service modules live in services.modules though they may also be installed as external packages and
installed via pip if you wish. A module is installed by including it in the INSTALLED_APPS setting.
Service Module Structure
Typically a service will contain 5 key components:
• The Hook
• The Service Manager
• The Views
• The Tasks
• The Models
The architecture looks something like this:
urls ------- Views
|
|
|
|
ServiceHook ---- Tasks ---- Manager
70
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
|
|
AllianceAuth
Where:
Module -- Dependency/Import
While this is the typical structure of the existing services modules, there is no enforcement of this structure and you are,
effectively, free to create whatever architecture may be necessary. A service module need not even communicate with
an external service, for example, if similar triggers such as validate_user, delete_user are required for a module it may
be convenient to masquerade as a service. Ideally though, using the common structure improves the maintainability
for other developers.
The Hook
In order to integrate with Alliance Auth service modules must provide a services_hook. This hook will
be a function that returns an instance of the services.hooks.ServiceHook class and decorated with the
@hooks.registerhook decorator. For example:
@hooks.register('services_hook')
def register_service():
return ExampleService()
This would register the ExampleService
services.hooks.ServiceHook.
class
which
would
need
to
be
a
subclass
of
Important: The hook MUST be registered in yourservice.auth_hooks along with any other hooks you are registering
for Alliance Auth.
A subclassed ServiceHook might look like this:
class ExampleService(ServicesHook):
def __init__(self):
ServicesHook.__init__(self)
self.urlpatterns = urlpatterns
self.service_url = 'http://exampleservice.example.com'
"""
Overload base methods here to implement functionality
"""
The ServiceHook class
The base ServiceHook class defines function signatures that Alliance Auth will call under certain conditions in
order to trigger some action in the service.
You will need to subclass services.hooks.ServiceHook in order to provide implementation of the functions
so that Alliance Auth can interact with the service correctly. All of the functions are optional, so its up to you to define
what you need.
Instance Variables:
3.4. Development
71
Alliance Auth Documentation, Release
• self.name
• self.urlpatterns
• self.service_ctrl_template
Properties:
• title
Functions:
• delete_user
• validate_user
• sync_nickname
• update_groups
• update_all_groups
• service_enabled_members
• service_enabled_blues
• service_active_for_user
• show_service_ctrl
• render_service_ctrl
self.name
Internal name of the module, should be unique amongst modules.
self.urlpatterns
You should define all of your service urls internally, usually in urls.py. Then you can import them and set
self.urlpatterns to your defined urlpatterns.
from . import urls
...
class MyService(ServiceHook):
def __init__(self):
...
self.urlpatterns = urls.urlpatterns
All of your apps defined urlpatterns will then be included in the URLconf when the core application starts.
self.service_ctrl_template
This is provided as a courtesy and defines the default template to be used with render_service_ctrl. You are free to
redefine or not use this variable at all.
72
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
title
This is a property which provides a user friendly display of your service’s name. It will usually do a reasonably good
job unless your service name has punctuation or odd capitalisation. If this is the case you should override this method
and return a string.
delete_user
def delete_user(self,user,notify_user=False):
Delete the users service account, optionally notify them that the service has been disabled. The user parameter should
be a Django User object. If notify_user is set to True a message should be set to the user via the notifications
module to alert them that their service account has been disabled.
The function should return a boolean, True if successfully disabled, False otherwise.
validate_user
def validate_user(self,user):
Validate the users service account, deleting it if they should no longer have access. The user parameter should be a
Django User object.
An implementation will probably look like the following:
def validate_user(self, user):
logger.debug('Validating user %s %s account' % (user, self.name))
if ExampleTasks.has_account(user) and not self.service_active_for_user(user):
self.delete_user(user, notify_user=True)
No return value is expected.
This function will be called periodically on all users to validate that the given user should have their current service
accounts.
sync_nickname
def sync_nickname(self,user):
Very optional. As of writing only one service defines this. The user parameter should be a Django User object.
When called, the given users nickname for the service should be updated and synchronised with the service.
If this function is defined, an admin action will be registered on the Django Users view, allowing admins to manually
trigger this action for one or many users. The hook will trigger this action user by user, so you won’t have to manage
a list of users.
update_groups
def update_groups(self,user):
Update the users group membership. The user parameter should be a Django User object. When this is called the
service should determine the groups the user is a member of and synchronise the group membership with the external
service. If you service does not support groups then you are not required to define this.
3.4. Development
73
Alliance Auth Documentation, Release
If this function is defined, an admin action will be registered on the Django Users view, allowing admins to manually
trigger this action for one or many users. The hook will trigger this action user by user, so you won’t have to manage
a list of users.
This action is usually called via a signal when a users group membership changes (joins or leaves a group).
update_all_groups
def update_all_groups(self):
The service should iterate through all of its recorded users and update their groups.
I’m really not sure when this is called, it may have been a hold over from before signals started to be used. Regardless,
it can be useful to server admins who may call this from a Django shell to force a synchronisation of all user groups
for a specific service.
service_active_for_user
def service_active_for_user(self,user):
Is this service active for the given user? The user parameter should be a Django User object.
Usually you wont need to override this as it calls service_enabled_members or service_enabled_blues
depending on the users state.
show_service_ctrl
def show_service_ctrl(self,user,state):
Should the service be shown for the given user with the given state? The user parameter should be a Django
User object, and the state parameter should be a valid state from authentication.states.
Usually you wont need to override this function.
For more information see the render_service_ctrl section.
render_service_ctrl
def render_services_ctrl(self,request):
Render the services control row. This will be called for all active services when a user visits the /services/ page
and show_service_ctrl returns True for the given user.
It should return a string (usually from render_to_string) of a table row (<tr>) with 4 columns (<td>). Column
#1 is the service name, column #2 is the users username for this service, column #3 is the services URL, and column
#4 is the action buttons.
You may either define your own service template or use the default one provided. The default can be used like this
example:
def render_services_ctrl(self, request):
"""
Example for rendering the service control panel row
You can override the default template and create a
custom one if you wish.
:param request:
74
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
:return:
"""
urls = self.Urls()
urls.auth_activate = 'auth_example_activate'
urls.auth_deactivate = 'auth_example_deactivate'
urls.auth_reset_password = 'auth_example_reset_password'
urls.auth_set_password = 'auth_example_set_password'
return render_to_string(self.service_ctrl_template, {
'service_name': self.title,
'urls': urls,
'service_url': self.service_url,
'username': 'example username'
}, request=request)
the Urls class defines the available URL names for the 4 actions available in the default template:
• Activate (create service account)
• Deactivate (delete service account)
• Reset Password (random password)
• Set Password (custom password)
If you don’t define one or all of these variable the button for the undefined URLs will not be displayed.
Most services will survive with the default template. If, however, you require extra buttons for whatever reason, you
are free to provide your own template as long as you stick within the 4 columns. Multiple rows should be OK, though
may be confusing to users.
Menu Item Hook
If you services needs cannot be satisfied by the Service Control row, you are free to specify extra hooks by subclassing
or instantiating the services.hooks.MenuItemHook class.
For more information see the Menu Hooks page.
The Service Manager
The service manager is what interacts with the external service. Ideally it should be completely agnostic about its environment, meaning that it should avoid calls to Alliance Auth and Django in general (except in special circumstances
where the service is managed locally, e.g. Mumble). Data should come in already arranged by the Tasks and data
passed back for the tasks to manage or distribute.
The reason for maintaining this separation is that managers may be reused from other sources and there may not
even be a need to write a custom manager. Likewise, by maintaining this neutral environment others may reuse the
managers that we write. It can also significantly ease the unit testing of services.
The Views
As mentioned at the start of this page, service modules are fully fledged Django apps. This means you’re free to do
whatever you wish with your views.
Typically most traditional username/password services define four views.
• Create Account
3.4. Development
75
Alliance Auth Documentation, Release
• Delete Account
• Reset Password
• Set Password
These views should interact with the service via the Tasks, though in some instances may bypass the Tasks and access
the manager directly where necessary, for example OAuth functionality.
The Tasks
The tasks component is the glue that holds all of the other components of the service module together. It provides the
function implementation to handle things like adding and deleting users, updating groups, validating the existence of
a users account. Whatever tasks auth_hooks and views have with interacting with the service will probably live
here.
The Models
Its very likely that you’ll need to store data about a users remote service account locally. As service modules are fully
fledged Django apps you are free to create as many models as necessary for persistent storage. You can create foreign
keys to other models in Alliance Auth if necessary, though I strongly recommend you limit this to the User and Groups
models from django.contrib.auth.models and query any other data manually.
If you create models you should create the migrations that go along with these inside of your module/app.
Examples
There is a bare bones example service included in services.modules.example, you may like to use this as the
base for your new service.
You should have a look through some of the other service modules before you get started to get an idea of the general
structure of one. A lot of them aren’t perfect so don’t feel like you have to rigidly follow the structure of the existing
services if you think its sub-optimal or doesn’t suit the external service you’re integrating.
Testing
You will need to add unit tests for all aspects of your service module before it is accepted. Be mindful that you don’t
actually want to make external calls to the service so you should mock the appropriate components to prevent this
behaviour.
Menu Hooks
Note: Currently most menu items are statically defined in the base.html template. Ideally this behaviour will change
over time with each module of Alliance Auth providing all of its menu items via the hook. New modules should aim
to use the hook over statically adding menu items to the base template.
The menu hooks allow you to dynamically specify menu items from your plugin app or service. To achieve this you
should subclass or instantiate the services.hooks.MenuItemHook class and then register the menu item with
one of the hooks.
To register a MenuItemHook class you would do the following:
76
Chapter 3. Troubleshooting
Alliance Auth Documentation, Release
@hooks.register('menu_item_hook')
def register_menu():
return MenuItemHook('Example Item', 'glyphicon glyphicon-heart', 'example_url_name
˓→', 150)
The MenuItemHook class specifies some parameters/instance variables required for menu item display.
MenuItemHook(text,classes,url_name,order=None)
text
The text value of the link
classes
The classes that should be applied to the bootstrap menu item icon
url_name
The name of the Django URL to use
order
An integer which specifies the order of the menu item, lowest to highest
navactive
A list of views or namespaces the link should be highlighted on. See django-navhelper for usage. Defaults to the
supplied url_name.
If you cannot get the menu item to look the way you wish, you are free to subclass and override the default render
function and the template used.
URL Hooks
Note: Currently most URL patterns are statically defined in the project’s core urls.py file. Ideally this behaviour
will change over time with each module of Alliance Auth providing all of its menu items via the hook. New modules
should aim to use the hook over statically adding URL patterns to the project’s patterns.
The URL hooks allow you to dynamically specify URL patterns from your plugin app or service. To achieve this you
should subclass or instantiate the services.hooks.UrlHook class and then register the URL patterns with the
hook.
To register a UrlHook class you would do the following:
@hooks.register('url_hook')
def register_urls():
return UrlHook(app_name.urls, 'app_name', r^'app_name/')
3.4. Development
77
Alliance Auth Documentation, Release
The UrlHook class specifies some parameters/instance variables required for URL pattern inclusion.
UrlHook(urls,app_name,base_url)
urls
The urls module to include. See the Django docs for designing urlpatterns.
namespace
The URL namespace to apply. This is usually just the app name.
base_url
The URL prefix to match against in regex form. Example r'^app_name/'. This prefix will be applied in front of
all URL patterns included. It is possible to use the same prefix as existing apps (or no prefix at all) but standard URL
resolution ordering applies (hook URLs are the last ones registered).
Example
An app called plugin provides a single view:
def index(request):
return render(request, 'plugin/index.html')
The app’s urls.py would look like so:
from django.conf.urls import url
import plugin.views
urlpatterns = [
url(r^'index$', plugins.views.index, name='index'),
]
Subsequently it would implement the UrlHook in a dedicated auth_hooks.py file like so:
from alliance_auth import hooks
from services.hooks import UrlHook
import plugin.urls
@hooks.register('url_hook')
def register_urls():
return UrlHook(plugin.urls, 'plugin', r^'plugin/')
When this app is included in the project’s settings.INSTALLED_APPS users would access the index view by
navigating to https://example.com/plugin/index.
78
Chapter 3. Troubleshooting
Download PDF

advertising