Move documentation into repository (#613)

This commit is contained in:
Basraah 2017-01-06 15:11:24 +10:00 committed by Adarnof
parent 8e64fe145e
commit 9ad61c1f4c
33 changed files with 2303 additions and 0 deletions

1
docs/.gitignore vendored Normal file
View File

@ -0,0 +1 @@
_build/

20
docs/Makefile Normal file
View File

@ -0,0 +1,20 @@
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = AllianceAuth
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

173
docs/conf.py Normal file
View File

@ -0,0 +1,173 @@
# -*- coding: utf-8 -*-
#
# Alliance Auth documentation build configuration file, created by
# sphinx-quickstart on Tue Jan 3 12:56:59 2017.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
# Support for recommonmark module
import recommonmark
from recommonmark.parser import CommonMarkParser
from recommonmark.transform import AutoStructify
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
# source_suffix = ['.rst', '.md']
source_suffix = ['.md', '.rst']
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'Alliance Auth'
copyright = u'2017, Alliance Auth'
author = u'R4stl1n'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = u'1.14'
# The full version, including alpha/beta/rc tags.
# release = u'1.14.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#
# html_theme_options = {}
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# -- Options for HTMLHelp output ------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'AllianceAuthdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#
# 'preamble': '',
# Latex figure (float) alignment
#
# 'figure_align': 'htbp',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'AllianceAuth.tex', u'Alliance Auth Documentation',
u'R4stl1n', 'manual'),
]
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'allianceauth', u'Alliance Auth Documentation',
[author], 1)
]
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'AllianceAuth', u'Alliance Auth Documentation',
author, 'AllianceAuth', 'Alliance service auth to help large scale alliances manage services.',
'Miscellaneous'),
]
# Markdown support
source_parsers = {
'.md': CommonMarkParser,
}
def setup(app):
app.add_config_value('recommonmark_config', {
'auto_toc_tree_section': 'Contents',
}, True)
app.add_transform(AutoStructify)

View File

