INSTALL.webfaction

   1 Detailed instructions for installing OSQA on WebFaction
   2
   3 Adapted from http://code.pinaxproject.com/wiki/DetailedPinaxWebfaction/
   4
   5 Please email turian at gmail with any updates or corrections.
   6
   7
   8 Installing OSQA on Webfaction
   9 ------------------------------------
  10
  11 Details the steps for setting up OSQA on a Webfaction shared-hosting
  12 account, including email setup, using Apache2, mod_wsgi, psycopg2.
  13
  14 If you want to search-and-replace through this file, you will need to replace:
  15     osqa_server         [name of Webfaction application, which will be in ~/webapps/]
  16     osqa_static         [name of Webfaction application for static media serving]
  17     DOMAIN.com          [domain name for OSQA site]
  18     PORT                [port number assigned by WebFaction to your mod_wsgi application]
  19     SITENAME            [name you give the OSQA site, which will contain the apache logs]
  20     MYOSQA              [name of the OSQA project]
  21     MAILBOX_USERNAME    [username you give the email address]
  22     MAILBOX_PASSWORD    [password that webfaction gives to this email username]
  23     OSQADATABASE_NAME   [username you give the database]
  24     OSQADATABASE_PASSWORD   [password that webfaction gives to this database]
  25     ~/envs/osqa         [directory for the OSQA python environment, grep for 'env']
  26     USERNAME            [your WebFaction username]
  27
  28 Some things I'm not sure about:
  29
  30 Here's what I don't know how to do:
  31     * Set up a nginx server for static media.
  32     * Configure sphinx search
  33     * Use PostgreSQL, not MySQL: http://osqa.net/question/13/can-i-use-osqa-with-postgresql
  34
  35
  36 Webfaction Control Panel
  37 --------------------------
  38
  39 (Note: if you sign up and pick django it will create the application
  40 for you, website/subdomain and associate the two for you.)
  41
  42     If necessary, add or create any domains or subdomains you may need.
  43
  44         https://panel.webfaction.com/domain/list/
  45
  46     Let's call the domain DOMAIN.com.
  47
  48     Create a new Webfaction application with a "Type:" of "mod_wsgi
  49     2.5/Python2.5", naming it "osqa_server". (These instructions
  50     might also work with mod_wsgi 2.0, if you like.)
  51
  52         https://panel.webfaction.com/app_/list
  53
  54     Note the port number assigned to the mod_wsgi application. Call
  55     it PORT.
  56
  57     Create a new Webfaction website which will associate the subdomain
  58     with the new osqa_server application. Give it name SITENAME, at least one
  59     domain, and set it to use the osqa_server application for the site's
  60     root location, "/".
  61
  62         https://panel.webfaction.com/site/list
  63
  64     You will need to create a database, typically one for each project
  65     you create. Change the type to PostgreSql and modify the name (it
  66     defaults to your webfaction account name) by adding an underscore
  67     and a project-specific identifier such as "_osqa". Before
  68     leaving this section of the control panel, you may wish to change
  69     the password.
  70
  71         https://panel.webfaction.com/database/create
  72
  73     Call these OSQADATABASE_NAME and OSQADATABASE_PASSWORD.
  74
  75     Save the database password for later.
  76
  77     [The following I haven't figured out yet]
  78     You will probably want to add a static media server. This is a
  79     Webfaction application. I created one of type "Static only (no
  80     .htaccess)" and with the name of "osqa_static".
  81
  82         https://panel.webfaction.com/app_/create
  83
  84     To configure email, you need an email mailbox. Add one here. Note
  85     that your mailbox password shouldn't be the same password you use
  86     to SSH to webfaction.
  87
  88         https://panel.webfaction.com/mailbox/list
  89
  90     Save the mail password for later.
  91     We will call the username and password MAILBOX_USERNAME and
  92     MAILBOX_PASSWORD, respectively.
  93     You might also consider adding an email address like admin@DOMAIN.com,
  94     here:
  95
  96         https://panel.webfaction.com/email/list
  97
  98
  99 OSQA Software
 100 --------------
 101
 102     Log onto webfaction and get the code. I use my fork because I have
 103     a simple pip installation:
 104         git://github.com/turian/osqa.git
 105     In my situation, I keep source code in ~/utils/src, create
 106     virtual environments in ~/envs/osqa, and create Pinax projects in
 107     ~/webapps/osqa_server/projects.
 108
 109     You will need pip + virtualenv installed:
 110
 111         easy_install --prefix=~/utils/ pip
 112         easy_install --prefix=~/utils/ virtualenv
 113
 114         cd ~/utils/src/
 115         git clone git://github.com/turian/osqa.git
 116         cd osqa
 117
 118         # We need python2.5 to be compatible with WSGI
 119         python2.5 ~/utils/bin/pip install -E ~/envs/osqa -r osqa-requirements.txt
 120         source ~/envs/osqa/bin/activate
 121
 122         # [Optional] If you want a MySQL database
 123         easy_install-2.5 --prefix ~/envs/osqa/ mysql-python
 124
 125 Additional Software
 126 -------------------
 127
 128     [Note that PostgreSQL installation doesn't work for me.]
 129
 130     You will need to install psycopg2 separately for PostgreSQL.
 131     Psycopg2 requires a little fiddling. Continuing to
 132     work in the ~/utils/src/ directory:
 133
 134         cd ~/utils/src/
 135         wget http://initd.org/pub/software/psycopg/psycopg2-2.0.13.tar.gz
 136         tar zxf psycopg2-2.0.13.tar.gz
 137         cd psycopg2-2.0.13
 138         nano setup.cfg
 139
 140         # edit the line reading "#pg_config=" so that it reads:
 141             "pg_config=/usr/local/pgsql/bin/pg_config"
 142
 143         python2.5 setup.py build
 144         python2.5 setup.py install
 145
 146
 147 Create a Project
 148 ----------------
 149
 150     In Pinax, you clone a project from OSQA.
 151     However, OSQA we just copy it.
 152
 153         cd ~/webapps/osqa_server
 154         mkdir projects
 155         cd projects
 156         cp -R ~/utils/src/osqa MYOSQA
 157         cd MYOSQA
 158         export OSQAPROJECT=`pwd`
 159
 160     Make some directories, as described in the OSQA INSTALL file:
 161     [okay I haven't actually done this yet]
 162
 163 #        mkdir -p $OSQASITE/upfiles/
 164 #        mkdir -p $OSQALOG
 165 #        sudo chown -R `whoami`:www-data $OSQASITE
 166 #        sudo chown -R `whoami`:www-data $OSQALOG
 167 #        chmod -R g+w $OSQASITE/upfiles
 168 #        chmod -R g+w $OSQALOG
 169
 170
 171     Edit the settings files:
 172
 173         cd $OSQAPROJECT
 174         cp settings_local.py.dist settings_local.py
 175         vi settings_local.py settings.py
 176
 177         Pay attention to the following settings:
 178
 179             DATABASE_ENGINE = 'mysql'
 180             DATABASE_NAME = 'OSQADATABASE_NAME'
 181             DATABASE_USER = 'OSQADATABASE_NAME'
 182             DATABASE_PASSWORD = 'OSQADATABASE_PASSWORD'
 183
 184             EMAIL_HOST='smtp.webfaction.com'
 185             EMAIL_HOST_USER='MAILBOX_USERNAME'
 186             EMAIL_HOST_PASSWORD='MAILBOX_PASSWORD'
 187             EMAIL_PORT='25'
 188             DEFAULT_FROM_EMAIL = 'MAILBOX_USERNAME@DOMAIN.com'
 189             SERVER_EMAIL = 'MAILBOX_USERNAME@DOMAIN.com'
 190             # The following setting might not be necessary, it's used in Pinax tho
 191             CONTACT_EMAIL = "MAILBOX_USERNAME@DOMAIN.com"
 192
 193             APP_URL = 'http://DOMAIN.com' #used by email notif system and RSS
 194
 195         [Later on, the install instructions should talk about]
 196             SERVE_MEDIA = False     # [Not present, not ready yet]
 197
 198     Create a directory for logs:
 199
 200         cd $OSQAPROJECT
 201         mkdir log
 202
 203     Modify mail cron scripts "cron/send_email_alerts" as follows:
 204     [Pinax has cron/emit_notices.sh, cron/retry_deferred.sh,
 205     cron/send_mail.sh, are these also necessary?]
 206
 207             #!/bin/sh
 208
 209             WORKON_HOME=~/envs/osqa
 210             PROJECT_ROOT=~/webapps/osqa_server/projects/MYOSQA/
 211
 212             # activate virtual environment
 213             . $WORKON_HOME/bin/activate
 214
 215             cd $PROJECT_ROOT
 216             python manage.py send_email_alerts >> $PROJECT_ROOT/log/cron_mail.log 2>&1
 217
 218         Use command "crontab -e" to add this script to your cron file, to run twice a day::
 219
 220             1 0,12 * * * ~/webapps/osqa_server/projects/MYOSQA/cron/send_email_alerts
 221
 222     [Configure sphinx]
 223
 224     Create the database tables, indices, and so forth:
 225
 226         python manage.py syncdb
 227
 228     [Ignore the following static media steps, I haven't tried them]
 229     Build media directory links within the project and create symbolic
 230     links on the static media server.
 231         python manage.py build_media -all
 232         mkdir ~/webapps/OSQA_STATIC/MYOSQA
 233         ln -sd ~/webapps/osqa_server/projects/MYOSQA/site_media ~/webapps/OSQA_STATIC/MYOSQA/site_media
 234
 235
 236     Set up the badges:
 237
 238         1. You should run the SQL commands in:
 239
 240                  sql_scripts/badges.sql
 241
 242         2. Edit paths in the file `cron/multi_award_badges`. (This
 243         file doesn't yet exist in the git repositories, so just
 244         copy `cron/send_email_alerts` and make sure the command
 245         `multi_award_badges` is executed.)
 246
 247         3. Run `cron/multi_award_badges` to make sure it works okay.
 248
 249         4. Use `crontab -e` to call `cron/multi_award_badges` maybe
 250         four times an hour.
 251
 252             4,19,34,49 * * * * ~/webapps/osqa_server/projects/MYOSQA/cron/multi_award_badges
 253
 254         5. Repeat steps 1-4 for `cron/once_award_badges`.
 255
 256
 257 Configure Apache2
 258 ----------------
 259
 260     Edit  ~/webapps/osqa_server/apache2/conf/httpd.conf as follows::
 261
 262         ServerAdmin "MAILBOX_USERNAME@DOMAIN.com"
 263         ServerRoot "/home/USERNAME/webapps/osqa_server/apache2"
 264         ServerName DOMAIN.com
 265
 266         LoadModule dir_module modules/mod_dir.so
 267         LoadModule env_module modules/mod_env.so
 268         #LoadModule setenvif_module modules/mod_setenvif.so
 269         LoadModule log_config_module modules/mod_log_config.so
 270         LoadModule mime_module modules/mod_mime.so
 271         LoadModule rewrite_module modules/mod_rewrite.so
 272         LoadModule wsgi_module modules/mod_wsgi.so
 273
 274         KeepAlive Off
 275         Listen PORT
 276         LogFormat "%{X-Forwarded-For}i %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
 277         CustomLog /home/USERNAME/logs/user/access_osqa_server_log combined
 278         ErrorLog /home/USERNAME/logs/user/error_osqa_server_log
 279         ServerLimit 2
 280
 281         #SetEnvIf X-Forwarded-SSL on HTTPS=1
 282
 283         WSGIPythonPath /home/USERNAME/envs/osqa/lib/python2.5/site-packages/
 284         WSGIScriptAlias / /home/USERNAME/webapps/osqa_server/projects/MYOSQA/osqa.wsgi
 285
 286         LoadModule alias_module modules/mod_alias.so
 287         WSGIDaemonProcess osqaWSGI user=USERNAME group=USERNAME threads=25 python-path=/home/USERNAME/envs/osqa/lib/python2.5/site-packages
 288         WSGIProcessGroup osqaWSGI
 289
 290         NameVirtualHost 127.0.0.1:PORT
 291
 292         #ErrorLog "logs/MYOSQA_2009_05_06.log"
 293         SetHandler none
 294         #Alias /site_media /home/USERNAME/webapps/static/MYOSQA/site_media
 295
 296         #force all content to be served as static files
 297         #otherwise django will be crunching images through itself wasting time
 298         Alias /content/ /home/USERNAME/webapps/osqa_server/projects/MYOSQA/templates/content/
 299         Alias /forum/admin/media/ /home/turian/envs/osqa/lib/python2.5/site-packages/django/contrib/admin/media/
 300         #AliasMatch /([^/]*\.css) /home/USERNAME/webapps/osqa_server/projects/MYOSQA/templates/content/style/$1
 301         <Directory "/home/USERNAME/webapps/osqa_server/projects/MYOSQA/templates/content">
 302         #    Order deny,allow
 303         #    Allow from all
 304         </Directory>
 305
 306     If you want virtual hosts of the admin interface under HTTPS, please
 307     look at OSQA's install file.
 308
 309     Create osqa.wsgi and edit it:
 310         cp osqa.wsgi.dist osqa.wsgi
 311
 312     Edit  ~/webapps/osqa_server/projects/MYOSQA/deploy/osqa.wsgi as follows::
 313
 314         import os
 315         import sys
 316
 317         # redirect sys.stdout to sys.stderr for bad libraries like geopy that uses
 318         # print statements for optional import exceptions.
 319         sys.stdout = sys.stderr
 320
 321         from os.path import abspath, dirname, join
 322         from site import addsitedir
 323
 324         # add the virtual environment site-packages to the path
 325         from site import addsitedir
 326         addsitedir('/home/USERNAME/envs/osqa/lib/python2.5/site-packages')
 327
 328         sys.path.insert(0, abspath(join(dirname(__file__), "../")))
 329         sys.path.append(abspath(dirname(__file__)))
 330
 331         from django.conf import settings
 332         os.environ["DJANGO_SETTINGS_MODULE"] = "MYOSQA.settings"
 333
 334         #print sys.path
 335
 336         from django.core.handlers.wsgi import WSGIHandler
 337         application = WSGIHandler()
 338
 339 And then you're up and running with:
 340
 341     ~/webapps/osqa_server/apache2/bin/stop
 342     ~/webapps/osqa_server/apache2/bin/start
 343
 344 You should log in to the admin interface (http://DOMAIN.com/admin/),
 345 and go to "Sites > Sites", and change the domain name that is used in
 346 all emails.