Mathis/allianceauth
1
0
Fork 0
mirror of https://gitlab.com/allianceauth/allianceauth.git synced 2026-02-06 07:06:19 +01:00
Code Issues Packages Projects Releases Wiki Activity

Minor Documentation Update (#1019)

Browse Source 
Gunicorn needs to be run whilist in the folder for context, folder path is not enough
Correct static path, note to check nginx user
Capitalization of services and small typos
Service examples updated to their latest versions and download links
Expanded /var/www chowns for Nginx and Apache examples
Add in a troubleshooting note for no images being displayed (permissions issue) and gunicorn not execting (file path context)
Correct formatting. Reword a few parts. Remove "new in 1.15".
This commit is contained in:
Ariel Rin
2018-04-18 08:55:18 +10:00
committed by Adarnof
parent cd8bcfbbb5
commit 95f72c854d
27 changed files with 203 additions and 181 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
docs/installation/auth/allianceauth.md
View File

@@ -2,12 +2,12 @@
```eval_rst
.. tip::
If you are uncomfortable with linux permissions follow the steps below as the root user. Some commands do not behave the same when run with sudo.
If you are uncomfortable with Linux permissions follow the steps below as the root user. Some commands do not behave the same when run with sudo.
```
## Dependencies
Alliance Auth can be installed on any operating system. Dependencies are provided below for two of the most popular server platforms, Ubuntu and CentOS. To install on your favourite flavour of linux, identify and install equivalent packages to the ones listed here.
Alliance Auth can be installed on any operating system. Dependencies are provided below for two of the most popular server platforms, Ubuntu and CentOS. To install on your favourite flavour of Linux, identify and install equivalent packages to the ones listed here.
```eval_rst
.. hint::
@@ -31,7 +31,7 @@ CentOS:
### Database
It's recommended to use a database service instead of sqlite. Many options are available, but this guide will use MariaDB.
It's recommended to use a database service instead of SQLite. Many options are available, but this guide will use MariaDB.
Ubuntu:
@@ -60,7 +60,7 @@ CentOS:
```eval_rst
.. important::
CentOS: Make sure redis is running before continuing. ::
CentOS: Make sure Redis is running before continuing. ::
systemctl enable redis.service
systemctl start redis.service
@@ -104,7 +104,7 @@ Create a Python virtual environment and put it somewhere convenient (e.g. `/home
```eval_rst
.. warning::
The python3 command may not be available on all installations. Try a specific version such as python3.6 if this is the case.
The python3 command may not be available on all installations. Try a specific version such as ``python3.6`` if this is the case.
```
```eval_rst
@@ -117,14 +117,14 @@ Activate the virtualenv using `source /home/allianceserver/venv/auth/bin/activat
```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.
Each time you come to do maintenance on your Alliance Auth installation, you should activate your virtual environment first. When finished, deactivate it with the ``deactivate`` command.
```
Ensure wheel is available with `pip install wheel` before continuing.
### Alliance Auth Project
You can install the library using `pip install allianceauth`. This will install Alliance Auth and all its python dependencies. You should also install gunicorn with `pip install gunicorn` before proceeding.
You can install the library using `pip install allianceauth`. This will install Alliance Auth and all its python dependencies. You should also install Gunicorn with `pip install gunicorn` before proceeding.
Now you need to create the application that will run the Alliance Auth install. Ensure you are in the allianceserver home directory by issuing `cd /home/allianceserver`.
@@ -153,13 +153,13 @@ And finally ensure the allianceserver user has read/write permissions to this di
### Gunicorn
To run the auth website a [WSGI Server](https://www.fullstackpython.com/wsgi-servers.html) is required. [Gunicorn](http://gunicorn.org/) is highly recommended for its ease of configuring. It can be manually run with `gunicorn myauth.wsgi` or automatically run using supervisor.
To run the auth website a [WSGI Server](https://www.fullstackpython.com/wsgi-servers.html) is required. [Gunicorn](http://gunicorn.org/) is highly recommended for its ease of configuring. It can be manually run from within your `myauth` base directory with `gunicorn --bind 0.0.0.0 myauth.wsgi` or automatically run using Supervisor.
The default configuration is good enough for most installations. Additional information is available in the [gunicorn](gunicorn.md) doc.
### Supervisor
[Supervisor](http://supervisord.org/) is a process watchdog service: it makes sure other processes are started automatically and kept running. It can be used to automatically start the WSGI server and celery workers for background tasks. Installation varies by OS:
[Supervisor](http://supervisord.org/) is a process watchdog service: it makes sure other processes are started automatically and kept running. It can be used to automatically start the WSGI server and Celery workers for background tasks. Installation varies by OS:
Ubuntu:
@@ -171,7 +171,7 @@ CentOS:
systemctl enable supervisord.service
systemctl start supervisord.service
Once installed it needs a configuration file to know which processes to watch. Your Alliance Auth project comes with a ready-to-use template which will ensure the celery workers, celery task scheduler and gunicorn are all running.
Once installed it needs a configuration file to know which processes to watch. Your Alliance Auth project comes with a ready-to-use template which will ensure the Celery workers, Celery task scheduler and Gunicorn are all running.
Ubuntu:
@@ -187,7 +187,7 @@ You can check the status of the processes with `supervisorctl status`. Logs from
```eval_rst
.. note::
Any time the code or your settings change you'll need to restart gunicorn and celery. ::
Any time the code or your settings change you'll need to restart Gunicorn and Celery. ::
supervisorctl restart myauth:
```
@@ -214,4 +214,4 @@ Some releases come with changes to settings: update your project's settings with
Some releases come with new or changed models. Update your database to reflect this with `python /home/allianceserver/myauth/manage.py migrate`.
Always restart celery and gunicorn after updating.
Always restart Celery and Gunicorn after updating.

4
docs/installation/auth/apache.md
View File

@@ -24,7 +24,7 @@ Apache needs to be able to read the folder containing your auth project's static
Apache serves sites through defined virtual hosts. These are located in `/etc/apache2/sites-available/` on Ubuntu and `/etc/httpd/conf.d/httpd.conf` on CentOS.
A virtual host for auth need only proxy requests to your WSGI server (gunicorn if you followed the install guide) and serve static files. Examples can be found below. Create your config in its own file eg `myauth.conf`.
A virtual host for auth need only proxy requests to your WSGI server (Gunicorn if you followed the install guide) and serve static files. Examples can be found below. Create your config in its own file e.g. `myauth.conf`
### Ubuntu
@@ -34,7 +34,7 @@ To proxy and modify headers a few mods need to be enabled.
a2enmod proxy_http
a2enmod headers
Create a new config file for auth eg `/etc/apache2/sites-available/myauth.conf` and fill out the virtual host configuration. To enable your config use `a2ensite myauth.conf` and then reload apache with `service apache2 reload`.
Create a new config file for auth e.g. `/etc/apache2/sites-available/myauth.conf` and fill out the virtual host configuration. To enable your config use `a2ensite myauth.conf` and then reload apache with `service apache2 reload`.
### CentOS

4
docs/installation/auth/gunicorn.md
View File

@@ -10,12 +10,12 @@ Check out the full [Gunicorn docs](http://docs.gunicorn.org/en/latest/index.html
```eval_rst
.. note::
If you're using a virtual environment (and I would encourage you to do so when hosting Alliance Auth), activate it now. `source /path/to/venv/bin/activate`.
If you're using a virtual environment, activate it now. ``source /path/to/venv/bin/activate``.
```
Install Gunicorn using pip, `pip install gunicorn`.
In your `myauth` base directory, try running `gunicorn --bind 0.0.0.0:8000 myauth.wsgi`. You should be able to browse to http://yourserver:8000 and see your Alliance Auth installation running. Images and styling will be missing, but dont worry, your web server will provide them.
In your `myauth` base directory, try running `gunicorn --bind 0.0.0.0:8000 myauth.wsgi`. You should be able to browse to http://yourserver:8000 and see your Alliance Auth installation running. Images and styling will be missing, but don't worry, your web server will provide them.
Once you validate its running, you can kill the process with Ctrl+C and continue.

17
docs/installation/auth/nginx.md
View File

@@ -1,6 +1,6 @@
# NGINX
## Overivew
## Overview
Nginx (engine x) is a HTTP server known for its high performance, stability, simple configuration, and low resource consumption. Unlike traditional servers (i.e. Apache), Nginx doesn't rely on threads to serve requests, rather using an asynchronous event driven approach which permits predictable resource usage and performance under load.
@@ -12,7 +12,7 @@ You can read more about NGINX on the [NGINX wiki](https://www.nginx.com/resource
If you're converting from Apache, here are some things to consider.
Nginx is lightweight for a reason. It doesn't try to do everything internally and instead concentrates on just being a good HTTP server. This means that, unlike Apache, it wont automatically run PHP scripts via mod_php and doesn't have an internal WSGI server like mod_wsgi. That doesn't mean that it can't, just that it relies on external processes to run these instead. This might be good or bad depending on your outlook. It's good because it allows you to segment your applications, restarting Alliance Auth wont impact your PHP applications. On the other hand it means more config and more management of services. For some people it will be worth it, for others losing the centralised nature of Apache may not be worth it.
Nginx is lightweight for a reason. It doesn't try to do everything internally and instead concentrates on just being a good HTTP server. This means that, unlike Apache, it won't automatically run PHP scripts via mod_php and doesn't have an internal WSGI server like mod_wsgi. That doesn't mean that it can't, just that it relies on external processes to run these instead. This might be good or bad depending on your outlook. It's good because it allows you to segment your applications, restarting Alliance Auth wont impact your PHP applications. On the other hand it means more config and more management of services. For some people it will be worth it, for others losing the centralised nature of Apache may not be worth it.
```eval_rst
+-----------+----------------------------------------+
@@ -25,13 +25,20 @@ Nginx is lightweight for a reason. It doesn't try to do everything internally an
```
Your .htaccess files wont work. Nginx has a separate way of managing access to folders via the server config. Everything you can do with htaccess files you can do with Nginx config. [Read more on the Nginx wiki](https://www.nginx.com/resources/wiki/start/topics/examples/likeapache-htaccess/)
Your .htaccess files won't work. Nginx has a separate way of managing access to folders via the server config. Everything you can do with htaccess files you can do with Nginx config. [Read more on the Nginx wiki](https://www.nginx.com/resources/wiki/start/topics/examples/likeapache-htaccess/)
## Setting up Nginx
Install Nginx via your preferred package manager or other method. If you need help just search, there are plenty of guides on installing Nginx out there.
Nginx needs to be able to read the folder containing your auth project's static files. On Ubuntu: `chown -R nginx:nginx /var/www/myauth/static`, and on CentOS: `chown -R nginx:nginx /var/www/myauth/static`
Nginx needs to be able to read the folder containing your auth project's static files. `chown -R nginx:nginx /var/www/myauth/static`.
```eval_rst
.. tip::
Some specific distros may use www-data:www-data instead of nginx:nginx, causing static files (images, stylesheets etc) not to appear. You can confirm what user Nginx will run under by checking either its base config file `/etc/nginx/nginx.conf` for the "user" setting, or once Nginx has started `ps aux | grep nginx`.
Adjust your chown commands to the correct user if needed.
..
```
You will need to have [Gunicorn](gunicorn.md) or some other WSGI server setup for hosting Alliance Auth.
@@ -57,7 +64,7 @@ server {
location = /favicon.ico { access_log off; log_not_found off; }
location /static/ {
location /static {
alias /var/www/myauth/static;
autoindex off;
}