language-learning

Setup Prerequisites

• Python 3.10+
• Node.js 22+

---

Setup Instructions

The service can be run via docker containers or manually. It is recommended to use Docker. (Both were tested on macOS and should therefore also work for Linux devices as well, no idea about Windows)

Run Containers with Docker

The whole service can be run in docker containers. For this, Docker, as well as docker compose, have to be installed. Then open a new terminal session and navigate to the root folder (most likely language-learning). After that, copy the following command into the terminal to build and run the docker containers as they are defined in compose.yaml:

    docker compose up --build

In your browser of choice, navigate to the host address (http://localhost:8000), and you should see the landing page. For an overview of the available routs, visit the treafic dashboard (http://localhost:8080/dashboard/).

---

For Debugging

Here is a collection of further docker commands that were useful for debugging the application.

Close the container

  docker compose down

Starting a single container

  docker compose up --build [container name]

Restart a container

  docker compose restart [container name]

View running containers

  docker compose ps

Connect to the database

  docker exec -it database psql -U user database

---

Manual Execution

As said before, it is recommended to use the docker containers.

1. Backend

Install the required packages and run the application using fastAPI. So, while in the root directory, copy the following commands into your console:

  pip install -r backend/requirements.txt
  fastapi dev backend/app/main.py

The backend will be running at http://127.0.0.1:8000.

Using a virtual environment for Python

If you want to use a virtual environment for Python, first check if there is one available or use

  python -m venv backend/.venv

to create one. Then check, if the right environment is used with

  which python

If it is the wrong one (or non is specified), set the environment with the following command (assuming you are in the root folder)

  source backend/.venv/bin/activate

---

2. Frontend

From the project root, use the following to install and run the frontend:

    npm --prefix ./frontend install
    npm --prefix ./frontend run dev

The frontend will be running at http://localhost:5173.

---

Environment Variables

To generate a secure SECRET_KEY for your .project.env file, run:

python -c "import secrets; print(secrets.token_hex(32))"

Set the ALGORITHM to HS256 (recommended).