-
Notifications
You must be signed in to change notification settings - Fork 1
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-24.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.
sudo apt install python3.13 python3-pip(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.
To install follow their guide.
To run commands with the virtual environment uv makes for you, just prepend all commands with uv run ....
(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.
# Make sure to clone this repo where you can find it later
git clone git@github.com:CSSS/csss-site-backend.gitHere 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. Please not we are using postgres 16, 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 -adocker run --name csss-site-postgres -e POSTGRES_HOST_AUTH_METHOD="trust" -p 5444:5432 -d postgres:16docker 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>"'
exitNote: This part of the guide was from the previous version of this guide, but has not been tested yet
If you don't have a local install of postgres, follow the guide for your operating system.
# 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-16 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
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>"'
# add test db (for unit tests)
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>"'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).
alembic --version
# 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/project/src
python load_test_database.py# 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. If using Docker
export DB_PORT=5444
sudo service docker start
docker start csss-site-postgres
# 4. Populate the database
python ./src/load_test_db.py
# 5. Run the web server
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