Setup

Web development is fiendishly complex. There is code, tools for managing code, and tools for managing tools.

Prerequisites

These are the software you are required to download and install. Unless noted, default settings are OK. Consult with officers on advice for preferences of certain settings.

There are other ways to install the following items. The instructions here will provide the EASIEST and SUFFICIENT way to install them. Ultimately, it is up to you on how to get them and install them if you want to do a more centalized way (i.e. Chocolatey for Windows) or a fancy pants method (i.e. Build from Scratch).

When Unix is used, it includes (not limited to) Linux, Windows WSL, and MacOS. For obvious reasons, it doesn't include Windows.

• git and Terminal
  • Unix systems usually have these out of the box
    • Default terminal usually zsh or bash
  • [Windows] git bash ONLY (due to Makefile syntax)
    • You can use the default options, with one exception: Select Use Windows' default console window in the Configuring the terminal emulator to use with Git Bash step. Do not use "MinTTY".
      • This is very important! If you do not select this option, your terminal won't work with Python!
      • If you already have Git Bash installed before, just redownload and rerun the EXE (no need to uninstall, but you may if you want or need to) and go through all the options (it should keep what you previously selected). On the Configuring the terminal emulator page, select Use Windows' default console window.
• Miniconda (or Anaconda) + Python 3.7.3
  • Our server will also use Miniconda to allow for some flexibility in installing packages without having to wait for OCF to install them for us, like upgrading the Python version. As of Spring 2023, we currently use Python 3.7.3.
  • Install instructions here: Setup Conda Environment
  • Commands Summary:
    • Initial setup: conda env create -f config/tbpweb-dev.yml, uses a yml Conda environment configuration file to set up a tbpweb-dev environment (from environmental variables to Python Pip packages)
    • Activate the conda environment with conda activate tbpweb-dev (do this every time you start developing on tbpweb)
    • Deactivate conda environment with conda deactivate
    • Remove the conda environment with conda env remove -n tbpweb-dev
    • Disable automatic base environment activation with conda config --set auto_activate_base false
• Ruby (OCF uses 2.7.7, but we can use 3.1.X)
  • Windows should use Ruby+Devkit
  • Install "Compass": gem install compass -v 1.0.3
  • Only purpose is to support the Compass Sass library that is in Ruby
  • DO NOT install Ruby 3.2.X or beyond that, for "compass" compatibility. MacOS can install Ruby via Homebrew by: brew install ruby@3.1

Instructions

Create a fork of the program

Once you've installed and setup the above programs, clone the forked repository to your computer:

git clone https://github.com/GITHUB_USERNAME/tbpweb

Then, with a terminal, cd into your newly cloned repository:

cd tbpweb

Developing on tbpweb requires a virtual environment so that every developer has the exact same development environment (i.e. Any errors that a developer has is not due to a difference in configuration). We will be using Conda Environments to make our virtual environment.

Others exist like Python's built-in venv, but we won't use that here

Create your Conda environment and install the Python Pip dependencies if you haven't done so already:

$ conda env create -f config/tbpweb-dev.yml

This will create a Conda environment with all the Python Pip packages to keep as a standard between development environments. You will only need to wait for setup once. In the future, you may turn it on with conda activate tbpweb-dev and it will already be setup.

There is one difference in the Conda environment between Production and Development is the TBPWEB_MODE variable. During Production, the Conda environment variable will have a production value. During Development, the Conda environment variable will have a dev value. Look in the config folder's dev and prod .yml files to see how they work.

If you need to create your Conda environment from scratch, this command creates our Conda Environment completely from scratch, simply run the command again

Next, we need to have our current terminal/shell use the Conda environment we just created. We do this through:

$ conda activate tbpweb-dev

In summary, the setup looks like:

$ cd tbpweb                                     # enter our main directory
$ conda env create -f config/tbpweb-dev.yml     # create our Conda Environment and install dependencies
$ conda activate tbpweb-dev                     # enter our Conda Environment
$ python manage.py makemigrations               # Create migrations files
$ python manage.py migrate                      # apply all database changes
$ python manage.py runserver                    # start local web server (127.0.0.1:8000)
$ conda deactivate                              # Exit the Conda Environment

Django will also require a working copy of MySQL (or MariaDB) for deployment. Development just needs SQLite3.

Development

To run the Django development server (which runs a web server locally), run

$ python manage.py runserver

which will make the web site available at http://127.0.0.1:8000.

You may also use python manage.py runserver 0.0.0.0:3000 to use http://localhost:3000 or http://0.0.0.0:3000

If you would like to access the admin interface in the local web server, run

$ python manage.py createsuperuser

You will be prompted for some login info, after which you should be able to access the admin interface with your super user credentials at http://localhost:3000/admin.

Usually, any differences in Python code behavior between the Operating Systems are rare. A good rule of thumb is that if you have to use any OS-dependent code, you should consult with someone to see if there are alternatives. However, Windows developers have the additional responsibility to make their code Linux-friendly (since our destination OS is Linux on OCF). Therefore, if there is an error on the code on Linux and not Windows, support on Linux takes precedence! Unix developers should also try to make their code Windows-friendly for Windows developers. Example with strftime ... Fixes made here

FAQ

This is a compilation of past errors and how they were solved.

Python won't load on Windows Git Bash

Git Bash's Terminal emulator should be Use Windows' default console window. Don't use MinTTY. Follow the instructions for reinstalling Git Bash in the Prerequisites section of this README.