Ubuntu with Apache and MySQL

About This Installation Guide

Before you begin OSQA installation, you first need to get the source code from subversion. You can receive instruction on how to do this from our Download OSQA page . This guide covers the installation of OSQA on the Ubuntu operating system using a MySQL database. If you've achieved a successful installation on Windows, Mac, or any other OS, we are interested in adding your installation methods to our upcoming guides for those systems. To successfully install OSQA, simply perform the instructions in each section as you scroll down the page.

This doc was based on Ubuntu 10.4 but should work with older or newer versions with minor adaption (if any).

This tutorial assumes that you are logged in as the "osqa" user, and will be installing OSQA the directory /home/osqa/osqa-server.

Downloading OSQA

Checkout the OSQA source tree from Subversion:

svn co http://svn.osqa.net/svnroot/osqa/trunk/ /home/osqa/osqa-server

Prerequisites

Apache Web Server

For this tutorial, Apache will act as the web server for OSQA. Out of the box Apache will happily serve up static web content; for our purposes we'll also need to configure it to run the OSQA Python code.

Install Apache

In order to install the Apache web server and the Mod_WSGI Python support libraries on Ubuntu, run the following command:

sudo apt-get install apache2 libapache2-mod-wsgi

Update the OSQA WSGI Script

Create a new file in the /home/osqa/osqa-server directory named osqa.wsgi. Copy the following contents into the file:

/home/osqa/osqa-server/osqa.wsgi
import os
import sys
sys.path.append('/home/osqa')
sys.path.append('/home/osqa/osqa-server')
# The first part of this module name should be identical to the directory name
# of the OSQA source.  For instance, if the full path to OSQA is
# /home/osqa/osqa-server, then the DJANGO_SETTINGS_MODULE should have a value
# of 'osqa-server.settings'.
os.environ['DJANGO_SETTINGS_MODULE'] = 'osqa-server.settings'
import django.core.handlers.wsgi
application = django.core.handlers.wsgi.WSGIHandler()

Remove the Default Apache Configurations

This server will be dedicated to running OSQA, so the default Apache configuration files will not be needed. Remove the default Apache configuration files:

sudo rm /etc/apache2/sites-available/default\
    /etc/apache2/sites-available/default-ssl\
    /etc/apache2/sites-enabled/000-default

Add the OSQA Configuration to Apache

Open a new OSQA configuration file for editing in /etc/apache2/sites-available with the following command:

sudo vim /etc/apache2/sites-available/osqa

Paste in the following content:

/etc/apache2/sites-available/osqa
# Must be readable and writable by apache
WSGISocketPrefix ${APACHE_RUN_DIR}

#NOTE: all urs below will need to be adjusted if
#settings.FORUM_SCRIPT_ALIAS !='' (e.g. = 'forum/')
#this allows "rooting" forum at [http://example.com/forum], if you like
<VirtualHost *:80>
	ServerAdmin forum@example.com
	DocumentRoot /home/osqa/osqa-server
	ServerName example.com

	#run mod_wsgi process for django in daemon mode
	#this allows avoiding confused timezone settings when
	#another application runs in the same virtual host
	WSGIDaemonProcess OSQA
	WSGIProcessGroup OSQA

	#force all content to be served as static files
	#otherwise django will be crunching images through itself wasting time
	Alias /m/ "/home/osqa/osqa-server/forum/skins/"
        <Directory "/home/osqa/osqa-server/forum/skins">
                Order allow,deny
                Allow from all
        </Directory>
	Alias /upfiles/ "/home/osqa/osqa-server/forum/upfiles/"
	<Directory "/home/osqa/osqa-server/forum/upfiles">
		Order deny,allow
		Allow from all
	</Directory>

	#this is your wsgi script described in the prev section
	WSGIScriptAlias / /home/osqa/osqa-server/osqa.wsgi

	CustomLog ${APACHE_LOG_DIR}/osqa.access.log common
	ErrorLog ${APACHE_LOG_DIR}/osqa.error.log
</VirtualHost>

Link to the OSQA config in the sites-enabled directory:

sudo ln -s /etc/apache2/sites-available/osqa /etc/apache2/sites-enabled/osqa

MySQL Database Server

OSQA can make use of MySQL for its database backend. This guide assumes that MySQL will be OSQA's database. The following steps will walk through how to install MySQL and set up the intial OSQA user and database.

Installing MySQL

