Installing the Troop 89 Website¶
This guide assumes that you already have Python installed. At the time of this writing, the troop 89 website requires Python 3.6 or greater.
Getting a local copy of the troop 89 website running is a fairly simple process, though there are several steps. This guide is intended to be especially detailed so that it may serve as a partial reference for future webmasters in training.
Fetching the Source¶
The easiest way to get a copy of the troop 89 website source is by cloning the public github repository. This has the added benefit of integrating git into your development environment, which will be necessary if you intend on making changes to the website’s source.
$ git clone git://github.com/blueschu/troop89medfield.org.git $ cd troop89medfield.org
Installing the Dependencies¶
You will need to create a virtual environment for Python libraries. If you are using Python3.6+ (which you should be), the tools needed to create virtual environments ship with the interpreter as the venv module.
Third party packages for creating virtual environments also exist. Some popular options are the virtualenv and virtualenvwrapper packages, which preceded the standard venv module and provide additional convenience tools. Both of these packages can be installed with pip, and can be freely used inplace of the venv module in the following instructions.
To install the site dependencies, execute the following:
$ python3 -m venv troop89_venv # Create a virtual environment in the folder 'troop89_venv' $ source troop89_venv/bin/active # Active the virtual environment $ pip install -r requirements/dev.txt # Install the development dependencies
On Windows, run
venv\Scripts\activate.bat in place of
Compiling the Stylesheets¶
The stylesheets for our website are written in sass, an extension language to css. You can either install sass system wide, use a feature in your IDE (if one is offered), or you can use the Python libsass package. Regardless of what method you use, you want to compile all the files in
assets/scss/*.scss that don’t begin with an underscore to
If you have already installed the site dependencies (Installing the Dependencies), you will have the libsass package in your virtual environment, which provides the
sassc utility. With this program on your path (which will be the case if you have activated the virtual environment), you can run the following script to compile the stylesheets.
Adding the Configuration File¶
You will need to create a file called
.secrets.json in the root directory of the project sources. This is a config file that stores sensitive information such as database credentials and encryption keys.
An example configuration is located in the
demo.secrets.json file, which you can temporarily copy to get the site running:
$ cp demo.secrets.json .secrets.json
This file includes the credentials for an SQLite database, which is a single-file based relational database that ships with Python. Before beginning significant development, you should install and configure a PostreSQL database (for which the site is designed) and substitute its credentials into
.secrets.json. See Database Configuration for more details.
Initializing the Database¶
Assuming all configurations are good, you should only need to run
$ ./manage.py migrate
This will create the necessary tables and relations, but will not populate the database with data.
Populating the Database¶
The Troop 89 website ships with some default data to populate the database. This data is provided using Django fixtures, which are contained in the
To load the default hostnames for the
django.contrib.sites app, run
$ ./mange.py loaddata ./fixtures/sites.json
To load the demo flatpages, run
$ ./mange.py loaddata ./fixtures/demo_flatpages.json
Creating the Django Superuser¶
Run the following command
$ ./manage.py createsuperuser
and follow the prompts. This will create a user instance in the database that has all possible site privileges. You will need this to access the site admin.
Collecting the Static Media¶
$ ./manage.py collectstatic
This will collect the static files and media from across the project into a single directory (
./static/) so that they can be served by the web server. See the django staticfiles docs for more information
Updating Local Hostnames (Optional)¶
If you would like to use a host name (e.g. troop89.localhost) in place of a numeric IP (e.g. 127.0.0.1) when accessing the development site, you will want to update your machines hostname configuration. For Unix system (MacOS, Linux, etc), add the following entry to your
Note that the
.localhost TLD is reserved for loop back addresses of this sort. In fact, some browsers will treat
.localhost domains as loop back addresses even without a DNS configuration or modified
Running the Server¶
The following instructions are for development only. For production, a fully fledged HTTP server such as Apache or Nginx should be used in place of the lightweight server that ships with Django. See the Django runserver docs for more information.
To run the testing server, simple run
$ export DJANGO_SETTINGS_MODULE=troop89.settings.dev # Use the development settings. Run once per session. $ ./mange.py runserver
If you updated your hosts files to include a local hostname, you can run the following instead
$ ./manage.py runserver troop89.localhost
Do note that by default, the production setting will be used (as defined in
troop89/wsgi.py). To run the development flavor, set the environment variables
troop89.settings.dev. This can be done by modifying your
~/.bashrc file (to set it every time you begin a new bash session), by running
export DJANGO_SETTINGS_MODULE=troop89.settings.dev in your terminal (as in the commands above), or by preceding the run server command itself with