-
Notifications
You must be signed in to change notification settings - Fork 4
1. Local Setup
There are two different parts of the backend you'll need to set up: the server and the database. You'll need both to run the project.
To run csss-site-backend locally, you'll want to get the project running, load a test database, then serve it over localhost.
Areas marked (Recommended) are optional, but if you don't know what you're doing then it's okay to just follow it. If something is marked (Optional) then you should understand why it's suggested and then decide from there if you want to do it. TL;DR: Do recommended things, ask yourself if you want the optional things.
Our environment has not been set up to work with Windows natively. To avoid having to dual-boot your machine or switch to Linux you can run WSL2, which is sort of like a virtual machine for running the Linux kernel. To read more about installation follow this link below, or just use the command pasted below in an administrator-elevated PowerShell terminal.
wsl --install Ubuntu-26.04Once installed, you will follow the rest of the guide inside the WSL2 instance you just created.
The following instructions assume you're on a Debian-based Linux distro i.e. you're using apt. If you're using WSL2 this should work with Ubuntu.
You have an option here: you can install Python normally or you can use uv. Either one works, but when following this guide follow either the regular version or the uv version if there are instructions for both.
(Optional) Using `uv`
If you're familiar with Python virtual environments then uv might interest you. It automatically manages your virtual environment and different versions of Python so other projects can safely co-exist with this one. This means you don't need to download the correct version of Python or activate the virtual environment. To run commands with the virtual environment uv makes for you, just prepend all commands with uv run .... For example, instead of alembic upgrade head you would run uv run alembic upgrade head.
To install follow their guide.
# Only run these commands if you're NOT using uv
# This repository holds the version of Python you want to install
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.13 python3-pip python3.13-venv(Recommended) Using SSH over HTTPS
It's recommended to use SSH when cloning the repository to avoid having to type your password for GitHub whenever interacting with the remote repository. Follow this guide to set it up.
If you have not been added to the W3 organization yet you will not be able to push changes up. You'll need to fork the repository and clone your fork.
# Make sure to clone this repo where you can find it later
git clone git@github.com:CSSS/csss-site-backend.git # or your forkHere is where you install all the libraries our project uses. This will be done in a virtual environment to ensure other project dependencies don't mess with each other. If you want to know what we use look inside pyproject.toml under dependencies and project.optional-dependencies.
You have a couple of options here. If you have opted to use uv then skip to this section, otherwise ignore that section entirely.
# Make sure you're inside the repository
cd /path/to/csss-site-backend
# This creates the virtual environment
python3.13 -m venv .venv
# This activates the virtual environment
source .venv/bin/activate
# This will install all dependencies with both the `dev` and `test` modules
pip install ".[dev, test]"Only run this if you're using uv.
# Make sure you're inside the repository
cd /path/to/csss-site-backend
# This will install all dependencies with both the `dev` and `test` modules
uv sync --all-extrasThat's all server setup. We use pyright for type checking and ruff for linting. As the project matures, our pipeline will include the pyright check, but for now you can feel free to install it as a type checker while you work.
In order to do anything interesting you're going to need a database to interact with. There are two options to install the local database: Docker and locally. We recommend doing this in Docker, just so your database is isolated from any other projects that might use postgres. This setup still assumes you're in Linux or WSL2. We are using postgres 18, so make sure you're installing the correct version.
If you don't want to mess up your local install, you can install the postgres database in a docker container.
Install Docker however you want to use it, but these instructions will assume you are using it through the CLI i.e. not through Docker desktop. Ubuntu MacOS
Once installed, start the service.
sudo service docker start
# Check docker is working
docker ps -aIf you run into privilege issues when running docker ps -a then try using sudo. If you don't want to use sudo every time you want to check Docker then follow their post-install guide.
docker run --name csss-site-postgres -e POSTGRES_HOST_AUTH_METHOD="trust" -p 5444:5432 -d postgres:18docker exec -it \
-u postgres \
-e DB_USER="<your-username>" \
csss-site-postgres \
bash -c 'createuser --no-password "<your-username>" && createdb --owner="<your-username>" main'docker exec -it \
-u postgres \
-e DB_USER="$DB_USER" \
csss-site-postgres \
bash -c 'createuser --no-password "$DB_USER" && createdb --owner="$DB_USER" test'You can now exit the Docker container by using exit until you're back to your regular shell.
If you don't have a local install of postgres, follow the guide for your operating system.
You can check your installation by running
psql --versionsudo -u postgres createuser "<your-username>"
sudo -u postgres createdb --owner="<your-username>" mainsudo -u postgres createuser "<your-username>"
sudo -u postgres createdb --owner="<your-username>" testCreate a copy of .env.example called .env. They should be in the same folder.
These are the environment variables you'll need for the server to start:
ENVIRONMENT=dev
APP_URL=http://localhost:3049
COOKIE_SECURE=false
MEDIA_ROOT=local/path/to/media_root
MEDIA_BASE_URL=/media
# If and only if you're using Docker:
DB_PORT=5444is all you'll need.
We use alembic to manage our database versions. Think of it like git, but for our database schema. If you're running the database locally you can ignore the Using Docker section.
This runs the migration (sort of like a git pull).
# Make sure you have activated your virtual environment or are prepending alembic commands with `uv run` if you're using uv
alembic --version
# Other alembic commands needs to be run in the `src` directory
cd /path/to/csss-site-backend/src
# This updates the database schema to the most recent one. Do this every time you git pull new changes
alembic upgrade headcd path/to/csss-site-backend/src
python load_test_db.py # without uv
# or
uv run load_test_db.py # with uvOnce you've completed the server and database setup you should now be able to run the project locally.
pg_isready -h localhost -p `DATABASE_PORT`If it's not and you're using Docker, make sure it's on:
docker ps -a # Status should say "UP" on `csss-site-postgres`
# If it isn't turn the container on:
docker start csss-site-postgres# In `src`
# Start the backend
gunicorn main:app --worker-class=uvicorn.workers.UvicornWorker -b localhost:3049You should now be able to access the web server by checking localhost:3049 in your web browser.
# 1. (Using pip) Activate the environment
cd /path/to/csss-site-backend
source .venv/bin/activate
# 2. Ensure environment variables in `.env` are correct
ENVIRONMENT=dev # or test
# 3. (Using Docker) Run the database
sudo service docker start
docker start csss-site-postgres
# Make sure `DB_PORT` is set in your `.env` file
# DB_PORT=5444
# 4. (Recommended) Populate the database
python ./src/load_test_db.py # without uv
# or
uv run ./src/load_test_db.py # with uv
# 5. Run the web server
cd src
gunicorn main:app --worker-class=uvicorn.workers.UvicornWorker -b localhost:3049
# or
uv run gunicorn main:app --worker-class=uvicorn.workers.UvicornWorker -b localhost:3049