diff --git a/backend/README.md b/backend/README.md index 3ac95fbc..ae44afe5 100644 --- a/backend/README.md +++ b/backend/README.md @@ -2,7 +2,26 @@ CHAOS' backend is implemented in Rust and for data persistence, we use PostgreSQL. +## Table of Contents + +- [Dev Setup](#dev-setup) +- [Code Structure](#code-structure) +- [Tech Stack](#tech-stack) + + +## Dev Setup + +To run the backend in a dev/testing environment: +1. Install `docker-compose` (see [official installation guide](https://docs.docker.com/compose/install/)). +2. Navigate to the directory this file is in (`backend`) in your terminal (not `backend/server`). +3. Possibly terminate any running instances of postgres, as the dockerized postgres we will spawn uses the same default port, so the two might interefere with each other. +4. Run `./setup-dev-env.sh` (you might have to make it executable before with `chmod +x setup-dev-env.sh`), which should drop you into a new shell that has the required tools installed. +5. Now, you can `cd server` and should be able to `cargo build` successfully. +6. Once you exit out of the newly created shell (e.g. type `exit`, or kill the terminal), the dockerized postgres instance should automatically be torn down, so it's not unnecessarily running in the background all the time. + + ## Code Structure + ### Service The service module contains all functions that conduct business logic, and also interact with the database. This separation from the request handling makes it easy to swap out any new form of requests, but reuse the same business @@ -27,6 +46,7 @@ Request -> Middleware (optional) -> Handler -> Service -> Middleware (Optional) ## Tech Stack + ### Web Server - [Axum](https://github.com/tokio-rs/axum) diff --git a/backend/setup-dev-env.sh b/backend/setup-dev-env.sh new file mode 100755 index 00000000..d7257648 --- /dev/null +++ b/backend/setup-dev-env.sh @@ -0,0 +1,75 @@ +#!/bin/sh + +# Drop the caller into a new shell that has the required dependencies, namely +# postgres and sqlx, installed and running. This is required because the Rust +# backend can only be built and run if the database is also running, due to +# sqlx. + +# Create .env file. +env_file=.env +if [ -f "$env_file" ]; then + while true; do + printf "You already have a $env_file file, are you sure you want to continue, as this will override your $env_file file? [yn] " + read -r answer + case "$answer" in + y) + # Continue with execution. + break + ;; + n) + echo "Aborting" + exit 0 + ;; + *) + # Try again. + echo "Invalid answer. Please type either 'y' for yes, or 'n' for no." + continue + ;; + esac + done +fi + +echo "Overwriting $env_file file" + +cat << 'EOF' > "$env_file" +DATABASE_URL="postgres://user:password@localhost:5432/chaos" +JWT_SECRET="test_secret" +GOOGLE_CLIENT_ID="test" +GOOGLE_CLIENT_SECRET="test" +GOOGLE_REDIRECT_URI="http://localhost:3000/auth/callback" +S3_BUCKET_NAME="chaos-storage" +S3_ACCESS_KEY="test_access_key" +S3_SECRET_KEY="test_secret_key" +S3_ENDPOINT="https://chaos-storage.s3.ap-southeast-1.amazonaws.com" +S3_REGION_NAME="ap-southeast-1" +EOF + +# Install sqlx if it isn't installed yet. +if ! which sqlx >/dev/null; then + echo "Installing sqlx" + cargo install sqlx-cli --no-default-features --features native-tls,postgres +else + echo "sqlx already installed" +fi + +# Run postgres database in the background. +this_script_dir="$(dirname "$(realpath "$0")")" +docker_compose_file_name="setup-test-database.yml" +docker_compose_file_path="$this_script_dir/$docker_compose_file_name" + +echo 'Starting up postgres database in docker' +docker-compose -f "$docker_compose_file_path" up --detach + +# Ensure the docker container gets killed once this script exits. +trap 'echo "shutting down $docker_compose_file_path" && docker-compose -f "$docker_compose_file_path" down' EXIT + +# Wait for the database to be ready. +echo "Waiting for database to be ready" +sleep 3 + +# Setup sqlx. +echo "Setting up sqlx" +sqlx database create +sqlx migrate run + +"$SHELL" diff --git a/backend/setup-test-database.yml b/backend/setup-test-database.yml new file mode 100644 index 00000000..d30d0b4e --- /dev/null +++ b/backend/setup-test-database.yml @@ -0,0 +1,17 @@ +# Run `docker-compose -f setup-test-database.yml up` + +services: + database: + # Official Postgres image from DockerHub. + image: 'postgres:16' + + # By default, a Postgres database is running on port 5432, so make that port accessible from outside of the container. + ports: + - 5432:5432 + + environment: + # Username and password to access database. + POSTGRES_USER: user + POSTGRES_PASSWORD: password + # Name of the database. + POSTGRES_DB: chaos