To use Courant News, you’ll have to install it. Before that, we’ll need to install some other software which it relies upon. This guide will walk you through these steps, and point you to references where you can find more information where appropriate.
Courant News is written in the Python programming language, so the first order of business is installing Python itself. We recommend either version 2.5 or 2.6, due to compatibility concerns with some of the software that Courant News uses.
We do not currently support Python 3.0, as our primary dependency (the Django web framework) does not currently support it. When Django begins to support Python 3.0, we will evaluate the transition ourselves. Until then, you will be more than fine with Python 2.5 or 2.6
You can get Python at http://www.python.org. Most versions of Linux and Mac OS X come with Python pre-installed. To verify that you have Python installed, you can type python from a terminal or command-line program. You should see something like:
Python 2.5.2 (r252:60911, Oct 5 2008, 19:29:17)
[GCC 4.3.2] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>>
Courant News and other software projects rely upon certain tools to manage their code and collaboration between developers. Two of the popular tools are Subversion (svn) and Git. Although Courant News itself uses svn, a number of third-party libraries that we depend on use git.
To install svn, you can find an appropriate download at their download website. You can confirm that your installation has worked by running svn help at your terminal or command-line program.
Windows Note: While the popular TortoiseSVN is a useful GUI interface for Subversion, it will not install the necessary binaries and place them on your system path for the Courant installation to work. You must install the binary packages from the link above.
Similarly, you can install git by choosing the appropriate link at their download page. Windows users should probably choose the msysGit version. You can confirm that your installation has worked by running git at your terminal or command-line program.
Instructions can be found in the Django database installation documentation section. We strongly recommend the use of PostgreSQL, but most of the Courant News functionality has been tested against MySQL as well.
We’re finally ready to install Courant News itself, along with the other Python software that it runs on and with. To simplify the process, we have created a bootstrapping script to handle most of the process. The script creates a virtualenv directory into which everything will be installed. virtualenv isolates the software from the rest of your system, preventing conflicts with other Python software you may have installed, and allowing simple removal of the entire system by just deleting the virtualenv directory.
To get started, download the bootstrapping file from the Courant News source code repository: courant-boot.py. Save it to the directory where you would like Courant News to be installed; good candidates include your home directory, and /usr/local/ on *nix systems, but there are no real restrictions on where you put it.
In the following examples, we are going to install into a virtualenv called site-env (in the same directory where the courant-boot.py resides) and a site called mynews, but you can call them whatever you wish. The most common scenario for a beginner would be to start with the sample “default” project site that Courant News bundles. You will need to call the courant-boot script from the command line.
Windows Note: In Vista, for the courant-boot command to work, your command line window must be run as administrator.
To do this, run the following (after moving to the directory where you downloaded the courant-boot.py file):
python courant-boot.py site-env -n mynews -p default
This will create the virtualenv, install some support software, download the latest version of Courant News, download and install all third-party libraries (including Django and others), and make a fresh copy of the default project in the root of the site-env virtualenv.
The bootstrapping script takes a number of options to control its behavior. Running python courant-boot.py will give a full listing, including descriptions of each. Following are some of the most commonly used.
The -p parameter can be either the name of a bundled project template, as used above, or it can be a URL to a source code repository housing your site’s project code. We strongly recommend that organizations use a source control tool, and this parameter allows for easy integration:
python courant-boot.py site-env -n mynews -p svn://svn.mynews.com/trunk
The URL can be of any format supposed by pip, including Subversion, Git, Mercurial, and Bazaar repositories as of this time. The URL can also be a path to a directory on your computer, allowing you to link the Courant News virtualenv with code elsewhere on your computer that may be more convenient:
python courant-boot.py site-env -n mynews -p ~/mynews/trunk
Note: pip currently does not support repositories that require authentication. In cases where your project’s repository requires authentication to do a checkout, you will have to do the checkout manually. When pip supports authenticated checkouts, we will add support for such behavior.
The -r or --requirements flag allows you to enable the fetching of the external dependencies required for Courant News to operate properly. This flag is implicit and enabled by default, so you should never need to use it directly.
However, you may want to skip the fetching of these external requirements, as that may be a lengthy process. You can do so by passing the --skip-requirements flag:
python courant-boot.py site-env --skip-requirements
This is probably most useful when you wish to update to the latest version of Courant News or update your project’s code (by including the -n and -p parameters as seen above).
For those who want or need to work on the code of Courant News itself, the -c or --courant parameter allows you to specify a file path to where you have a copy of the Courant News repository checked out. This will create a link to that folder instead of creating and installed a bundled (Python egg) version, so that you can work on the code separately.
After installing Courant News and creating your site’s project, you will have to configure the site by modifying the settings file. If you started from one of the bundled project templates, you will find a settings file template in settings/local_settings.py.dist. You will want to make a copy of this file and save it as settings/local_settings.py.
Then open this file in your favorite text editor and tweak the settings as appropriate. Be sure to adjust the database settings. You can find more information regarding settings files in the Django documentation’s settings overview and settings reference.
You are now ready to build your news site. A tutorial covering the basics will be coming soon.