- Introduction: About This Installation Guide
- Step 1: Setting Up a New Website in WebFaction
- Step 2: Installing Required Libraries
- Step 3: Getting OSQA
- Step 4: The Settings File
- Step 5: The WSGI Files
- Step 6: Configure the Webserver
- Step 7: Database
- Step 8: Starting & Stopping Your Server
- Step 9: Setting up Your First User and Standardizing the Interface
This guide details the steps for setting up OSQA on a WebFaction shared-hosting account, including email setup, using Apache2, mod_wsgi, and a MySQL database backend. We have chosen arbitrary names, passwords, domain names, etc. throughout this tutorial (indicated by all caps and quotes around the name). You may choose names and passwords that are different from our suggested ones, but it is important to note that they are often referenced later in the documentation, so you must remember any alternative names and passwords that you enter.
When you sign up for a Webfaction account, select Django and WebFaction will create a Django application for your website/subdomain. WebFaction will also associate that application with your website/subdomain. If necessary, add or create any domains or subdomains that you might need by going here. For the rest of this tutorial we will use "DOMAIN.com" as the domain.
Now go to the control panel and create a new Webfaction application with a "Type:" of "Django 1.2.3 (mod_wsgi 3.2/Python 2.6)". Name it "osqa_server".
Next, you will need to go to this list in the Webfaction control panel and create a new Webfaction website which will associate the subdomain with the new osqa_server application. We will call the website "SITENAME" and set it to use the osqa_server application for the site's root location - "/".
Typically each project you create will need its own database. This can be done here via the Webfaction control panel. Choose MySQL and modify the name (it defaults to your Webfaction account name) by adding an underscore and a project-specific identifier such as "_osqa". Before leaving this section of the control panel, you will want to change database's name and the password. We will name the database "OSQADATABASE_NAME" and "OSQADATABASE_PASSWORD" will be our password.
- To configure email, you need to create an email mailbox. Add one here. Note that your mailbox password shouldn't be the same password you use to SSH to webfaction.
- Save the mail password for later. We will call the username and password MAILBOX_USERNAME and MAILBOX_PASSWORD respectively. You might also consider adding an email address like admin@DOMAIN.com, here
After logging into Webfaction via SSH (go here for Webfaction's instructions), you will need to update you library files. In this tutorial we are using Python 2.6. Therefore, we will be using the command 'easy_install-2.6.' This may not be appropriate for you. For instance, if you are using Python 2.4, you need to change that command to 'easy_install-2.4'.
- South - automates database migrations - strongly recommended
- djangosphinx - only necessary if you are going to use the sphinxfulltext module. (refer back to the Modules section for more details)
- Django Debug Toolbar - very helpful for debugging
Now you can run the SVN command to get the software:
Now that you have the latest release of OSQA you can begin setting it up. First, change your directory to the newly formed osqa directory. Then copy and rename the file settings_local.py.dist to settings_local.py. You can do this with the following command:
Next, you will need to open the newly created settings_local.py file and edit it as specified below.
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:
From within the osqa directory copy and rename the file osqa.wsgi.dist to osqa.wsgi. You can do this with the following command:
Now open the osqa.wsgi file and find the lines that append directories to the system's path.
These lines tell WSGI where to find the OSQA modules. You will need to update them to point to the OSQA installation directory, for instance /home/USER_NAME/webapps/osqa.
If you have not named the OSQA installation directory "osqa," you will also have to update the DJANGO_SETTINGS_MODULE value. Look for the following line, and configure it so that it looks like YOUR_OSQA_INSTALL_DIR.settings.
Once you have saved your changes, the full file should look like the example below:
Open the Apache configuration file, found in /home/USER_NAME/webapps/SITE_NAME/apache2/conf/httpd.conf. Find the line where WSGIScriptAlias is defined and update it to point to the osqa.wsgi script in your OSQA installation directory. The declaration should look like this:
Now you will populate the blank MySQL osqa database with the necessary tables and data. From inside the OSQA directory, run the following command:
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:
With the database now prepared, you are ready to start the Apache server and begin using your new OSQA installation.
To get your server up and running, enter the following into the command shell:
|You can see the results of the Apache start and stop commands by looking at the log held in /home/USER_NAME/logs/user/error_SITE_NAME.log.|
Once you get into your site you're going to setup your first user which will be you and it will automatically make you a superuser. When you're done registering you'll see the link for the administration panel in the upper left corner. Once you get into the admin area click on To Standard Interface in the upper left corner to get rid of the ugly simple text version.