Home

Welcome! This is the in-progress website redesign for the IEEE-Eta Kappa Nu (HKN) University of California, Berkeley Mu Chapter, built with Django, Django REST framework, and Vue.js.

• If you are new to development, check out the Git tutorial.
• If you are new to web development, check out the HTML and CSS tutorials.
• If you are new to Django, check out the Django tutorial.
• If you are new to hknweb, check out the Setup, Development, and Layout sections and the Contribution Procedure page.
• If you are maintaining hknweb, check out the Deployment and Production maintenance sections and the Miscellaneous page.

For more information, contact compserv@hkn.eecs.berkeley.edu.

Setup

We use any sh shell e.g. bash, zsh, etc.

If conda is not already available, install conda. If you're installing conda for the first time, we recommend Miniconda over Anaconda.

# Once `conda` is installed
$ conda env create -f config/hknweb-dev.yml         # Create dev environment
$ conda activate hknweb-dev                         # Activate dev environment
$ python manage.py migrate                          # Initialize database
$ python manage.py init_permissions                 # Provision database with default permissions

Development

All commands we use are native to Django link to available Django commands. If you haven't worked with Django before, checkout the Django tutorial.

A few frequently used commands:

$ python manage.py makemigrations       # Create migrations files
$ python manage.py migrate              # Apply migrations files to database
$ python manage.py createsuperuser      # Create an admin super user to login as 
$ python manage.py runserver            # Run development server
$ coverage run                          # Run tests
$ coverage report                       # Report test coverage

Layout

Where can I find what I'm looking for?

Path	Description
.github/workflows	Github actions config
config	General non-python hknweb config files
keyrings/live	GPG keyring, for authorizing access to encrypted secrets (Production Server Only)
LICENSE	Legal license: open source, enforced by law
bbtest.txt.gpg	blackbox test file
fabfile.py	Fabric deployment scripts
manage.py	Django task runner
pyproject.toml	Project maintenance config
run	The production run script

Production maintenance

Here are a few handy commands for maintainers:

# SSH into prod
ssh hkn@apphost.ocf.berkeley.edu

# cd into hknweb production
cd hknweb/prod/current

# Activate prod environment
conda activate hknweb-prod

# Open a Django shell
python manage.py shell

# Open a Django direct SQL database interface
python manage.py dbshell

Deployment

Our deployment pipeline deploys from compserv/master to OCF servers using fabfile.py.

# Activate our dev environment
conda activate hknweb-dev

# Depending on your ssh setup, this may or may not work for you:
HKNWEB_MODE="prod" fab deploy

# If your SSH key to the apphost requires a password to unlock:
HKNWEB_MODE="prod" fab --prompt-for-passphrase deploy

# If you have no SSH key to the apphost (shame on you), and require password authentication:
HKNWEB_MODE="prod" fab --prompt-for-login-password deploy

Rollback to Past Version

HKNWEB_MODE="prod" fab rollback --release <Timestamp of Folder>

where the <Timestamp of Folder> is the timestamp folder you want to rollback to in ~/hknweb/prod/releases/ (you don't need the full path, just the name of the specific folder inside the "releases" folder).

Credits

The documentation on this wiki is largely written by @jameszhu and @ochan1. Thanks for their efforts at making compserv renewable!