Run the following command to install the MySQL client and server packages:

sudo apt-get install mysql-server mysql-client
MySQL Root User Password
During the installation process, you will be prompted to configure the password for the root MySQL user. Make sure you make a note of this, as the password will be needed during future MySQL administration tasks.

Adding the OSQA user

Typical installations have a dedicated user in MySQL for OSQA. To add this user, first login to the MySQL console as the MySQL root user:

sudo mysql -u root -p

After supplying the root user password, you will be presented with the MySQL command prompt (mysql>). Enter the following command and press Enter to create the OSQA MySQL user:

CREATE USER 'osqa'@'localhost' IDENTIFIED BY 'your_osqa_password';

Creating the OSQA database

OSQA uses its own "osqa" database within MySQL. To prepare this database you need to run the following two lines in the MySQL console. Enter the following lines, pressing Enter after each line to submit the command:

CREATE DATABASE osqa DEFAULT CHARACTER SET UTF8 COLLATE utf8_general_ci;
GRANT ALL ON osqa.* to 'osqa'@'localhost';

Python

OSQA requires Python 2.x to run (this installation guide was tested against Python v2.6.6). Recent Ubuntu distributions have shipped with Python installed by default. To ensure that Python is installed on your machine, run this command:

python -V

If Python is not installed on your system, you can install Python by running the following command:

sudo apt-get install python

Python Setup Tools

Having the Python setup tools handy will allow you to install the required libraries quickly and easily. Install python-setuptools by running this command:

sudo apt-get install python-setuptools

Required Libraries

OSQA depends on a number of other libraries to run successfully. Install the required libraries by executing the following commands:

While these packages are also available from Ubuntu repositories, the easy_install method more reliably delivers the most recent version of the desired library.
sudo apt-get install python-mysqldb
sudo easy_install South django django-debug-toolbar markdown \
    html5lib python-openid

Configure OSQA Settings

Change your directory to the osqa installation directory. Then copy and rename the file settings_local.py.dist to settings_local.py. You can do this with the following command:

cp settings_local.py.dist settings_local.py

Update the Database Settings

Next, you will need to open the newly created settings_local.py file and edit it as specified below.

settings_local.py
DATABASE_NAME = 'osqa'
DATABASE_USER = 'osqa'
DATABASE_PASSWORD = 'your_osqa_password'
DATABASE_ENGINE = 'mysql'

Update the Application URL

Osqa needs to know the server domain name so that it can use that information to create URLs, such as for email validation messages. Enter your domain name in the APP_URL field as shown below:

settings_local.py
APP_URL = 'http://YOUR_URL/'

Populate the OSQA Database

Now you will populate the blank MySQL osqa database with the necessary tables and data. From inside the OSQA directory, run the following command:

sudo python manage.py syncdb --all
Warning
You will be prompted to create a new "super user."  You should promptly answer "NO".  Once you get your site running, create a new user through the normal OSQA account creation process and that will be your super user.

With that command you have successfully defined the schema. With South installed, you also have the ability to migrate between databases--a useful feature as OSQA is updated. However, as this is a fresh install, you will need to convince South that the schema is already up to date by "faking" a migration. You can do that with the following command:

sudo python manage.py migrate forum --fake

With the database now prepared, you are ready to start the Apache server and begin using your new OSQA installation.

Grant Apache Permissions to the OSQA Files

Apache will need read and write permissions to various OSQA files in order to support OSQA. The best way to give Apache read permissions to the OSQA files is to grant group ownership to the Apache group (www-data). The following command will make all OSQA files owned by the "osqa" user and the Apache group:

sudo chown -R osqa:www-data /home/osqa/osqa-server

Apache will need write access to the templates/upfiles and log directories. The following commands will grant write permissions to the Apache group for those two directories:

sudo chmod -R g+w /home/osqa/osqa-server/forum/upfiles
sudo chmod -R g+w /home/osqa/osqa-server/log

Starting Apache and OSQA

Once all of the installation and configuration is complete, you can start Apache and OSQA. Do this by restarting the Apache instance to load the new configuration:

sudo /etc/init.d/apache2 restart

Apache will load OSQA as it starts back up. It should report "[ OK ]" when the restart is finished. You can check the status by examining the general Apache error log at /var/log/apache2/error.log and the OSQA-specific log at /var/log/apache2/osqa.error.log.

If everything started up ok, you can being using OSQA by visiting the this URL: http://localhost/

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.