Getting Started

Contents

1. Requirements
2. Python Environment
   • conda
   • venv
   • requirements.txt
3. Environment Variables
4. Running the Development Server
   • Database
   • Database Migrations
   • Cache
   • Running the Dev Server
   • Creating Users Locally
     1. Adding Additional Users
     2. Giving a user a profile
5. File Structure
   • Templates and Creating Static Files

Requirements

• Python 3.8 or higher
• Docker
• Docker Compose

Python Environment

For local development, create a Python virtual environment.

Conda

We recommend you use Anaconda (or Miniconda), as it makes managing virtual environments with different Python versions easier:

$ conda create -n hackathon_site python=3.8

This will create a new conda environment named hackathon_site (you may choose a different name). Then, activate the environment:

$ conda activate hackathon_site

venv

Alternatively, you can use venv provided under the standard library, but note that you must already have Python 3.8 installed first:

$ python3.8 -m venv venv

How you activate the environment depends on your operating system, consult the docs for further information.

Installing Requirements

Install the requirements in hackathon_site/requirements.txt. This should be done regularly as new requirements are added, not just the first time you set up.

$ cd hackathon_site
$ pip install -r requirements.txt

Environment Variables

In order to run the django and react development servers locally (or run tests), the following environment variables are used. Those in bold are required. We recommend creating a simple bash script (called env_vars.sh for example) with an export VAR=VALUE for variable and just running source env_vars.sh when developing.

Variable	Required value	Default	Description
DEBUG	1	0	Run Django in debug mode. Required to run locally.
SECRET_KEY	Something secret, create your own	None	Secret key for cryptographic signing. Must not be shared. Required.
DB_HOST		127.0.0.1	Postgres database host.
DB_USER		postgres	User on the postgres database. Must have permissions to create and modify tables.
DB_PASSWORD			Password for the postgres user.
DB_PORT		5432	Port the postgres server is open on.
DB_NAME		hackathon_site	Postgres database name.
REDIS_URI		172.17.0.1:6379/1	Redis URI. <host>:<port>/<database>.
REACT_APP_DEV_SERVER_URL	http://localhost:8000		Path to the django development server, used by React. Update the port if you aren't using the default 8000.

If you are using miniconda, you can add these to your environment such that each time you conda activate hackathon_site, the variables will be sourced as well. To do this run (while the hackathon_site environment is activated):

$ conda env config vars set DEBUG=1

where you can substitube DEBUG=1 for any environment variable you desire.

Testing

Specifying SECRET_KEY is still required to run tests, because the settings file expects it to be set. DEBUG is forced to False by Django.

In the GitHub action for Python tests, DEBUG is set to be 1. SECRET_KEY is taken from the DJANGO_SECRET_KEY repository secret. In order to run tests on a fork of this repo, you will need to create this secret yourself.

Running the development server

Database

Before the development server can be ran, the database must be running. This project is configured to use PostgreSQL.

You may install Postgres on your machine if you wish, but we recommend running it locally using docker. A docker-compose service is available in development/docker-compose.yml. To run all the services, including the database:

$ docker-compose -f development/docker-compose.yml up -d

To shut down the database and all other services:

$ docker-compose -f development/docker-compose.yml down

To run only the database service:

$ docker-compose -f development/docker-compose.yml up -d postgres

The postgres container uses a volume mounted to development/.postgres-data/ for persistent data storage, so you can safely stop the service without losing any data in your local database.

A note about security: by default, the Postgres service is run with trust authentication for convenience, so no passwords are required even if they are set. You should not store any sensitive information in your local database, or broadcast your database host publicly with these settings.

Database migrations

Migrations are Django's way of managing changes to the database structure. Before you run the development server, you should run any unapplied migrations; this should be done every time you pull an update to the codebase, not just the first time you set up:

$ cd hackathon_site
$ python manage.py migrate

Cache

This application also relies on a cache, for which we use Redis.

You may install Redis on your machine if you wish, but we recommend running it locally using docker. A Redis service is available in development/docker-compose.yml. To run all the services, including the database:

$ docker-compose -f development/docker-compose.yml up -d

To run only the redis service:

$ docker-compose -f development/docker-compose.yml up -d redis

If you run multiple instances of this application in production using Redis through Docker (perhaps in Swarm mode), you should make sure that the Redis databases used between applications do not conflict. The easiest way to do this is to change the database id in the Redis URI environment variable, eg to 172.17.0.1:6379/2.

Run the development server

Finally, you can run the development server, by default on port 8000. From above, you should already be in the top-level hackathon_site directory:

$ python manage.py runserver

If you would like to run on a port other than 8000, specify a port number after runserver.

Creating Users Locally

In order to access most of the functionality of the site (the React dashboard or otherwise), you will need to have user accounts to test with.

To start, create an admin user. This will give you access to the admin site, and will bypass all Django permissions checks:

$ python manage.py createsuperuser 

Once a superuser is created (and the Django dev server is running), you can log in to the admin site at http://localhost:8000/admin. Note that creating a superuser does not give it a first or last name, so you should set those from the admin site otherwise some parts of the site may behave weird. Our regular sign up flow also assumes that username and email are the same, so we recommend creating your superuser accordingly.

Adding additional users

The easiest way to add new users is via the admin site, through the "Users" link of the "Authentication and Authorization" panel. When adding a user, you will be prompted for only a username and a password. The react site uses email to log in, so make sure to click "Save and continue editing" and add a first name, last name, and email address.

Giving a user a profile

Profiles are used by participants who have either been accepted or waitlisted. Some features of the React dashboard require the user to have a profile. This can be done through the "Profiles" link of the "Event" panel on the admin site. Click "Add profile", select a user from the dropdown, either add them to an existing team (if you have any) or click the green "+" to create a team, pick a status, fill out any other required fields, and click save.

File Structure

The top level hackathon_site folder contains the Django project that encapsulates this template.

The main project configs are in hackathon_site/hackathon_site, including the main settings file settings/__init__.py and top-level URL config.

The dashboard app contains the React project for the inventory management and hardware sign-out platform.

The event app contains the public-facing templates for the landing page.

The registration app contains models, forms, and templates for user registration, including signup and application templates. Since these templates are similar to the landing page, they may extend templates and use static files from the event app.

Templates and Creating Static Files

Templates served from Django can be placed in any app. We use Jinja 2 as our templating engine, instead of the default Django Template Language. Within each app, Jinja 2 templates must be placed in a folder called jinja2/<app_name>/ (i.e., the full path will be hackathon_site/<app_name>/jinja2/<app_name>/). Templates can then be referenced in views as <app_name>/your_template.html.

Static files are placed within each app, in a folder named static/<app_name>/ (same convention as templates). For example, SCSS files for the Event app may be in hackathon_site/event/static/event/styles/scss/. They can then be referenced in templates as <app_name>/<path to static file>, for example event/styles/css/styles.css (assuming the SCSS has been compiled to CSS).

To compile the SCSS automatically when you save, run following task running while you work:

$ cd hackathon_site
$ yarn run scss-watch

To compile all SCSS files at once, run:

$ yarn run scss

Django can serve static files automatically in development. In a production environment, static files must be collected:

$ python manage.py collectstatic

This will place static files in hackathon_site/static/. These must be served separately, for example using Nginx, as Django cannot serve static files in production. Read more about how Django handles static files.