-
Notifications
You must be signed in to change notification settings - Fork 2
1. (WIP) 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 17, 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:15docker exec -it csss-site-postgres bash
psql --version
su postgres
createuser --no-password <your-username>
createdb --no-password main
psql --command='GRANT ALL PRIVILEGES ON DATABASE main TO "<your-username>"'
psql main --command='GRANT ALL ON SCHEMA public TO "<your-username>"'createdb --no-password test
psql --command='GRANT ALL PRIVILEGES ON DATABASE test TO "<your-username>"'
psql test --command='GRANT ALL ON SCHEMA public TO "<your-username>"'
exitYou 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 --version# Log in as the admin "postgres"
sudo -i -u postgres
createuser --no-password <your-username>
createdb --no-password main
psql --command='GRANT ALL PRIVILEGES ON DATABASE main TO "<your-username>"'
psql main --command='GRANT ALL ON SCHEMA public TO "<your-username>"'createdb --no-password test
psql --command='GRANT ALL PRIVILEGES ON DATABASE test TO "<your-username>"'
psql test --command='GRANT ALL ON SCHEMA public TO "<your-username>"'
exitYou can now exit until you've reached your regular shell.
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.
# Export an environment variable so the project knows which port to use when accessing the database. Not needed if running locally.
export DB_PORT=5444This 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 headOnce you've completed the server and database setup you should now be able to run the project locally.
export LOCAL=true # Yeah, I know, it's confusing to have this named LOCAL, even when using Docker
# (Recommended) Populate the test database with stuff
cd path/to/csss-site-backend/src
python load_test_db.py # without uv
# or
uv run load_test_db.py # with uv# 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. Activate environment (if using pip and venv)
cd /path/to/csss-site-backend
source .venv/bin/activate
# 2. Export environment variable
export LOCAL=true
# 3. (Optional) If you're using Docker
export DB_PORT=5444
sudo service docker start
docker start csss-site-postgres
# 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:3049Below is stuff that has to be verified once the project requires them.
# 1. activate environment
source .venv/bin/activate
cd csss-site-backend
# 2. run it
cd src
export LOCAL=true
export DB_PORT=5444
# go to https://discord.com/developers/applications & create a new bot for testing purposes
# go to the Bot tab, then reset your token
export DISCORD_TOKEN="<input-token-here>"
# reach out to an admin & give them your "Client ID" to get your bot access to the server
# the admin will enter https://discord.com/api/oauth2/authorize?client_id=<your-client-id>&permissions=17180460032&scope=guilds+bot+guilds.members.read+messages.read+guilds.channels.read+identify+email+dm_channels.read+relationships.read+applications.builds.read+presences.read+dm_channels.messages.read
# which will give your app (mostly) read-only permissions, limiting potential damages
docker start csss-site-postgres
# python load_test_db.py
gunicorn main:app --worker-class=uvicorn.workers.UvicornWorker -b localhost:3049...
export GITHUB_TOKEN="github_pat_<token-contents>"
...make sure you have the google_key.json