Local Setup

First Time Setup

To run the csss-site-backend locally, you'll want to install everything, load a test database, then serve over localhost. You can test things by making requests to localhost & checking that responses are valid. If you're on mac/linux this should work by default, if you're on windows you can do all of this in wsl.

The following steps will help you set this up on WSL2 on Windows. Mac/Linux should be very similar.

# 0. setup a folder
mkdir csss-site-new
cd csss-site-new

# 1. clone this repo
git clone https://github.com/CSSS/csss-site-backend.git

# 2. get dependencies (we use python 3.11, but other versions might work...). 
sudo apt install python3.11 python3.11-venv -y # the default on debian 12

# 3. create a python virtual environment (or just wing it)
python3.11 -m venv .venv
source .venv/bin/activate

# 4. install required python libraries
# NOTE: you may need to install some dependencies? Not sure
cd csss-site-backend
python3.11 -m pip install -r requirements.txt
# setup the ruff pre-commit hook which will format & lint your code automagically! (or not, it's annoying...)
# python3.11 -m pre-commit install

# 5. setup postgresql - there are two options (docker or local install), see below under Database Setup

# 6. run database migrations to setup the schema
cd src
# if you're running postgres in docker, export the port number as DB_PORT
export DB_PORT=5444
# if you want to switch to local postgres, you can remove the environment variable
# unset DB_PORT 
alembic --version
# this updates the database schema to the most recent one. Do this every time you git pull new changes
alembic upgrade head

# 7. run it
export LOCAL=true
gunicorn main:app --worker-class=uvicorn.workers.UvicornWorker

# 8. open a new terminal window & go to localhost:8000
# (if this hangs, make sure your xlaunch config is running on windows)
google-chrome

Installing python3.11 from source (reference) (may not work on all wsl distributions)

sudo apt update && sudo apt upgrade
sudo apt install wget build-essential libncursesw5-dev libssl-dev libsqlite3-dev tk-dev libgdbm-dev libc6-dev libbz2-dev libffi-dev zlib1g-dev  
 
cd ~
wget https://www.python.org/ftp/python/3.11.8/Python-3.11.8.tgz 
tar xzf Python-3.11.8.tgz
rm Python-3.11.8.tgz

cd Python-3.11.8
./configure --enable-optimizations 
sudo make -j 4
sudo make altinstall
sudo ln -s ~/Python-3.11.8/python3.11 /usr/bin/python3.11

Installing python3.11 via homebrew

brew install python@3.11

Database Setup

In order to do anything interesting you're going to need a database to interact with.

Install Postgres - Docker

If you don't want to mess up your local install, you can install the postgres database in a docker container.

# 1. install docker
# see https://docs.docker.com/desktop/wsl/ for wsl
# for wsl, you may also have to start the docker daemon in a non vs-code terminal (not fully sure why, but it works...)
sudo service docker start
# check docker is working
docker ps -a

# 2. run the latest postgres container with no password (no important information in your local database)
docker run --name csss-site-postgres -e POSTGRES_HOST_AUTH_METHOD="trust" -p 5444:5432 -d postgres:16

# 3. enter the container & setup the db
docker exec -it csss-site-postgres bash
psql --version
su postgres
createdb --no-password main
createuser --no-password <your-username>
psql --command='GRANT ALL PRIVILEGES ON DATABASE main TO "<your-username>"'
psql main --command='GRANT ALL ON SCHEMA public TO "<your-username>"'
exit

Install Postgres - Locally

If you don't have a local install of postgres, you can do the following:

# get the official apt repository for postgresql
sudo sh -c 'echo "deb https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt-get update
sudo apt-get install postgresql-15 postgresql-contrib

# for WSL users only (windows)
# sudo service postgresql status
# sudo passwd postgres # optional: choose a password
# sudo service postgresql start

# setup your account & the "main" database (the db that our server uses for most things)
psql --version
sudo -i -u postgres
createdb --no-password main
createuser --no-password <your-username>
psql --command='GRANT ALL PRIVILEGES ON DATABASE main TO "<your-username>"'
psql main --command='GRANT ALL ON SCHEMA public TO "<your-username>"'

Second Time Setup

# 1. activate environment
cd csss-site-new
source .venv/bin/activate
cd csss-site-backend

# 2. run it
cd src
export LOCAL=true
export DB_PORT=5444
docker start csss-site-postgres
gunicorn main:app --worker-class=uvicorn.workers.UvicornWorker