Skip to content

readme.md

Latest commit

 

History

History
135 lines (84 loc) · 5.5 KB

readme.md

File metadata and controls

135 lines (84 loc) · 5.5 KB

Couchers.org backend

This is the backend for Couchers.org built in Python. The React web frontend and React Native apps make API calls to it using gRPC which are defined via Protocol Buffers. The business logic manipulates a PostgreSQL database via SQLAlchemy. Geospatial features are provided by the PostGIS extension.

Readme last updated: 2025/01/12.

Quick Start

These instructions should work directly on Linux and macOS. If you are using Windows, please install Ubuntu via WSL2, then follow these instructions inside Ubuntu.

You need Docker engine installed. Please refer to the Docker install documentation for how to set it up.

Next, run the following commands to get the backend up and running:

## Check out the repo and navigate to the backend folder
git clone https://github.com/Couchers-org/couchers.git
cd couchers/app/backend
## Generate the autogenerated API definitions using protobuf and grpc
make protos

## Build and start the docker containers
docker compose up --build

This will spin up a complete copy of the database, backend, and proxies needed to run the platform inside Docker.

If this succeeds, the backend should come up and print some info logging every few seconds about background jobs. You should be able to navigate to http://localhost:8888/status and see some JSON indicating the backend is up.

This will not currently run the frontend, to do that, please follow the instructions in app/web/readme.md under Quick Start, then Running against a local backend.

Running tests in docker

You can run all backend tests in docker with the following commands:

cd app/backend

# Run all tests
make docker-test

# Or run a single file's tests
make docker-test file=test_filename.py

# Teardown the test database when done
make teardown-docker-test

Running the backend outside Docker

You can run the backend outside Docker and have it talk to the rest of the containerized services running inside Docker.

You'll need to install uv (a Python package/project manager) and sync dependencies before starting:

curl -LsSf https://astral.sh/uv/install.sh | sh
cd app/backend
uv sync

Then start a local backend with all dependencies (postgres, maildev, etc.):

make run

If you find that the proxy/media services can't talk to your local backend, try setting the BACKEND_HOST=host.docker.internal environment variable before running the services via docker compose.

Running under a debugger

Run dependencies with docker compose:

cd app/backend
make run-deps

Then execute app/backend/src/run_locally.py with your debugger of choice. It will have all the correct env variables and will connect to the services (db, etc.) running in docker.

Running tests outside Docker

cd app/backend

# Start the test database
make setup-db

# Now run the test against the testing postgres database
make test

# Or run a single file's tests, add your filename
make test file=[test_filename.py]

Q/A:

Q: I can't connect to the DB!

A: First doublecheck what port the DB is listening on - run docker compose up postgres and it should say something like listening on IPv6 address "::", port 6545. Then doublecheck you have the right password. There are TWO passwords - one for the test db and one for the normal db! See app/postgres.dev.env and app/postgres.test.env

Here is information for debugging the backend inside VS Code

Q: I'm seeing issues with migrations or the database not being up to date!

A: This happens when you either switch between branches that mutate the database or something else funny happens. The easiest way is to nuke the database:

  1. Stop postgres docker container
  2. Delete the postgres folder in app/data
  3. Re-run docker compose up --build

If you have any trouble, send Aapeli a message on Slack. He's more than happy to spend a bit of time helping you set things up!

Q: I'm having issues with proto protos!

A: Regenerate protos using

docker run --pull always --rm -w /app -v $(pwd):/app registry.gitlab.com/couchers/grpc ./generate_protos.sh

Q: How do I log in or sign up when developing?

A: If you are using the local backend, you can log in with the username "aapeli" and the password "Aapeli's password". This comes from the dummy data. For emails, see the next question.

If you are using the live dev api ("next"/staging), it will send you real emails so you can sign up. However, all links will point to next.couchershq.org. If you want to open them with the couchers frontend you are working on locally, change the links to http://localhost:3000/rest/of/the/url.

Q: How do I receive emails like the signup confirmation email in local dev?

A: We run MailDev with the docker compose setup: it will receive emails and let you browse them. To view emails, visit http://localhost:1080.