update dev containers documentation

DEV_ENVIRONMENT.md

@@ -0,0 +1,46 @@
+# Gradesa Development Environment
+
+## Overview
+
+The current setup uses a container as a fully-fledged development environment. This ensures that:
+
+- Everyone works with the same tools and versions.
+- Only Docker or Podman needs to be installed (in theory, even Git is optional).
+
+In other words, the docker-compose.yml file starts the **development environment**, not the application itself.
+
+## Containers
+
+- **node-dev-env**: This is the main development environment. It’s based on a standard Node.js Debian image with an added PostgreSQL CLI client (psql). When you start the container, the project’s root directory is mounted inside the container (/host), giving you full access to your code. To open a shell inside the container, run `$ docker exec -it node-dev-env bash` (replace docker with podman if you’re using Podman). From here, you can run commands like:
+
+  - Start the app: `$ npm run dev`
+  - Update dependencies: `$ npm audit fix`
+
+  All changes inside the container are reflected in your local project files.
+
+- **gradesa-db & gradesa-pgtestdb**: These containers run the application’s databases:
+  - gradesa-db is for local development and testing.
+  - gradesa-pgtestdb is for automated tests.
+
+## VS Code Debugger
+
+You can use VS Code’s integrated debugger by connecting your editor to the node-dev-env container via the Dev Containers extension.
+
+**Steps**:
+
+- Start the containers using docker-compose or podman-compose.
+- Attach VS Code to the node-dev-env container.
+- Configure a valid launch.json file (search online for examples).
+
+Once set up, you can debug your app directly from VS Code.
+
+## Why Podman / Rootless Docker?
+
+The main reason is file ownership when sharing volumes. Users inside the container differ from users outside. For example:
+
+- Inside the container, you’re root.
+- Outside, files created by root inside the container appear as owned by the Docker daemon user (often root), which can clutter your home directory with root-owned files.
+
+Podman and rootless Docker solve this by running the daemon as your normal user. This way, files created inside the container appear as owned by your regular user outside.
+
+(In theory, you could avoid volume sharing and clone the project each time inside the container, but that’s not recommended 😀)

README.md

@@ -4,9 +4,7 @@ GRADESA is a freely accessible website where language learners at language centr
 
 ## Prerequisites
 
-- **Node.js**: v20 or higher (included in the dev container)
+- **Rootless container runtime**: Docker (rootless) or Podman with compose support
-- **npm**: v10.2.4 or higher (included in the dev container)
-- **Container runtime**: Docker or Podman with compose support
 
 ## Install
 
@@ -26,9 +24,7 @@ To be able to use the container-based development environment, you need to be ab
 
 If you encounter permission issues, see the explanation section below about rootless containers.
 
-### Explanation
+For deeper explanation, see [DEV_ENVIRONMENT.md](./DEV_ENVIRONMENT.md).
-
-The development environment includes a container named node-dev-env which can be used as a development environment. When the container is created, a bind mount is created and the code base folder is mounted to the container. All development is done inside the container as root. If for example podman is used, this root user inside the container maps to your own user outside the container and there are no problems. If however the container process is running as root, the root user inside the container gets mapped to root user outside the container. This is not only insecure but also creates problems with file permissions. If you now for example create a new file inside the container (by for example running `$ npm install`), the newly created files are owned by root both inside the container but also outside of it.
 
 ## Running locally
 
@@ -71,10 +67,6 @@ cd gradesa && npm install
 
 Required environment variables are documented in `gradesa/src/backend/config.js`. The dev environment uses `.env` and `.env.development` files. See [Database Migrations](gradesa/data/DATABASE_MIGRATIONS.md) for database configuration.
 
-### Explanation
-
-`docker-compose up -d` (or podman) — This command starts the development environment which includes two databases (one for development, one for automatic tests) and a development container named node-dev-env. VSCode dev-containers can be used to attach to the running container (see [dev-containers documentation](https://code.visualstudio.com/docs/devcontainers/attach-container)). It is also possible to run commands inside the container with `docker exec -it node-dev-env bash` (or with Podman). The codebase is mounted at /host.
-
 ## OpenShift
 
 The project is currently hosted on University of Helsinki TIKE OpenShift cluster. The deployment is managed with the manifest files in the manifests folder. The CI/CD pipeline is set up so that when new commit(s) are merged to master, a GitHub actions pipeline runs and builds the new code into a container image which is then pushed to ghcr.io. OpenShift is configured to poll for new images automatically with an interval of 15 minutes. This means that after a change has been merged to master and the pipelines have run successfully, it should take max 15 minutes for the new version to appear in production.
@@ -118,6 +110,7 @@ Organized documentation files throughout the repository:
 - **[gradesa/src/shared/hooks/DATA_FETCHING_HOOKS.md](gradesa/src/shared/hooks/DATA_FETCHING_HOOKS.md)** – Custom data fetching hooks (useQuery, useRequest)
 - **[gradesa/src/components/ui/layout/LAYOUT_COMPONENTS.md](gradesa/src/components/ui/layout/LAYOUT_COMPONENTS.md)** – Layout component system (Container, Row, Column)
 - **[gradesa/src/components/ui/UI_COMPONENTS.md](gradesa/src/components/ui/UI_COMPONENTS.md)** – UI components quick reference (buttons, layout, exercises, glossary)
+- **[DEV_ENVIRONMENT.md](./DEV_ENVIRONMENT.md)** – Explanation about dev containers workflow
 
 ## Definition of Done