Mathis/allianceauth
1
0
Fork 0
mirror of https://gitlab.com/allianceauth/allianceauth.git synced 2025-07-14 23:10:15 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update install docs to reflect new magical commands.

Browse Source
This commit is contained in:
Adarnof 2017-10-05 03:10:27 -04:00
parent 03447abf5c
commit d43b8cf0e5
10 changed files with 181 additions and 249 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
allianceauth/project_template/project_name/settings/base.py
View File

@ -150,7 +150,6 @@ USE_TZ = True
# https://docs.djangoproject.com/en/1.10/howto/static-files/
STATIC_URL = '/static/'
STATIC_ROOT = os.path.join(BASE_DIR, "static")
# Bootstrap messaging css workaround
MESSAGE_TAGS = {

32
allianceauth/project_template/project_name/settings/local.py
View File

@ -6,6 +6,7 @@ WSGI_APPLICATION = '{{ project_name }}.wsgi.application'
STATICFILES_DIRS = [
os.path.join(PROJECT_DIR, 'static'),
]
STATIC_ROOT = "/var/www/{{ project_name }}/static/"
TEMPLATES[0]['DIRS'] += [os.path.join(PROJECT_DIR, 'templates')]
SECRET_KEY = '{{ secret_key }}'
@ -15,6 +16,23 @@ SITE_NAME = '{{ project_name }}'
# Change this to enable/disable debug mode
DEBUG = False
#######################################
# Database Settings #
#######################################
# Uncomment and change the database name
# and credentials to use MySQL/MariaDB.
# Leave commented to use sqlite3
#######################################
"""
DATABASES['default'] = {
'ENGINE': 'django.db.backends.mysql',
'NAME': 'alliance_auth',
'USER': os.environ.get('AA_DB_DEFAULT_USER', ''),
'PASSWORD': os.environ.get('AA_DB_DEFAULT_PASSWORD', ''),
'HOST': os.environ.get('AA_DB_DEFAULT_HOST', '127.0.0.1'),
'PORT': os.environ.get('AA_DB_DEFAULT_PORT', '3306'),
}
"""
######################################
# SSO Settings #
@ -30,6 +48,20 @@ ESI_SSO_CLIENT_ID = ''
ESI_SSO_CLIENT_SECRET = ''
ESI_SSO_CALLBACK_URL = ''
######################################
# Email Settings #
######################################
# Alliance Auth validates emails before
# new users can log in.
# It's recommended to use a free service
# like SparkPost or Mailgun to send email.
# https://www.sparkpost.com/docs/integrations/django/
#################
EMAIL_HOST = ''
EMAIL_PORT = 587
EMAIL_HOST_USER = ''
EMAIL_HOST_PASSWORD = ''
EMAIL_USE_TLS = True
######################################
# Add any custom settings below here #

BIN
docs/_static/images/installation/auth/cloudflare/page_rules.jpg vendored
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 142 KiB

147
docs/installation/auth/allianceauth.md Normal file
View File

@ -0,0 +1,147 @@
# Alliance Auth Installation
```eval_rst
.. important::
Installation is easiest as the root user. Log in as root or a user with sudo powers.
```
## Dependencies
```eval_rst
.. hint::
CentOS: A few packages are included in a non-default repository. Add it and update the package lists. ::
yum -y install https://centos7.iuscommunity.org/ius-release.rpm
yum update
```
### Python
Alliance Auth requires python3.4 or higher. Ensure it is installed on your server before proceeding.
Ubuntu:
apt-get install python3 python3-dev python3-setuptools python3-pip
CentOS:
yum install python36u python36u-devel python36u-setuptools python36u-pip bzip2-devel
### Database
It's recommended to use a database service instead of sqlite. Many options are available, but this guide will use MariaDB. Ensure it's installed on your server before proceeding. It can be installed with:
Ubuntu:
apt-get install mariadb-server mysql-client libmysqlclient-dev
CentOS:
yum install mariadb-server mariadb-devel mariadb
### Redis and Other Tools
A few extra utilities are also required for installation of packages.
Ubuntu:
apt-get install unzip git redis-server curl libssl-dev libbz2-dev libffi-dev
CentOS:
yum install gcc gcc-c++ unzip git redis curl
```eval_rst
.. important::
CentOS: Make sure redis is running before continuing: ::
systemctl enable redis.service
systemctl start redis.service
```
## Database Setup
Alliance Auth needs a MySQL user account and database. Create one as follows, replacing `PASSWORD` with an actual secure password:
mysql -u root -p
CREATE USER 'allianceserver'@'localhost' IDENTIFIED BY 'PASSWORD';
CREATE DATABASE alliance_auth;
GRANT ALL PRIVILEGES ON alliance_auth . * TO 'allianceserver'@'localhost';
Secure your MySQL / MariaDB server by typing `mysql_secure_installation`
## Auth Install
### User Account
For security and permissions, it’s highly recommended you create a separate user to install under.
Ubuntu:
adduser --disabled-login allianceserver
CentOS:
useradd -s /bin/nologin allianceserver
### Virtual Environment
Create a Python virtual environment and put it somewhere convenient (e.g. `/home/allianceserver/venv/auth/`)
python3 -m venv /home/allianceserver/venv/auth/
```eval_rst
.. tip::
A virtual environment provides support for creating a lightweight "copy" of Python with their own site directories. Each virtual environment has its own Python binary (allowing creation of environments with various Python versions) and can have its own independent set of installed Python packages in its site directories. You can read more about virtual environments on the Python_ docs.
.. _Python: https://docs.python.org/3/library/venv.html
```
Activate the virtualenv using `source /home/allianceserver/venv/auth/bin/activate`. Note the `/bin/activate` on the end of the path.
```eval_rst
.. hint::
Each time you come to do maintenance on your Alliance Auth installation, you should activate your virtual environment first. When finished, deactivate it with the 'deactivate' command.
```
### Alliance Auth Project
Now you can install the library using `pip install allianceauth`. This will install Alliance Auth and all its python dependencies.
Now you need to create the application that will run the Alliance Auth install. Ensure you are in the allianceserver home directory by issuing `cd /home/allianceserver`.
Issue `allianceauth start myauth` to bootstrap the Django application that will run Alliance Auth. You can rename it from `myauth` to anything you'd like: this name is shown by default as the site name but that can be changed later.
The settings file needs configuring. Edit the template at `myauth/myauth/settings/local.py`. Be sure to configure the EVE SSO and Email settings.
Django needs to install models to the database before it can start.
python /home/allianceserver/myauth/manage.py migrate
Now we need to round up all the static files required to render templates. Make a directory to serve them from and populate it.
mkdir /var/www/myauth/static
python /home/allianceserver/myauth/manage.py collectstatic
chown -R www-data:www-data /var/www/myauth/static
Check to ensure your settings are valid.
python /home/allianceserver/myauth/manage.py check
And finally ensure the allianceserver user has read/write permissions to this directory before proceeding.
chown -R allianceserver:allianceserver /home/allianceserver/myauth
## Superuser
Before proceeding it is essential to create a superuser account. This account will have all permissions in Alliance Auth. It's OK to use this as your personal auth account.
python /home/allianceserver/myauth/manage.py createsuperuser
```eval_rst
.. important::
Be sure to add a main character to this account before attempting to activate services with it.
```
## Webserver
Once installed, move onto the [Gunicorn Guide](gunicorn.md) and decide on whether you're going to use [NGINX](nginx.md) or [Apache](apache.md). You will also need to install [supervisor](supervisor.md) to run the background tasks.

80
docs/installation/auth/centos.md
View File

@ -1,80 +0,0 @@
# CentOS Installation
It's recommended to update all packages before proceeding.
`sudo yum update`
`sudo yum upgrade`
`sudo reboot`
Now install all [dependencies](dependencies.md).
sudo yum install xxxxxxx
replacing the x's with the list of packages.
Make sure redis is running before continuing:
systemctl enable redis.service
systemctl start redis.service
For security and permissions, it's highly recommended you create a user to install under who is not the root account.
sudo adduser allianceserver
sudo passwd allianceserver
This user needs sudo powers. Add them by editing the sudoers file:
sudo nano /etc/sudoers
Find the line which says `root ALL=(ALL) ALL` - beneath it add another line `allianceserver ALL=(ALL) ALL` - now reboot.
**From this point on you need to be logged in as the allianceserver user**
Start your mariadb server `sudo systemctl start mariadb`
Secure your MYSQL / Maria-db server by typing `mysql_secure_installation `
AllianceAuth needs a MySQL user account. Create one as follows, replacing `PASSWORD` with an actual secure password:
mysql -u root -p
CREATE USER 'allianceserver'@'localhost' IDENTIFIED BY 'PASSWORD';
GRANT ALL PRIVILEGES ON * . * TO 'allianceserver'@'localhost';
Now we need to make the requisite database.
create database alliance_auth;
Create a Python virtual environment and put it somewhere convenient (e.g. `~/venv/aauth/`)
python3.6 -m venv /path/to/new/virtual/environment
A virtual environment provides support for creating a lightweight "copy" of Python with their own site directories. Each virtual environment has its own Python binary (allowing creation of environments with various Python versions) and can have its own independent set of installed Python packages in its site directories. You can read more about virtual environments on the [Python docs](https://docs.python.org/3/library/venv.html).
Activate the virtualenv using `source /path/to/new/virtual/environment/bin/activate`. Note the `/bin/activate` on the end of the path. Each time you come to do maintenance on your Alliance Auth installation, you should activate your virtual environment first.
Now you can install the library using `pip install allianceauth`. This will install Alliance Auth and all its python dependencies.
Ensure you are in the allianceserver home directory by issuing `cd ~`.
Now you need to create the application that will run the Alliance Auth install.
Issue `django-admin startproject myauth` to bootstrap the Django application that will run Auth. You can rename it from `myauth` anything you'd like, the name is not important for auth.
Grab the example settings file from the [Alliance Auth repository](https://github.com/allianceauth/allianceauth/blob/master/alliance_auth/settings.py.example) for the relevant version you're installing.
The settings file needs configuring. See [this lengthy guide](settings.md) for specifics.
Django needs to install models to the database before it can start.
python manage.py migrate
Now we need to round up all the static files required to render templates. Answer ‘yes’ when prompted.
python manage.py collectstatic
Test the server by starting it manually.
python manage.py runserver 0.0.0.0:8000
If you see an error, stop, read it, and resolve it. If the server comes up and you can access it at `yourip:8000`, you're golden. It's ok to stop the server if you're going to be installing a WSGI server to run it. **Do not use runserver in production!**
Once installed, move onto the [Gunicorn Guide](gunicorn.md) and decide on whether you're going to use [NGINX](nginx.md) or [Apache](apache.md). You will also need to install [supervisor](supervisor.md) to run the background tasks.

35
docs/installation/auth/cloudflare.md
View File

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

44
docs/installation/auth/dependencies.md
View File

@ -1,44 +0,0 @@
# Dependencies
## Ubuntu
Tested on Ubuntu 14.04LTS, 16.04LTS and 17.04. Package names and repositories may vary. Please note that 14.04LTS comes with Python 3.4 which may be insufficient.
### Core
Required for base auth site
#### Python
python3 python3-dev python3-setuptools python3-pip
#### MySQL
mariadb-server mysql-client libmysqlclient-dev
#### Utilities
unzip git redis-server curl libssl-dev libbz2-dev libffi-dev
## CentOS 7
Tested on CentOS 7
### Add The IUS Repository
sudo yum -y install https://centos7.iuscommunity.org/ius-release.rpm
yum update
### Core
Required for base auth site
#### Python
python36u python36u-devel python36u-setuptools python36u-pip bzip2-devel
#### MySQL
mariadb-server mariadb-devel mariadb
#### Utilities
gcc gcc-c++ unzip git redis curl nano

9
docs/installation/auth/index.md
View File

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

11
docs/installation/auth/quickstart.md
View File

@ -1,11 +0,0 @@
# Quick Start
Once you’ve installed AllianceAuth, perform these steps to get yourself up and running.
First you need a superuser account. You can use this as a personal account. From the command line, `python manage.py createsuperuser` and follow the prompts.
The big goal of AllianceAuth is the automation of group membership, so we’ll need some groups. In the admin interface, select `Groups`, then at the top-right select `Add Group`. Give it a name and select permissions. Special characters (including spaces) are removing before syncing to services, so try not to have group names which will be the same upon cleaning. Repeat for all the groups you see fit, whenever you need a new one. Check the [groups documentation](../../features/groups.md) for more details on group configuration.
### Background Processes
To start the background processes you should utilise [supervisor](supervisor.md). Previously screen was suggested to keep these tasks running, however this is no longer the preferred method.

71
docs/installation/auth/ubuntu.md
View File

@ -1,71 +0,0 @@
# Ubuntu Installation
It’s recommended to update all packages before proceeding.
sudo apt-get update
sudo apt-get upgrade
sudo reboot
Now install all [dependencies](dependencies.md).
sudo apt-get install xxxxxxx
replacing the xs with the list of packages.
For security and permissions, it’s highly recommended you create a user to install under who is not the root account.
sudo adduser allianceserver
This user needs sudo powers. Add them by editing the sudoers file:
sudo nano /etc/sudoers
Find the line which says `root ALL=(ALL:ALL) ALL` - beneath it add another line `allianceserver ALL=(ALL:ALL) ALL` - now reboot.
**From this point on you need to be logged in as the allianceserver user**
AllianceAuth needs a MySQL user account. Create one as follows, replacing `PASSWORD` with an actual secure password:
mysql -u root -p
CREATE USER 'allianceserver'@'localhost' IDENTIFIED BY 'PASSWORD';
GRANT ALL PRIVILEGES ON * . * TO 'allianceserver'@'localhost';
Now we need to make the requisite database.
create database alliance_auth;
Create a Python virtual environment and put it somewhere convenient (e.g. `~/venv/aauth/`)
python3 -m venv /path/to/new/virtual/environment
A virtual environment provides support for creating a lightweight "copy" of Python with their own site directories. Each virtual environment has its own Python binary (allowing creation of environments with various Python versions) and can have its own independent set of installed Python packages in its site directories. You can read more about virtual environments on the [Python docs](https://docs.python.org/3/library/venv.html).
Activate the virtualenv using `source /path/to/new/virtual/environment/bin/activate`. Note the `/bin/activate` on the end of the path. Each time you come to do maintenance on your Alliance Auth installation, you should activate your virtual environment first.
Now you can install the library using `pip install allianceauth`. This will install Alliance Auth and all its python dependencies.
Ensure you are in the allianceserver home directory by issuing `cd ~`.
Now you need to create the application that will run the Alliance Auth install.
Issue `django-admin startproject myauth` to bootstrap the Django application that will run Auth. You can rename it from `myauth` anything you'd like, the name is not important for auth.
Grab the example settings file from the [Alliance Auth repository](https://github.com/allianceauth/allianceauth/blob/master/alliance_auth/settings.py.example) for the relevant version you're installing.
The settings file needs configuring. See [this lengthy guide](settings.md) for specifics.
Django needs to install models to the database before it can start.
python manage.py migrate
Now we need to round up all the static files required to render templates. Answer ‘yes’ when prompted.
python manage.py collectstatic
Test the server by starting it manually.
python manage.py runserver 0.0.0.0:8000
If you see an error, stop, read it, and resolve it. If the server comes up and you can access it at `yourip:8000`, you're golden. It's ok to stop the server if you're going to be installing a WSGI server to run it. **Do not use runserver in production!**
Once installed, move onto the [Gunicorn Guide](gunicorn.md) and decide on whether you're going to use [NGINX](nginx.md) or [Apache](apache.md). You will also need to install [supervisor](supervisor.md) to run the background tasks.