diff --git a/docs/installation/auth/allianceauth.md b/docs/installation/auth/allianceauth.md index 222feff0..2e55817c 100644 --- a/docs/installation/auth/allianceauth.md +++ b/docs/installation/auth/allianceauth.md @@ -2,7 +2,7 @@ ```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. ``` ## Dependencies diff --git a/docs/installation/auth/gunicorn.md b/docs/installation/auth/gunicorn.md index 46b2db37..7e35b305 100644 --- a/docs/installation/auth/gunicorn.md +++ b/docs/installation/auth/gunicorn.md @@ -65,7 +65,7 @@ e.g. `command=/path/to/venv/bin/gunicorn myauth.wsgi` ### Starting via Supervisor -Once you have your configuration all sorted, you will need to reload your supervisor config `sudo service supervisor reload` and then you can start the Gunicorn server via `sudo supervisorctl start aauth-gunicorn` (or whatever you renamed it to). You should see something like the following `aauth-gunicorn: started`. If you get some other message, you'll need to consult the Supervisor log files, usually found in `/var/log/supervisor/`. +Once you have your configuration all sorted, you will need to reload your supervisor config `service supervisor reload` and then you can start the Gunicorn server via `supervisorctl start aauth-gunicorn` (or whatever you renamed it to). You should see something like the following `aauth-gunicorn: started`. If you get some other message, you'll need to consult the Supervisor log files, usually found in `/var/log/supervisor/`. ## Configuring your webserver @@ -76,4 +76,4 @@ Any web server capable of proxy passing should be able to sit in front of Gunico ## Restarting Gunicorn In the past when you made changes you restarted the entire Apache server. This is no longer required. When you update or make configuration changes that ask you to restart Apache, instead you can just restart Gunicorn: -`sudo supervisorctl restart myauth-gunicorn`, or the service name you chose for it. +`supervisorctl restart myauth-gunicorn`, or the service name you chose for it. diff --git a/docs/installation/auth/upgradev1.md b/docs/installation/auth/upgradev1.md index 2a663a93..0e0640ed 100644 --- a/docs/installation/auth/upgradev1.md +++ b/docs/installation/auth/upgradev1.md @@ -60,10 +60,13 @@ If you used member/blue group names other than the standard "Member" and "Blue" Any permissions assigned to these groups will be copied to the state replacing them. Because these groups are no longer managed they pose a security risk and so are deleted at the end of the migration automatically. - +### Run Migrations + +Once you've configured any optional settings it is now safe to run the included migrations. + ## Validating Upgrade -Before starting the Celery workers it's a good idea to validate the states were created and assigned correctly. Any mistakes now will trigger deletion of service accounts: if celery workers aren't running these tasks aren't yet processed. States can be checked through the admin site. +Before starting the Celery workers it's a good idea to validate the states were created and assigned correctly. Any mistakes now will trigger deletion of service accounts: if Celery workers aren't running these tasks aren't yet processed. States can be checked through the admin site. The site (and not Celery) can be started with `supervisorctl start myauth:gunicorn`. Then navigate to the admin site and log in with your v1 username and password. States and User Profiles can be found under the Authentication app. diff --git a/docs/installation/services/discord.md b/docs/installation/services/discord.md index 5f3ad75e..72602741 100644 --- a/docs/installation/services/discord.md +++ b/docs/installation/services/discord.md @@ -21,8 +21,6 @@ In your auth project's settings file, do the following: DISCORD_SYNC_NAMES = False ### Creating a Server -*If you already have a Discord server, skip the creation step, but be sure to retrieve the server ID* - Navigate to the [Discord site](https://discordapp.com/) and register an account, or log in if you have one already. On the left side of the screen you’ll see a circle with a plus sign. This is the button to create a new server. Go ahead and do that, naming it something obvious. @@ -31,6 +29,11 @@ Now retrieve the server ID [following this procedure.](https://support.discordap Update your auth project's settings file, inputting the server ID as `DISCORD_GUILD_ID` +```eval_rst +.. note:: + If you already have a Discord server skip the creation step, but be sure to retrieve the server ID +``` + ### Registering an Application Navigate to the [Discord Developers site.](https://discordapp.com/developers/applications/me) Press the plus sign to create a new application. @@ -66,3 +69,8 @@ If you want users to have their Discord nickname changed to their in-game charac ## Managing Roles Once users link their accounts you’ll notice Roles get populated on Discord. These are the equivalent to Groups on every other service. The default permissions should be enough for members to use text and audio communications. Add more permissions to the roles as desired through the server management window. + +## Troubleshooting + +### "Unknown Error" on Discord site when activating service +This indicates your callback URL doesn't match. Ensure the `DISCORD_CALLBACK_URL` setting exactly matches the URL entered on the Discord developers site. This includes http(s), trailing slash, etc. \ No newline at end of file diff --git a/docs/installation/services/market.md b/docs/installation/services/market.md index 0a478b66..7c919d97 100644 --- a/docs/installation/services/market.md +++ b/docs/installation/services/market.md @@ -30,7 +30,7 @@ Alliance Market needs a database. Create one in MySQL/MariaDB. Default name is ` Install required packages to clone the repository: - sudo apt-get install mercurial meld + apt-get install mercurial meld Change to the web folder: @@ -38,18 +38,18 @@ Change to the web folder: Now clone the repository - sudo hg clone https://bitbucket.org/krojew/evernus-alliance-market + 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 + mkdir evernus-alliance-market/app/cache + mkdir evernus-alliance-market/app/logs + chmod -R 777 evernus-alliance-market/app/cache + chmod -R 777 evernus-alliance-market/app/logs Change ownership to apache - sudo chown -R www-data:www-data evernus-alliance-market + chown -R www-data:www-data evernus-alliance-market Enter directory @@ -61,7 +61,7 @@ Set environment variable Copy configuration - sudo cp app/config/parameters.yml.dist app/config/parameters.yml + cp app/config/parameters.yml.dist app/config/parameters.yml Edit, changing the following: - `database_name` to `alliance_market` @@ -79,25 +79,25 @@ Install composer [as per these instructions.](https://getcomposer.org/download/) Update dependencies. - sudo php composer.phar update --optimize-autoloader + php composer.phar update --optimize-autoloader Prepare the cache: - sudo php app/console cache:clear --env=prod --no-debug + php app/console cache:clear --env=prod --no-debug Dump assets: - sudo php app/console assetic:dump --env=prod --no-debug + php app/console assetic:dump --env=prod --no-debug Create DB entries - sudo php app/console doctrine:schema:update --force + php app/console doctrine:schema:update --force Install SDE: - sudo php app/console evernus:update:sde + php app/console evernus:update:sde Configure your web server to serve alliance market. @@ -150,11 +150,11 @@ A minimal Nginx config might look like: Once again, set cache permissions: - sudo chown -R www-data:www-data app/ + 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 + php app/console fos:user:promote your_username --super Now edit your auth project's settings file and fill in the web URL to your market as well as the database details. diff --git a/docs/installation/services/mumble.md b/docs/installation/services/mumble.md index f628d42a..87b6cd1e 100644 --- a/docs/installation/services/mumble.md +++ b/docs/installation/services/mumble.md @@ -15,21 +15,21 @@ Mumble is a free voice chat server. While not as flashy as TeamSpeak, it has all ## 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 + apt-add-repository ppa:mumble/release + apt-get update Now two packages need to be installed: - sudo apt-get install python-software-properties mumble-server + apt-get install python-software-properties mumble-server -Download the appropriate authenticator release from https://github.com/allianceauth/mumble-authenticator and install the python dependencies for it: +Download the appropriate authenticator release from [the authenticator repository](https://github.com/allianceauth/mumble-authenticator) and install the python dependencies for it: pip install -r requirements.txt ## Configuring Mumble Mumble ships with a configuration file that needs customization. By default it’s located at /etc/mumble-server.ini. Open it with your favourite text editor: - sudo nano /etc/mumble-server.ini + nano /etc/mumble-server.ini REQUIRED: To enable the ICE authenticator, edit the following: @@ -50,13 +50,13 @@ Save and close the file (control + O, control + X). To get Mumble superuser account credentials, run the following: - sudo dpkg-reconfigure mumble-server + dpkg-reconfigure mumble-server Set the password to something you’ll remember and write it down. This is needed to manage ACLs. Now restart the server to see the changes reflected. - sudo service mumble-server restart + service mumble-server restart That’s it! Your server is ready to be connected to at example.com:64738 @@ -84,9 +84,6 @@ The authenticator needs to be running 24/7 to validate users on Mumble. You shou 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 Alliance Auth creates your groups, go ahead and follow one of the wonderful web guides available on how to set up channel ACL properly. - ## Prepare Auth In your project's settings file, set `MUMBLE_URL` to the public address of your mumble server. Do not include any leading `http://` or `mumble://`. diff --git a/docs/installation/services/openfire.md b/docs/installation/services/openfire.md index 2190862b..e9c19577 100644 --- a/docs/installation/services/openfire.md +++ b/docs/installation/services/openfire.md @@ -17,21 +17,16 @@ BROADCAST_USER_PASSWORD = "" BROADCAST_SERVICE_NAME = "broadcast" -## Overview -Openfire is a Java-based XMPP server (Jabber). - ## Dependencies -One additional package is required - openjdk8 +Openfire require a Java 8 runtime environment. Ubuntu: - sudo add-apt-repository ppa:webupd8team/java -y - sudo apt-get update - sudo apt-get install oracle-java8-installer + apt-get install openjdk-8-jdk CentOS: - sudo yum -y install java-1.8.0-openjdk java-1.8.0-openjdk-devel + yum -y install java-1.8.0-openjdk java-1.8.0-openjdk-devel ## Setup ### Download Installer @@ -51,11 +46,11 @@ Now install from the package. Replace the filename with your filename (the last Ubuntu: - sudo dpkg -i openfire_4.2.3_all.deb + dpkg -i openfire_4.2.3_all.deb CentOS: - sudo yum install -y openfire-4.2.3-1.noarch.rpm + yum install -y openfire-4.2.3-1.noarch.rpm ### Create Database Performance is best when working from a SQL database. If you installed MySQL or MariaDB alongside your auth project, go ahead and create a database for Openfire: diff --git a/docs/installation/services/phpbb3.md b/docs/installation/services/phpbb3.md index d31167cd..ab4abf9d 100644 --- a/docs/installation/services/phpbb3.md +++ b/docs/installation/services/phpbb3.md @@ -34,8 +34,8 @@ Create a database to install phpBB3 in. Edit your auth project's settings file and fill out the `DATABASES['phpbb3']` part. -### Download phpbb3 -phpBB is available as a zip from their website. Navigate to the website’s [downloads section](https://www.phpbb.com/downloads/) using your PC browser and copy the URL for the latest version zip. Depending on your browser you may have a Copy Link or similar option in your right click menu. +### Download phpBB3 +phpBB3 is available as a zip from their website. Navigate to the website’s [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 user’s home directory: `cd ~` @@ -49,12 +49,12 @@ This needs to be unpackaged. Unzip it, replacing the file name with that of the Now we need to move this to our web directory. Usually `/var/www/forums`. - sudo mv phpBB3 /var/www/forums + mv phpBB3 /var/www/forums The web server needs read/write permission to this folder -Apache: `sudo chown -R www-data:www-data /var/www/forums` -Nginx: `sudo chown -R nginx:nginx /var/www/forums` +Apache: `chown -R www-data:www-data /var/www/forums` +Nginx: `chown -R nginx:nginx /var/www/forums` ```eval_rst .. tip:: @@ -133,7 +133,7 @@ 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 + 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`. diff --git a/docs/installation/services/smf.md b/docs/installation/services/smf.md index 6a0d34ce..72d222b5 100644 --- a/docs/installation/services/smf.md +++ b/docs/installation/services/smf.md @@ -38,12 +38,12 @@ This needs to be unpackaged. Unzip it, replacing the file name with that of the Now we need to move this to our web directory. Usually `/var/www/forums`. - sudo mv smf /var/www/forums + mv smf /var/www/forums The web server needs read/write permission to this folder -Apache: `sudo chown -R www-data:www-data /var/www/forums` -Nginx: `sudo chown -R nginx:nginx /var/www/forums` +Apache: `chown -R www-data:www-data /var/www/forums` +Nginx: `chown -R nginx:nginx /var/www/forums` ```eval_rst .. tip:: @@ -80,7 +80,7 @@ A minimal Nginx config might look like: listen 80; server_name forums.example.com; root /var/www/forums; - index app.php; + index index.php; access_log /var/logs/forums.access.log; location ~ \.php$ { diff --git a/docs/installation/services/teamspeak3.md b/docs/installation/services/teamspeak3.md index 91fbeeae..289a65b9 100644 --- a/docs/installation/services/teamspeak3.md +++ b/docs/installation/services/teamspeak3.md @@ -41,26 +41,26 @@ Now we need to extract the file. ### Create User TeamSpeak needs its own user. - sudo adduser --disabled-login teamspeak + 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 + mv teamspeak3-server_linux_amd64 /usr/local/teamspeak + 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 + ln -s /usr/local/teamspeak/ts3server_startscript.sh /etc/init.d/teamspeak + update-rc.d teamspeak defaults Finally we start the server. - sudo service teamspeak start + service teamspeak start ### Update Settings -The console will spit out a block of text. If it does not appear, it can be found with `sudo service teamspeak status`. **SAVE THIS**. +The console will spit out a block of text. If it does not appear, it can be found with `service teamspeak status`. **SAVE THIS**. If you plan on claiming the ServerAdmin token, do so with a different TeamSpeak client profile than the one used for your auth account, or you will lose your admin status. diff --git a/docs/maintenance/troubleshooting.md b/docs/maintenance/troubleshooting.md index 9737e991..def222da 100644 --- a/docs/maintenance/troubleshooting.md +++ b/docs/maintenance/troubleshooting.md @@ -2,18 +2,20 @@ ## Something broken? Stuck on an issue? Can't get it set up? -Start by checking the [issues](https://github.com/allianceauth/allianceauth/issues?utf8=%E2%9C%93&q=is%3Aissue) - especially closed ones. +Start by checking the [issues](https://github.com/allianceauth/allianceauth/issues?q=is%3Aissue) - especially closed ones. No answer? - open an [issue](https://github.com/allianceauth/allianceauth/issues) - harass us on [gitter](https://gitter.im/R4stl1n/allianceauth) + +## Logging + +In its default configuration your auth project logs INFO and above messages to myauth/log/allianceauth.log. If you're encountering issues it's a good idea to view DEBUG messages as these greatly assist the troubleshooting process. These are printed to the console with manually starting the webserver via `python manage.py runserver`. + +To record DEBUG messages in the log file, alter a setting in your auth project's settings file: `LOGGING['handlers']['log_file']['level'] = 'DEBUG'`. After restarting gunicorn and celery your log file will record all logging messages. ## Common Problems -### `pip install -r requirements.txt` is failing - -It's probably a permissions issue. Ensure your current user can write to the virtual environment folder. That, or you're missing a dependency of some kind which will be indicated in the error message. - ### I'm getting an error 500 trying to connect to the website on a new install *Great.* Error 500 is the generic message given by your web server when *anything* breaks. The actual error message is hidden in one of your auth project's log files. Read them to identify it. @@ -43,7 +45,7 @@ This usually indicates an issue with your email settings. Ensure these are corre ### No images are available to users accessing the website -This is due to a permissions mismatch, check the setup guide for your web server. Additionally ensure the user who owns /var/www/myauth/static is the same user as running your webserver, as this can be non-standard. +This is likely due to a permissions mismatch. Check the setup guide for your web server. Additionally ensure the user who owns `/var/www/myauth/static` is the same user as running your webserver, as this can be non-standard. ### Unable to execute 'gunicorn myauth.wsgi' or ImportError: No module named 'myauth.wsgi'