@ -0,0 +1,38 @@
# Documentation
The documentation for Alliance Auth uses [Sphinx](http://www.sphinx-doc.org/) to build documentation. When a new commit
to specific branches is made (master, primarily), the repository is automatically pulled, docs built and deployed on
[readthedocs.org](https://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.
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](https://github.com/rtfd/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.

View File

@ -0,0 +1,7 @@
# Development
```eval_rst
.. toctree::
documentation
```

View File

@ -0,0 +1,84 @@
# HR Applications
## 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.
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.
```eval_rst
+---------------------------------------+------------------+----------------------------------------------------+
| Permission | Admin Site | Auth Site |
+=======================================+==================+====================================================+
| auth.human_resources | None | Can view applications and mark in progress |
+---------------------------------------+------------------+----------------------------------------------------+
| hrapplications.approve_application | None | Can approve applications |
+---------------------------------------+------------------+----------------------------------------------------+
| hrapplications.delete_application | Can delete model | Can delete applications |
+---------------------------------------+------------------+----------------------------------------------------+
| hrapplications.reject_applications | None | Can reject applications |
+---------------------------------------+------------------+----------------------------------------------------+
| hrapplications.view_apis | None | Can view applicant API keys, and audit in Jacknife |
+---------------------------------------+------------------+----------------------------------------------------+
| hrapplications.add_applicationcomment | Can create model | Can comment on applications |
+---------------------------------------+------------------+----------------------------------------------------+
```
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 make much sense.
## 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.
### 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.

9
docs/features/index.md Normal file
View File

@ -0,0 +1,9 @@
# Features
```eval_rst
.. toctree::
:maxdepth: 1
:caption: Contents
hrapplications
```

62
docs/index.md Normal file
View File

@ -0,0 +1,62 @@
# Alliance Auth
Alliance service auth to help large scale alliances manage services. Built for "The 99 Percent" open for anyone to use
# Installing
[Ubuntu Setup Guide](installation/auth/ubuntu.md)
For other distros, adapt the procedure and find distro-specific alternatives for the [dependencies](installation/auth/dependencies.md)
# Using
See the [Quick Start Guide](installation/auth/quickstart.md)
# Troubleshooting
Read the [list of common problems.](maintenance/troubleshooting.md)
# Upgrading
As AllianceAuth is developed, new features are added while old bugs are repaired. Its good practice to keep your instance of AllianceAuth up to date.
Some updates require specific instructions. Refer to their entry in the [changelog](maintenance/changelog.md)
In general, the update process has 4 steps:
- download the latest code
- generate new models in the database
- update current models in the database
- rebuild web cache
To perform each of these steps, youll need to be working from the console in the AllianceAuth directory. Usually `cd ~/allianceauth`
Start by pulling the code changes:
git pull
Modify settings.py according to the changelog.
For an automated upgrade, run the script:
bash update.sh
For a manual upgrade, execute the commands in this order:
sudo pip install -r requirements.txt
python manage.py migrate
python manage.py collectstatic
```eval_rst
.. toctree::
:maxdepth: 3
:caption: Contents
features/index
installation/index
maintenance/index
development/index
```

View File

@ -0,0 +1,77 @@
# Apache Setup
### Overview
AllianceAuth gets served using a Web Server Gateway Interface (WSGI) script. This script passes web requests to AllianceAuth which generates the content to be displayed and returns it. This means very little has to be configured in Apache to host AllianceAuth.
### Required Parameters for AllianceAuth Core
The AllianceAuth core requires the following parameters to be set:
WSGIDaemonProcess
WSGIProcessGroup
WSGIScriptAlias
The following aliases are required:
Alias /static/ to point at the static folder
Alias /templates/ to point at the templates folder
## Description of Parameters
- `WSGIDaemonProcess` is the name of the process/application. It also needs to be passed the python-path parameter directing python to search the AllianceAuth directory for modules to load.
- `WSGIProcessGroup` is the group to run the process under. Typically the same as the name of the process/application.
- `WSGIScriptAlias` points to the WSGI script.
## Additional Parameters for Full Setup
To pass additional services the following aliases and directories are required:
- `Alias /forums` to point at the forums folder
- `Alias /killboard` to point at the killboard
Each of these require directory permissions allowing all connections.
For Apache 2.4 or greater:
<Directory "/path/to/alias/folder">
Require all granted
</Directory>
For Apache 2.3 or older:
<Directory "/path/to/alias/folder">
Order Deny,Allow
Allow from all
</Directory>
## SSL
You can supply your own SSL certificates if you so desire. The alternative is running behind cloudflare for free SSL.
## Sample Config Files
### Own SSL Cert
- Apache 2.4 or newer:
- [000-default.conf](http://pastebin.com/3LLzyNmV)
- [default-ssl.conf](http://pastebin.com/HUPPEp0R)
- Apache 2.3 or older:
- [000-default](http://pastebin.com/HfyKpQNu)
- [default-ssl](http://pastebin.com/2WCS5jnb)
### No SSL or Cloudflare
- Apache 2.4 or newer:
- [000-default.conf](http://pastebin.com/j1Ps3ZK6)
- Apache 2.3 or older:
- [000-default](http://pastebin.com/BHQzf2pj)
## Enabling and Disabling Sites
To instruct apache to serve traffic from a virtual host, enable it:
sudo a2ensite NAME
where NAME is the name of the configuration file (eg 000-default.conf)
To disable traffic from a site, disable the virtual host:
sudo a2dissite NAME
where NAME is the name of the configuration file (eg 000-default.conf)

View File

@ -0,0 +1,74 @@
# CentOS Installation
Its recommended to update all packages before proceeding.
`sudo yum update`
`sudo yum upgrade`
`sudo reboot`
Now install all [dependencies](dependencies.md). For this guide you'll need the optional [JDK](dependencies.md) and [Apache](dependencies.md) sections as well.
sudo yum install xxxxxxx
replacing the x's with the list of packages.
For security and permissions, its highly recommended you create a user to install under who is not the root account.
sudo adduser allianceserver
sudo passwd allianceserver
This user needs sudo powers. Add them by editing the sudoers file:
sudo nano /etc/sudoers
Find the line which says `root ALL=(ALL) ALL` - beneath it add another line `allianceserver ALL=(ALL) ALL` - now reboot.
**From this point on you need to be logged in as the allianceserver user**
start your mariadb server `sudo systemctl start mariadb`
secure your MYSQL / Maria-db server by typing `mysql_secure_installation `
AllianceAuth needs a MySQL user account. Create one as follows, replacing `PASSWORD` with an actual secure password:
mysql -u root -p
CREATE USER 'allianceserver'@'localhost' IDENTIFIED BY 'PASSWORD';
GRANT ALL PRIVILEGES ON * . * TO 'allianceserver'@'localhost';
Now we need to make the requisite databases.
create database alliance_auth;
create database alliance_forum;
create database alliance_jabber;
create database alliance_mumble;
create database alliance_killboard;
Ensure you are in the allianceserver home directory by issuing `cd`
Now we clone the source code:
git clone https://github.com/R4stl1n/allianceauth.git
Enter the folder by issuing `cd allianceauth`
Python package dependencies can be installed from the requirements file:
sudo pip install -r requirements.txt
The settings file needs configuring. See this lengthy guide for specifics.
Django needs to install models to the database before it can start.
python manage.py syncdb
AllianceAuth needs to generate corp and alliance models before it can assign users to them.
python manage.py shell < run_alliance_corp_update.py
Now we need to round up all the static files required to render templates. Answer yes when prompted.
python manage.py collectstatic
Test the server by starting it manually.
python manage.py runserver 0.0.0.0:8000
If you see an error, stop, read it, and resolve it. If the server comes up and you can access it at `yourip:8000`, you're golden. It's ok to stop the server if you're going to be installing apache.

View File

@ -0,0 +1,71 @@
# Dependencies
## Ubuntu
Tested on Ubuntu 12, 14, 15, and 16. Package names and repositories may vary.
### Core
Required for base auth site
#### Python
python python-dev python-mysqldb python-setuptools python-mysql.connector python-pip
#### MySQL
mysql-server mysql-client libmysqlclient-dev
#### Utilities
screen unzip git redis-server curl libssl-dev libbz2-dev libffi-dev
### Apache
Required for displaying web content
apache2 libapache2-mod-php5 libapache2-mod-wsgi
### PHP
Required for phpBB, smf, evernus alliance market, etc
php5 php5-gd php5-mysqlnd php5-curl php5-gd php5-intl php-pear php5-imagick php5-imap php5-mcrypt php5-memcache php5-ming php5-ps php5-pspell php5-recode php5-snmp php5-sqlite php5-tidy php5-xmlrpc php5-xsl
### Java
Required for hosting jabber server
oracle-java8-installer
## CentOS 7
### Add The EPEL Repository
yum --enablerepo=extras install epel-release
yum update
### Core
Required for base auth site
#### Python
python python-devel MySQL-python python-setuptools mysql-connector-python python-pip
#### MySQL
mariadb-server mariadb-devel mariadb
#### Utilities
screen gcc unzip git redis curl nano
### Apache
Required for displaying web content
httpd mod_wsgi
### PHP
Required for phpBB, smf, evernus alliance market, etc
php php-gd php-mysqlnd php-intl php-pear ImageMagick php-imap php-mcrypt php-memcache php-pspell php-recode php-snmp php-pdo php-tidy php-xmlrpc
### Java
Required for hosting jabber server
java libstdc++.i686

View File

@ -0,0 +1,12 @@
# Auth
```eval_rst
.. toctree::
dependencies
ubuntu
centos
settings
apache
quickstart
```

View File

@ -0,0 +1,14 @@
# Quick Start
Once youve installed AllianceAuth, perform these steps to get yourself up and running.
First you need a superuser account. You can use this as a personal account. From the command line, `python manage.py createsuperuser` and follow the prompts.
The big goal of AllianceAuth is the automation of group membership, so well need some groups. In the admin interface, select `Groups`, then at the top-right select `Add Group`. Give it a name and select permissions. Special characters (including spaces) are removing before syncing to services, so try not to have group names which will be the same upon cleaning. A description of permissions can be found in the [readme file](https://github.com/R4stl1n/allianceauth/blob/master/README.md). Repeat for all the groups you see fit, whenever you need a new one.
### Background Processes
To start the background processes to sync groups and check api keys, issue these commands:
screen -dm bash -c 'python manage.py celeryd'
screen -dm bash -c 'python manage.py celerybeat'

View File

@ -0,0 +1,400 @@
# Settings Overview
The `alliance_auth/settings.py` file is used to pass settings to the django app needed to run.
### Words of Warning
Certain fields are quite sensitive to leading `http://` and trailing `/` - if you see these present in the default text, be sure to include them in your values.
Every variable value is opened and closed with a single apostrophe `'` - please do not include these in your values or it will break things. If you absolutely must, replace them at the opening and closing of the value with double quotes `"`.
Certain variables are booleans, and come in a form that looks like this:
MEMBER_CORP_GROUPS = 'True' == os.environ.get('AA_MEMBER_CORP_GROUPS', 'True')
They're handled as strings because when settings are exported from shell commands (eg `export AA_MEMBER_CORP_GROUPS False`) they're interpreted as strings, so a string comparison is done.
When changing these booleans, edit the setting within the brackets (eg `('AA_MEMBER_CORP_GROUPS', 'True')` vs `('AA_MEMBER_CORP_GROUPS', 'False')`) and not the `True` earlier in the statement. Otherwise these will have unexpected behaviours.
## Fields to Modify
### Required
- [SECRET_KEY](#secret_key)
- Use [this tool](http://www.miniwebtool.com/django-secret-key-generator/) to generate a key on initial install
- [DEBUG](#debug)
- If issues are encountered, set this to `True` to view a more detailed error report, otherwise set `False`
- [ALLOWED_HOSTS](#allowed_hosts)
- Should include localhost `127.0.0.1` and `yourdomain.com`
- [DATABASES](#databases)
- Fill out the database name and user credentials to manage the auth database.
- [IS_CORP](#is_corp)
- Set to `True` to run in corp mode, or `False` to run in alliance mode
- [DOMAIN](#domain)
- Set to the domain name AllianceAuth will be accessible under
- [EMAIL_HOST_USER](#email_host_user)
- Username to send emails from. If gmail account, the full gmail address.
- [EMAIL_HOST_PASSWORD](#email_host_password)
- Password for the email user.
- [CORP_ID](#corp_id)
- If running in corp mode, set to the corp ID of the owning corp.
- [CORP_NAME](#corp_name)
- If running in corp mode, set to the name of the owning corp.
- [ALLIANCE_ID](#alliance_id)
- If running in alliance mode, set to the alliance ID of the owning alliance.
- [ALLIANCE_NAME](#alliance_name)
- If running in alliance mode, set to the name of the owning alliance.
- [MEMBER_API_MASK](#member_api_mask)
- Set the minimum access mask for member API keys.
- [MEMBER_API_ACCOUNT](#member_api_account)
- Set to `True` to require member API keys be account keys.
- [BLUE_API_MASK](#blue_api_mask)
- Set the minimum access mask for blue API keys.
- [BLUE_API_ACCOUNT](#blue_api_account)
- Set to `True` to require blue API keys be account keys.
## Services
### Member Services
After installing services, enable specific services for members by setting the following to `True`
- [ENABLE_AUTH_FORUM](#enable_auth_forum)
- [ENABLE_AUTH_JABBER](#enable_auth_jabber)
- [ENABLE_AUTH_MUMBLE](#enable_auth_mumble)
- [ENABLE_AUTH_IPBOARD](#enable_auth_ipboard)
- [ENABLE_AUTH_TEAMSPEAK3](#enable_auth_teamspeak3)
- [ENABLE_AUTH_DISCORD](#enable_auth_discord)
- [ENABLE_AUTH_DISCOURSE](#enable_auth_discourse)
- [ENABLE_AUTH_IPS4](#enable_auth_ips4)
- [ENABLE_AUTH_SMF](#enable_auth_smf)
- [ENABLE_AUTH_MARKET](#enable_auth_market)
- [ENABLE_AUTH_XENFORO](#enable_auth_xenforo)
### Blue Services
After installing services, enable specific services for blues by setting the following to `True`
- [ENABLE_BLUE_FORUM](#enable_blue_forum)
- [ENABLE_BLUE_JABBER](#enable_blue_jabber)
- [ENABLE_BLUE_MUMBLE](#enable_blue_mumble)
- [ENABLE_BLUE_IPBOARD](#enable_blue_ipboard)
- [ENABLE_BLUE_TEAMSPEAK3](#enable_blue_teamspeak3)
- [ENABLE_BLUE_DISCORD](#enable_blue_discord)
- [ENABLE_BLUE_DISCOURSE](#enable_blue_discourse)
- [ENABLE_BLUE_IPS4](#enable_blue_ips4)
- [ENABLE_BLUE_SMF](#enable_blue_smf)
- [ENABLE_BLUE_MARKET](#enable_blue_market)
- [ENABLE_BLUE_XENFORO](#enable_blue_xenforo)
### IPBoard
If using IPBoard, the following need to be set
- [IPBOARD_ENDPOINT](#ipboard_endpoint)
- [IPBOARD_APIKEY](#ipboard_apikey)
- [IPBOARD_APIMODULE](#ipboard_apimodule)
### XenForo
If using XenForo, the following need to be set
- [XENFORO_ENDPOINT](#xenforo_endpoint)
- [XENFORO_APIKEY](#xenforo_apikey)
### Openfire
If using Openfire, the following need to be set
- [JABBER_URL](#jabber_url)
- [JABBER_PORT](#jabber_port)
- [JABBER_SERVER](#jabber_server)
- [OPENFIRE_ADDRESS](#openfire_address)
- [OPENFIRE_SECRET_KEY](#openfire_secret_key)
- [BROADCAST_USER](#broadcast_user)
- [BROADCAST_USER_PASSWORD](#broadcast_user_password)
- [BROADCAST_SERVICE_NAME](#broadcast_service_name)
### Mumble
If using Mumble, the following need to be set
- [MUMBLE_URL](#mumble_url)
### PHPBB3
If using phpBB3, the database needs to be defined.
### Teamspeak3
If using Teamspeak3, the following need to be set
- [TEAMSPEAK3_SERVER_IP](#teamspeak3_server_ip)
- [TEAMSPEAK3_SERVER_PORT](#teamspeak3_server_port)
- [TEAMSPEAK3_SERVERQUERY_USER](#teamspeak3_serverquery_user)
- [TEAMSPEAK3_SERVERQUERY_PASSWORD](#teamspeak3_serverquery_password)
- [TEAMSPEAK3_VIRTUAL_SERVER](#teamspeak3_virtual_server)
- [TEAMSPEAK3_PUBLIC_URL](#teamspeak3_public_url)
### Discord
If connecting to a Discord server, set the following
- [DISCORD_SERVER_ID](#discord_server_id)
- [DISCORD_USER_EMAIL](#discord_user_email)
- [DISCORD_USER_PASSWORD](#discord_user_password)
### Discourse
If connecting to Discourse, set the following
- [DISCOURSE_URL](#discourse_url)
- [DISCOURSE_API_USERNAME](#discourse_api_username)
- [DISCOURSE_API_KEY](#discourse_api_key)
### IPSuite4
If using IPSuite4 (aka IPBoard4) the following are required:
- [IPS4_URL](#ips4_url)
- the database needs to be defined
### SMF
If using SMF the following are required:
- [SMF_URL](#smf_url)
- the database needs to be defined
## Optional
### Standings
To allow access to blues, a corp API key is required to pull standings from. Corp does not need to be owning corp or in owning alliance. Required mask is 16 (Communications/ContactList)
- [CORP_API_ID](#corp_api_id)
- [CORP_API_VCODE](#corp_api_vcode)
### Jacknife
To view APIs on a different Jacknife install, set [JACK_KNIFE_URL](#jack_knife_url)
### Auto Groups
Groups can be automatically assigned based on a user's corp or alliance. Set the following to `True` to enable this feature.
- [MEMBER_CORP_GROUPS](#member_corp_groups)
- [MEMBER_ALLIANCE_GROUPS](#member_alliance_groups)
- [BLUE_CORP_GROUPS](#blue_corp_groups)
- [BLUE_ALLIANCE_GROUPS](#blue_alliance_groups)
### Fleet-Up
Fittings and operations can be imported from Fleet-Up. Define the following to do so.
- [FLEETUP_APP_KEY](#fleetup_app_key)
- [FLEETUP_USER_ID](#fleetup_user_id)
- [FLEETUP_API_ID](#fleetup_api_id)
- [FLEETUP_GROUP_ID](#fleetup_group_id)
# Description of Settings
## Django
### SECRET_KEY
A random string used in cryptographic functions, such as password hashing. Changing after installation will render all sessions and password reset tokens invalid.
### DEBUG
Replaces the generic `SERVER ERROR (500)` page when an error is encountered with a page containing a traceback and variables. May expose sensitive information so not recommended for production.
### ALLOWED_HOSTS
A list of addresses used to validate headers: AllianceAuth will block connection coming from any other address unless `DEBUG` is `True`. This should be a list of URLs and IPs to allow. For instance, include 'mydomain.com', 'www.mydomain.com', and the server's IP address to ensure connections will be accepted.
### DATABASES
List of databases available. Contains the Django database, and may include service ones if enabled. Service databases are defined in their individual sections and appended as needed automatically.
### LANGUAGE_CODE
Friendly name of the local language.
### TIME_ZONE
Friendly name of the local timezone.
### STATIC_URL
Absolute URL to serve static files from.
### STATIC_ROOT
Root folder to store static files in.
### SUPERUSER_STATE_BYPASS
Overrides superuser account states to always return True on membership tests. If issues are encountered, or you want to test access to certain portions of the site, set to False to disable.
## ALLIANCE / CORP TOGGLE
### IS_CORP
Used to determine the criteria used for member and blue validation, either requiring membership in the corp or alliance specified later, and being a standing of the corp or alliance specified later.
## EMAIL SETTINGS
### DOMAIN
The URL to which emails will link.
### EMAIL_HOST
The host address of the email server.
### EMAIL_PORT
The host port of the email server.
### EMAIL_HOST_USER
The username to authenticate as on the email server.
### EMAIL_HOST_PASSWORD
The password of the user used to authenticate on the email server.
### EMAIL_USE_TLS
Enable TLS connections to the email server.
## Front Page Links
### KILLBOARD_URL
Link to a killboard.
### EXTERNAL_MEDIA_URL
Link to another media site, eg YouTube channel.
### FORUM_URL
Link to forums. Also used as the phpbb3 URL if enabled.
## SSO Settings
If defined below, a `LOG IN WITH EVE ONLINE` button will be present on the login page. This allows registered users to log in as their characters instead of username/password.
### EVE_SSO_CLIENT_ID
The application cliend ID generated from the [developers site.](https://developers.eveonline.com)
### EVE_SSO_CLIENT_SECRET
The application secret key generated from the [developers site.](https://developers.eveonline.com)
### EVE_SSO_CALLBACK_URL
The callback URL for authentication handshake. Should be `https://mydomain.com/sso/callback`.
## Default Group Settings
### DEFAULT_AUTH_GROUP
Name of the group members of the owning corp or alliance are put in.
### DEFAULT_BLUE_GROUP
Name of the group blues of the owning corp or alliance are put in.
### MEMBER_CORP_GROUPS
If `True`, add members to groups with their corp name, prefixed with `Corp_`
### MEMBER_ALLIANCE_GROUPS
If `True`, add members to groups with their alliance name, prefixed with `Alliance_`
### BLUE_CORP_GROUPS
If `True`, add blues to groups with their corp name, prefixed with `Corp_`
### BLUE_ALLIANCE_GROUPS
If `True`, add blues to groups with their alliance name, prefixed with `Alliance_`
## Alliance Service Setup
### ENABLE_AUTH_FORUM
Allow members of the owning corp or alliance to generate accounts on a Phpbb3 install.
### ENABLE_AUTH_JABBER
Allow members of the owning corp or alliance to generate accounts on an Openfire install.
### ENABLE_AUTH_MUMBLE
Allow members of the owning corp or alliance to generate accounts on a Mumble install.
### ENABLE_AUTH_IPBOARD
Allow members of the owning corp or alliance to generate accounts on an IPBoard install.
### ENABLE_AUTH_TEAMSPEAK3
Allow members of the owning corp or alliance to generate accounts on a Teamspeak3 install.
### ENABLE_AUTH_DISCORD
Allow members of the owning corp or alliance to link accounts to a Discord server.
### ENABLE_AUTH_DISCOURSE
Allow members of the owning corp or alliance to generate accounts on a Discourse install
### ENABLE_AUTH_IPS4
Allow members of the owning corp or alliance to generate accounts on a IPSuite4 install.
### ENABLE_AUTH_SMF
Allow members of the owning corp or alliance to generate accounts on a SMF install.
### ENABLE_AUTH_MARKET
Allow members of the owning corp or alliance to generate accounts on an alliance market install.
### ENABLE_AUTH_XENFORO
Allow members of the owning corp or alliance to generate accounts on a XenForo install.
## Blue Service Setup
### BLUE_STANDING
The lowest standings to consider blue. Default is 5.0
### ENABLE_BLUE_FORUM
Allow blues of the owning corp or alliance to generate accounts on a Phpbb3 install.
### ENABLE_BLUE_JABBER
Allow blues of the owning corp or alliance to generate accounts on an Openfire install.
### ENABLE_BLUE_MUMBLE
Allow blues of the owning corp or alliance to generate accounts on a Mumble install.
### ENABLE_BLUE_IPBOARD
Allow blues of the owning corp or alliance to generate accounts on an IPBoard install.
### ENABLE_BLUE_TEAMSPEAK3
Allow blues of the owning corp or alliance to generate accounts on a Teamspeak3 install.
### ENABLE_BLUE_DISCORD
Allow blues of the owning corp or alliance to link accounts to a Discord server.
### ENABLE_BLUE_DISCOURSE
Allow blues of the owning corp or alliance to generate accounts on a Discourse install.
### ENABLE_BLUE_IPS4
Allow blues of the owning corp or alliance to generate accounts on an IPSuite4 install.
### ENABLE_BLUE_SMF
Allow blues of the owning corp or alliance to generate accounts on a SMF install.
### ENABLE_BLUE_MARKET
Allow blues of the owning corp or alliance to generate accounts on an alliance market install.
### ENABLE_BLUE_XENFORO
Allow blues of the owning corp or alliance to generate accounts on a XenForo install.
## Corp Configuration
### CORP_ID
EVE corp ID of the owning corp, if `IS_CORP` is set to `True`
## CORP_NAME
Name of the owning corp, if `IS_CORP` is set to `True`
## CORP_API_ID
The ID of an API key for a corp from which to pull standings, if desired. Needed for blues to gain access.
## CORP_API_VCODE
The verification code of an API key for a corp from which to pull standings, if desired. Needed for blues to gain access.
## Alliance Configuration
### ALLIANCE_ID
EVE alliance ID of the owning alliance, if `IS_CORP` is set to `False`
### ALLIANCE_NAME
Name of the owning alliance, if `IS_CORP` is set to `False`
## API Configuration
### MEMBER_API_MASK
Required access mask for members' API keys to be considered valid.
### MEMBER_API_ACCOUNT
If `True`, require API keys from members to be account-wide, not character-restricted.
### BLUE_API_MASK
Required access mask for blues' API keys to be considered valid.
### BLUE_API_ACCOUNT
If `True`, require API keys from blues to be account-wide, not character-restricted.
### REJECT_OLD_APIS
Require each submitted API be newer than the latest submitted API. Protects against recycled or stolen API keys.
### REJECT_OLD_APIS_MARGIN
Allows newly submitted APIs to have their ID this value lower than the highest API ID on record and still be accepted. Default is 50, 0 is safest.
## HR Configuration
### JACK_KNIFE_URL
Link to an install of [eve-jackknife](https://code.google.com/archive/p/eve-jackknife/)
## Forum Configuration
### IPBOARD_ENDPOINT
URL to the `index.php` file of a IPBoard install's API server.
### IPBOARD_APIKEY
API key for accessing an IPBoard install's API
### IPBOARD_APIMODULE
Module to access while using the API
## XenForo Configuration
### XENFORO_ENDPOINT
The address of the XenForo API. Should look like `https://mydomain.com/forum/api.php`
### XENFORO_DEFAULT_GROUP
The group ID of the group to assign to member. Default is 0.
### XENFORO_APIKEY
The API key generated from XenForo to allow API access.
## Jabber Configuration
### JABBER_URL
Address to instruct members to connect their jabber clients to, in order to reach an Openfire install. Usually just `mydomain.com`
### JABBER_PORT
Port to instruct members to connect their jabber clients to, in order to reach an Openfire install. Usually 5223.
### JABBER_SERVER
Server name of an Openfire install. Usually `mydomain.com`
### OPENFIRE_ADDRESS
URL of the admin web interface for an Openfire install. Usually `http://mydomain.com:9090`. If HTTPS is desired, change port to 9091: `https://mydomain.com:9091`
### OPENFIRE_SECRET_KEY
Secret key used to authenticate with an Openfire admin interface.
### BROADCAST_USER
Openfire user account used to send broadcasts from. Default is `Broadcast`.
### BROADCAST_USER_PASSWORD
Password to use when authenticating as the `BROADCAST_USER`
### BROADCAST_SERVICE_NAME
Name of the broadcast service running on an Openfire install. Usually `broadcast`
## Mumble Configuration
### MUMBLE_URL
Address to instruct members to connect their Mumble clients to.
## Teamspeak3 Configuration
### TEAMSPEAK3_SERVER_IP
IP of a Teamspeak3 server on which to manage users. Usually `127.0.0.1`
### TEAMSPEAK3_SERVER_PORT
Port on which to connect to a Teamspeak3 server at the `TEAMSPEAK3_SERVER_IP`. Usually `10011`
### TEAMSPEAK3_SERVERQUERY_USER
User account with which to authenticate on a Teamspeak3 server. Usually `serveradmin`.
### TEAMSPEAK3_SERVERQUERY_PASSWORD
Password to use when authenticating as the `TEAMSPEAK3_SERVERQUERY_USER`. Provided during first startup or when you define a custom serverquery user.
### TEAMSPEAK3_VIRTUAL_SERVER
ID of the server on which to manage users. Usually `1`.
### TEAMSPEAK3_PUBLIC_URL
Address to instruct members to connect their Teamspeak3 clients to. Usually `mydomain.com`
## Discord Configuration
### DISCORD_GUILD_ID
The ID of a Discord server on which to manage users.
### DISCORD_BOT_TOKEN
The bot token obtained from defining a bot on the [Discord developers site.](https://discordapp.com/developers/applications/me)
### DISCORD_INVITE_CODE
A no-limit invite code required to add users to the server. Must be generated from the Discord server itself (instant invite).
### DISCORD_APP_ID
The application ID obtained from defining an application on the [Discord developers site.](https://discordapp.com/developers/applications/me)
### DISCORD_APP_SECRET
The application secret key obtained from defining an application on the [Discord developers site.](https://discordapp.com/developers/applications/me)
### DISCORD_CALLBACK_URL
The callback URL used for authenticaiton flow. Should be `https://mydomain.com/discord_callback`. Must match exactly the one used when defining the application.
### DISCORD_SYNC_NAMES
Override usernames on the server to match the user's main character.
## Discourse Configuration
### DISCOURSE_URL
The web address of the Discourse server to direct users to.
### DISCOURSE_API_USERNAME
Username of the account which generated the API key on Discourse.
### DISCOURSE_API_KEY
API key defined on Discourse.
## IPS4 Configuration
### IPS4_URL
URL of the IPSuite4 install to direct users to.
### IPS4_API_KEY
Depreciated.
### IPS4_DB
The database connection to manage users on.
## SMF Configuration
### SMF_URL
URL of the SMF install to direct users to.
### SMF_DB
The database connection to manage users on.
## Fleet-Up Configuration
### FLEETUP_APP_KEY
Application key as [defined on Fleet-Up.](http://fleet-up.com/Api/MyApps)
### FLEETUP_USER_ID
API user ID as [defined on Fleet-Up.](http://fleet-up.com/Api/MyKeys)
### FLEETUP_API_ID
API ID as [defined on Fleet-Up.](http://fleet-up.com/Api/MyKeys)
### FLEETUP_GROUP_ID
The group ID from which to pull data. Can be [retrieved from Fleet-Up](http://fleet-up.com/Api/Endpoints#groups_mygroupmemberships)
## Logging Configuration
This section is used to manage how logging messages are processed.

View File

@ -0,0 +1,72 @@
# Ubuntu Installation
Its recommended to update all packages before proceeding.
sudo apt-get update
sudo apt-get upgrade
sudo reboot
Now install all [dependencies](dependencies.md). For this guide you'll need the optional [Apache section](dependencies.md) as well.
sudo apt-get install xxxxxxx
replacing the xs with the list of packages.
For security and permissions, its highly recommended you create a user to install under who is not the root account.
sudo adduser allianceserver
This user needs sudo powers. Add them by editing the sudoers file:
sudo nano /etc/sudoers
Find the line which says `root ALL=(ALL:ALL) ALL` - beneath it add another line `allianceserver ALL=(ALL:ALL) ALL` - now reboot.
**From this point on you need to be logged in as the allianceserver user**
AllianceAuth needs a MySQL user account. Create one as follows, replacing `PASSWORD` with an actual secure password:
mysql -u root -p
CREATE USER 'allianceserver'@'localhost' IDENTIFIED BY 'PASSWORD';
GRANT ALL PRIVILEGES ON * . * TO 'allianceserver'@'localhost';
Now we need to make the requisite databases.
create database alliance_auth;
create database alliance_forum;
create database alliance_jabber;
create database alliance_mumble;
Ensure you are in the allianceserver home directory by issuing `cd`
Now we clone the source code:
git clone https://github.com/R4stl1n/allianceauth.git
Enter the folder by issuing `cd allianceauth`
Python package dependencies can be installed from the requirements file:
sudo pip install requests>=2.9.1
sudo pip install -r requirements.txt
The settings file needs configuring. See [this lengthy guide](settings.md) for specifics.
Django needs to install models to the database before it can start.
python manage.py migrate
AllianceAuth needs to generate corp and alliance models before it can assign users to them.
python manage.py shell < run_alliance_corp_update.py
Now we need to round up all the static files required to render templates. Answer yes when prompted.
python manage.py collectstatic
Test the server by starting it manually.
python manage.py runserver 0.0.0.0:8000
If you see an error, stop, read it, and resolve it. If the server comes up and you can access it at `yourip:8000`, you're golden. It's ok to stop the server if you're going to be installing apache.
Once installed, follow the [Quick Start Guide](quickstart.md)

View File

@ -0,0 +1,10 @@
# Installation
```eval_rst
.. toctree::
:maxdepth: 2
auth/index
services/index
```

View File

@ -0,0 +1,54 @@
# 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
### Creating a Server
*If you already have a Discord server, skip the creation step, but be sure to retrieve the server ID and enter it in settings.py*
Navigate to the [Discord site](https://discordapp.com/) and register an account, or log in if you have one already.
On the left side of the screen youll 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 youre on. The ID is the first of the very long numbers. For instance my testing servers url look like:
https://discordapp.com/channels/120631096835571712/120631096835571712
with a server ID of `120631096835571712`
Update settings.py, inputting the server ID as `DISCORD_GUILD_ID`
### Generating an Invite
Still on the Discord site, in your new server, an invite needs to be generated for users to join. If you with for users to initially join a different channel than `#general`, create it and follow the steps below, substituting this channel for `#general`.
On the left bar under the Text Channels heading, hover over `#general` on the right site. There are two icons, a box with an arrow and a gear. Press the box, then on the bottom left select Advanced Settings. Set the expiration to never, and no limit on uses. Press generate.
This returns a code that looks like `https://discord.gg/0fmA8MyXV6qt7XAZ`. The part after the last slash, `0fmA8MyXV6qt7XAZ`, is the invite code. Update settings.py, inputting this invite code as `DISCORD_INVITE_CODE`
### Registering an Application
Navigate to the [Discord Developers site.](https://discordapp.com/developers/applications/me) Press the plus sign to create a new application.
Give it a name and description relating to your auth site. Add a redirect to `https://mydomain.com/discord_callback`, substituting your domain. Press Create Application.
Update settings.py, inputting this redirect address as `DISCORD_CALLBACK_URL`
On the application summary page, press Create a Bot User.
Update settings.py 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
### 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](https://support.discordapp.com/hc/en-us/articles/219576828). 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.
## Managing Roles
Once users link their accounts youll 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.

View File

@ -0,0 +1,122 @@
# Discourse
## 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.](https://github.com/discourse/discourse/blob/master/docs/INSTALL-email.md#recommended-email-providers-for-discourse)
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
## Apache config
Discourse must run on its own subdomain - it can't handle routing behind an alias like '/forums'. To do so, make a new apache config:
sudo nano /etc/apache2/sites-available/discourse.conf
And enter the following, changing the port if you used a different number:
<VirtualHost *:80>
ServerName discourse.mydomain.com
ProxyPass / http://0.0.0.0:7890/
ProxyPassReverse / http://0.0.0.0:7890/
</VirtualHost>
Now enable proxies and restart apache:
sudo a2enmod proxy_http
sudo service apache2 reload
## 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.mydomain.com` and log on. Top right press the 3 lines and select `Admin`. Go to API tab and press `Generate Master API Key`.
Now go to the allianceauth folder and edit settings:
nano /home/allianceserver/allianceauth/alliance_auth/settings.py
Scroll down to the Discourse section and set the following:
- `DISCOURSE_URL`: `discourse.mydomain.com`
- `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.mydomain.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://mydomain.com/discourse_sso`
- `sso_secret`: some secure key
Save, now change settings.py and add the following:
- `DISCOURSE_SSO_SECRET`: the secure key you just set
### Enable for your members
Set either or both of `ENABLE_AUTH_DISCOURSE` and `ENABLE_BLUE_DISCOURSE` in settings.py for your members to gain access. Save and exit with control+o, enter, control+x.
## Done

View File

@ -0,0 +1,17 @@
# Services
```eval_rst
.. toctree::
market
discord
discourse
ipboard3
mumble
openfire
phpbb3
smf
teamspeak3
xenforo
```

View File

@ -0,0 +1,44 @@
# IPBoard3
Yes, you read that right. AllianceAuth only supports IPBoard 3, not the new shiny 4. Why? Because InvisionPower removed the API we used to manage it.
Moving right along.
Youre on your own for the initial install of IPBoard. Its pretty much just download, unzip, and move to `/var/www/ipboard/`. Make sure to
sudo chown -R www-data:www-data /var/www/ipboard
a few times because its pretty finicky.
Youll need to add another alias in your [apache config](https://github.com/R4stl1n/allianceauth/wiki/Apache-Setup#additional-parameters-for-full-setup), this one for `/ipboard/` pointing to `/var/www/ipboard` and add another `<directory>` block for `/var/www/ipboard` with `Require all granted` or `Allow from all` depending on your apache version.
IPBoard needs a database table. Log in to mysql and run:
create database alliance_ipboard;
Thats all for SQL work. Control+D to close.
Navigate to http://yourdomain.com/ipboard and proceed with the install. If it whines about permissions make sure to `chown` again. Point it at that database we just made, using the `allianceserver` MySQL user account from the full install.
Once you get everything installed we need to copy the api module folder
sudo cp -a /home/allianceserver/allianceauth/thirdparty/IPBoard3/aa /var/www/ipboard/interface/board/modules/aa
and again run that `chown` command.
Log into the AdminCP for IPBoard and find your way to the `System` tab. On the left navigation bar, under `Tools and Settings`, select `API Users`.
Enable the API by toggling the `XML-RPC Status` from `disabled` to `enabled` (red box, top right of the page) and save. Now create a new api user. Put something descriptive for title such as AllianceAuth, then on the bottom panel click the `AllianceAuth` tab and tick all the boxes. Press `Create New API User` to save it.
Copy the API key. Now edit your settings.py as follows:
- IPBOARD_APIKEY is the key you just copied
- IPBOARD_ENDPOINT is `http://yourdomain.com/ipboard/interface/board/index.php`
Now enable IPBoard for Auth and/or Blue by editing the [booleans](#alliance-service-setup).
Save and exit. Restart apache or gunicorn.
Test it by creating a user through AllianceAuth. Just note right now theres no real error handling, so if account creation fails itll still return a username/password combo.
Good luck!

View File

@ -0,0 +1,104 @@
# Alliance Market
Alliance Market needs a database. Create one in mysql. Default name is `alliance_market`:
mysql -u root -p
create database alliance_market;
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 mkdir evernus-alliance-market/app/cache
sudo mkdir evernus-alliance-market/app/logs
sudo chmod -R 777 evernus-alliance-market/app/cache
sudo chmod -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
Install composer [as per these instructions.](https://getcomposer.org/download/)
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
Edit your apache config. Add the following:
Alias /market /var/www/evernus-alliance-market/web/
<Directory "/var/www/evernus-alliance-market/web/">
DirectoryIndex app.php
Require all granted
AllowOverride all
</Directory>
Enable rewriting
sudo a2enmod rewrite
Restart apache
sudo service apache2 reload
Once again, set cache permissions:
sudo chown -R www-data:www-data app/
Add a user account through auth, then make it a superuser:
sudo php app/console fos:user:promote your_username --super

View File

@ -0,0 +1,81 @@
# Mumble
## 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
## Configuring Mumble
Mumble ships with a configuration file that needs customization. By default its 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
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 users password
- `dbPort=3306`
- `dbPrefix=murmur_`
To name your root channel, uncomment and edit `registerName=` 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 youll remember and write it down. This is needed to manage ACLs.
Now restart the server to see the changes reflected.
sudo service mumble-server restart
Thats it! Your server is ready to be connected to at yourdomain.com:64738
## Configuring the Authenticator
The ICE authenticator lives in `allianceauth/thirdparty/Mumble/`, cd to this directory.
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. The best way is to run it in a screen much like celery:
screen -dm bash -c 'python authenticator.py'
Much like celery tasks, this process needs to be started every time the server reboots. It needs to be launched from this directory, so cd to this folder to launch.
Note that groups will only be created on Mumble automatically when a user joins who is in the group.
## 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.
## Setup Complete
Youve finished the steps required to make AllianceAuth work with Mumble. Play around with it and make it your own.

View File

@ -0,0 +1,99 @@
# Openfire
## Overview
Openfire is a java-based xmpp server (jabber).
## Dependencies
One additional package is required - [openjdk8](http://askubuntu.com/questions/464755/how-to-install-openjdk-8-on-14-04-lts)
sudo add-apt-repository ppa:webupd8team/java -y
sudo apt-get update
sudo apt-get install oracle-java8-installer
## 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](https://www.igniterealtime.org/downloads/index.jsp), and under Openfire select Linux, click on the debian file (2nd in list, ends with .deb).
Retrieve the file location by copying the url from the “click here” link.
In the console, ensure youre in your users 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_3.10.2_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)
sudo dpkg -i openfire_3.10.2_all.deb
### Web Configuration
The remainder of the setup occurs through Openfires web interface. Navigate to http://yourdomain.com:9090, or if youre behind CloudFlare, go straight to your servers IP:9090.
Select your language. I sure hope its english if youre reading this guide.
Under Server Settings, set the Domain to `yourdomain.com` replacing it with your actual domain. Dont 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 MySQL username you created for AllianceAuth, usually `allianceserver`
- enter the MySQL password for this 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 dont lost this login information.
Finally, log in to the console with your admin account.
### REST API Setup
Navigate to the `plugins` tab, and then `Available Plugins` on the left navigation bar. Youll 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`.
Select `Enabled`, and `Secret Key Auth`. Enter the secret key from OPENFIRE_SECRET_KEY here.
### Broadcast Plugin Setup
Navigate to the `Users/Groups` tab and select `Create New User` from the left navigation bar.
Username is what you set in `BROADCAST_USER` without the @ sign, usually `broadcast`.
Password is what you set in `BROADCAST_USER_PASSWORD`
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@yourdomain.com`, replacing the domain name with yours
- Do not encrypt this property value
### 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 rooms name users will connect to
- Room Name is the full name for the room
- Description is short text describing the rooms 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. Youll usually only be assigning groups to the `Member` category.
## Setup Complete
Youve finished the steps required to make AllianceAuth work with Openfire. Play around with it and make it your own.

View File

@ -0,0 +1,69 @@
# phpBB3
## Overview
phpBB is a free php-based forum. Its the default forum for AllianceAuth.
## Dependencies
All dependencies should have been taken care of during setup.
## Setup
### Download Phpbb3
phpBB is available as a zip from their website. Navigate to the websites [downloads section](https://www.phpbb.com/downloads/) using your PC browser and copy the URL for the latest version zip.
In the console, navigate to your users home directory: `cd ~`
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.1.6.zip
This needs to be unpackaged. Unzip it, replacing the file name with that of the file you just downloaded
unzip phpBB-3.1.6.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
### Web Install
Navigate to http://yourdomain.com/forums 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 MySQL user for AllianceAuth, usually `allianceserver`
- Database Password is this users password
You should see `Succesful Connection` and proceed.
Enter administrator credentials on the next page.
Everything from hereon out 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`.
[Screenshot of this page](http://imgur.com/UOgaq6J)
You can allow members to overwrite the portrait with a custom image if desired. Navigate to `Users and Groups`, `Group Permissions`, select the appropriate group (usually `Member` if you want everyone to have this ability), expand `Advanced Permissions`, under the `Profile` tab, set `Can Change Avatars` to `Yes`, and press `Apply Permissions`.
[Screenshot of this page](http://i.imgur.com/VGHwdxM.png)
## Setup Complete
Youve finished the steps required to make AllianceAuth work with phpBB. Play around with it and make it your own.

View File

@ -0,0 +1,50 @@
# SMF
## Overview
SMF is a free php-based forum. Its the one of the forums for AllianceAuth.
## Dependencies
All dependencies should have been taken care of during setup.
## 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/.
In the console, navigate to your users home directory: `cd ~`
Now 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-11_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-11_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
### Web Install
Navigate to http://yourdomain.com/forums 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 MySQL user for AllianceAuth, usually `allianceserver`
- Database Password is this users password
Follow the Directions in the installer.
## Setup Complete
Youve finished the steps required to make AllianceAuth work with SMF. Play around with it and make it your own.

View File

@ -0,0 +1,70 @@
# Teamspeak 3
## Overview
Teamspeak3 is the most popular VOIP program for gamers.
## Dependencies
All dependencies should have been taken care of during the AllianceAuth install.
## Setup
### Download Installer
To install we need a copy of the server. You can find the latest version from [this dl server](http://dl.4players.de/ts/releases/) (Id recommed getting the latest stable version find this version number from the [TeamSpeak site](https://www.teamspeak.com/downloads#)). Be sure to get a link to the linux version.
From the console, ensure youre in the users home directory: `cd ~`
And now download the server, replacing the link with the link you got earlier.
wget http://dl.4players.de/ts/releases/3.0.11.4/teamspeak3-server_linux-amd64-3.0.11.4.tar.gz
Now we need to extract the file.
tar -xvf teamspeak3-server_linux-amd64-3.0.11.4.tar.gz
### 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
### Update Settings
The console will spit out a block of text. **SAVE THIS**.
Update the AllianceAuth settings file with the following:
- TEAMSPEAK3_SERVERQUERY_USER is `loginname`
- TEAMSPEAK3_SERVERQUERY_PASSWORD is `password`
Save and reload apache.
sudo service apache2 reload
### 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 (yourdomain.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.
## Setup Complete

View File

@ -0,0 +1,31 @@
# XenForo
In this chapter we will explore how to setup AllianceAuth to work with [XenForo](https://xenforo.com/). At this point we will assume that you already have XenForo installed with a valid license (please keep in mind that XenForo is not free nor open-source, therefore you need to purchase a license first). If you come across any problems related with the installation of XenForo please contact their support service.
## XenAPI
By default XenForo does not support any kind of API, however there is a third-party package called [XenAPI](https://github.com/Contex/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.
```php
$restAPI = new RestAPI('REPLACE_THIS_WITH_AN_API_KEY');
```
## Configuration
AllianceAuth only needs to know 3 things about XenForo.
+ The API Endpoint
+ The API Key
+ The default group
The first two should be self explanatory. The default group is where AllianceAuth will add the user once his account is created. Unfortunately XenAPI **cannot create new groups**, therefore you have to create a group manually and then get its ID.
When you have a forum section which should be accessible ONLY by the auth'd users the access settings must be set to the default group.
In the future we will have different groups for blues and alliance/corp members.

View File

@ -0,0 +1,297 @@
# Changelog
## From now on all changelogs will be included as release notes.
https://github.com/R4stl1n/allianceauth/releases
### 547
Oct 16
Golly this is a big one. Upgrading takes a bit of work. [For full instructions click here.](https://github.com/R4stl1n/allianceauth/pull/547#issue-183247630)
- 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:
- `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
### 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 [wiki page](https://github.com/R4stl1n/allianceauth/wiki/HRApplications) 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
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.](../installation/services/mumble.md)
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.
### 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
### 245
Feb 7 2016
- ability to toggle assigning corp groups
- users able to manually trigger api refresh
Two new settings in [settings.py](../installation/auth/settings.md) - `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
- 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.
### 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 Adarnofs and Kaezons 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.

View File

@ -0,0 +1,41 @@
# CloudFlare
CloudFlare offers free SSL and DDOS mitigation services. Why not take advantage of it?
## Setup Protection
Youll need to register an account on [CloudFlares site.](https://www.cloudflare.com/)
Along the top bar, select `Add Site`
Enter your domain name. It will scan records and let you know you can add the site. Continue setup.
On the next page you should see an A record for yourdomain.com pointing at your server IP. If not, manually add one:
A yourdomain.com my.server.ip.address Automatic TTL
Add the record and ensure the cloud under Status is orange. If not, click it. This ensures traffic gets screened by CloudFlare.
If you want forums or kb on a subdomain, and want these to be protected by CloudFlare, add an additional record for for each subdomain in the following format, ensuring the cloud is orange:
CNAME subdomain yourdomain.com Automatic TTL
CloudFlare blocks ports outside 80 and 443 on hosts it protects. This means, if the cloud is orange, only web traffic will get through. We need to reconfigure AllianceAuth to provide services under a subdomain. Configure these subdomains as above, but ensure the cloud is not orange (arrow should go around a grey cloud).
## Redirect to HTTPS
Now we need to configure the https redirect to force all traffic to https. Along the top bar of CloudFlare, select `Page Rules`. Add a new rule, Pattern is yourdomain.com, toggle the `Always use https` to ON, and save. Itll take a few minutes to propagate.
![infographic](http://i.stack.imgur.com/VUBvo.jpg)
## Update Auth URLs
Edit settings.py and change the following values:
- FORUM_URL = `os.environ.get('AA_FORUM_URL', "http://forums.mydomain.com")` if forums are on a subdomain
- IPBOARD_ENDPOINT = `os.environ.get('AA_IPBOARD_ENDPOINT', 'http://forums.mydomain.com/ipboard/interface/board/index.php')` if forums are on a subdomain
- JABBER_URL = `os.environ.get('AA_JABBER_URL', "jabber.yourdomain.com")`
- OPENFIRE_ADDRESS = `os.environ.get('AA_OPENFIRE_ADDRESS', "http://jabber.yourdomain.com:9090")`
- MUMBLE_URL = `os.environ.get('AA_MUMBLE_URL', "mumble.yourdomain.com")`
- TEAMSPEAK3_PUBLIC_URL = `os.environ.get('AA_TEAMSPEAK3_PUBLIC_URL', 'ts.yourdomain.com')`
And there we have it. Youre DDOS-protected with free SSL.

11
docs/maintenance/index.md Normal file
View File

@ -0,0 +1,11 @@
# Maintenance
```eval_rst
.. toctree::
:maxdepth: 1
changelog
troubleshooting
cloudflare
```

View File

@ -0,0 +1,50 @@
# Troubleshooting
## Something broken? Stuck on an issue? Can't get it set up?
Start here:
- read the [documentation](https://github.com/R4stl1n/allianceauth/wiki)
- check the [issues](https://github.com/R4stl1n/allianceauth/issues?utf8=%E2%9C%93&q=is%3Aissue) - especially closed ones
- check the [forums](https://forums.eveonline.com/default.aspx?g=posts&t=383030)
No answer?
- open an [issue](https://github.com/R4stl1n/allianceauth/issues)
- harass us on [gitter](https://gitter.im/R4stl1n/allianceauth)
- post to the [forums](https://forums.eveonline.com/default.aspx?g=posts&t=383030)
## Common Problems
### `pip install -r requirements.txt` is failing
Most commonly, your repositories did not include the `requests` package. Install it and try again: `sudo pip install requests`
Otherwise it's usually a missing dependency. Check [the list](../installation/auth/dependencies.md), reinstall, and try again.
### I'm getting an error 500 trying to connect to the website on a new install
Read the apache error log: `sudo nano /var/log/apache2/error.log`
If it talks about failing to import something, google its name and install it.
If it whines about being unable to configure logger, make sure the log directory is write-able: `chmod -R 777 /home/allianceserver/allianceauth/log`, then reload apache.
### 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](../installation/auth/quickstart.md) 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:
sudo rabbitmqctl stop_app
sudo rabbitmqctl reset
sudo rabbitmqctl start_app
python manage.py celeryd --purge
Press control+C once.
python manage.py celeryd --discard
Press control+C once.
Now start celery again with [these background process commands.](../installation/auth/quickstart.md)
While debugging, it is useful to see if tasks are being executed. The easiest tool is [flower](http://flower.readthedocs.io/). 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.

36
docs/make.bat Normal file
View File

@ -0,0 +1,36 @@
@ECHO OFF
pushd %~dp0
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set SOURCEDIR=.
set BUILDDIR=_build
set SPHINXPROJ=AllianceAuth
if "%1" == "" goto help
%SPHINXBUILD% >NUL 2>NUL
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
goto end
:help
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
:end
popd

3
docs/requirements.txt Normal file
View File

@ -0,0 +1,3 @@
sphinx>=1.4.0,<1.5.0
sphinx_rtd_theme>=0.1.9
recommonmark==0.4.0