Skip to content

ebouchut/learn-dev

BranchesTags

Repository files navigation

Learn-dev: An Interactive Programming Learning Platform

Presentation

An interactive programming learning platform.

This project aims to enable students to learn programming.

It is also my capstone project for the Web and Web Mobile Developer REAC certification, which I am currently undergoing at La Plateforme_.

Goals

  • Provide an interactive environment for learning programming concepts
  • Support multiple user roles (such as Student, Instructor, Admin)
  • Demonstrate full-stack development skills using industry standards

Tech Stack

This project is built with Java/Spring Boot backend and Thymeleaf frontend.

Backend

  • Language: Java 21
  • Frameworks:
    • Java Framework used to build (Web) Applications and REST endpoints.
  • Authentication and authorization framework:
  • Spring Security:
  • Databases:
    • PostgreSQL version 17 (relational core)
    • MongoDB version 8, provisioned (Docker) for future content storage; not yet wired to a feature
  • Database schema migrations:
    • Liquibase (migrations applied at application startup)
  • Build and dependency management tool:
  • Containerization:
    • Podman (preferred over Docker) to containerize parts of the application as container images that can run as autonomous containers.

Frontend

The frontend is server-rendered: there is no separate frontend application.

  • Thymeleaf templates rendered by the backend (home, login, register, and dashboard pages)
  • thymeleaf-extras-springsecurity6 to display authentication data (such as the logged-in username) in the pages
  • Server-side form handling with bean validation (no JavaScript framework yet)
  • Plain HTML and CSS

Development Tools

  • JetBrains IntelliJ IDEA: IDE
  • Git: Version control
  • Maven: Build and dependency management
  • Podman: Containerization

Getting Started

Prerequisites

See the Tech Stack section.

Installation

  • Clone the ebouchut/learn-dev Git Repository
  • Install a container engine: Podman (recommended) or Docker, plus Docker Compose

Clone the Git repository

#
git clone git@github.com:ebouchut/learn-dev.git
# git clone https://github.com/ebouchut/learn-dev.git

cd learn-dev

Container Engine Setup

You need a container engine and Docker Compose to run the databases.

Option 1 (recommended): Podman

We recommend Podman for security reasons: it runs containers rootless by default and does not need a privileged, always-on daemon.

  • on macOS: 
    brew install podman docker-compose
podman machine init   # Do it once: create the Linux VM
podman machine start  # Start the VM (needed after each reboot)
  • on Windows and Linux

podman understands the Docker CLI syntax, and docker compose works against the Podman socket, so every docker compose ... command in this README works unchanged.

Option 2: Docker

If you prefer Docker anyway:

Python Setup

This is optional if you only need to run the application.

This is necessary in order to regenerate the MERISE database diagrams (MCD, MLD and MPD) after any changes have been made to the database design.

You will need to install Python and:

  • mocodo: a CLI tool to generate the MCD and MLD database diagrams from a text-file description of the conceptual data model.
  • tbls: a CLI tool to reverse engineer the live database to generate the MPD.

Here is the procedure:

  • Install Python
  • Create a Python Virtual Environment: 
    # cd to the folder where you cloned the repository
python3 -m venv venv       # Do it once
source venv/bin/activate  # Run this line each time you open a new shell/terminal/window/tab
  • Install mocodo 
    # mocodo >= 4.3.3 is required (the `make mld` target relies on its `-t diagram` template)
pip install 'mocodo[svg,clipboard]>=4.3.3'
  • Install tbls 
    # On macOS
brew install tbls

# or any OS with Go installed
 go install github.com/k1LoW/tbls@latest

Configuration

A fresh clone has no .env file (it is gitignored because it holds secrets). Create it from the provided template, then fill in the secrets:

  • Create .env from the template (do it once): 
    cp .env.example .env
  • Edit .env
    • Set a value for the variables POSTGRES_PASSWORD, LEARNDEV_DB_PASSWORD, MONGO_ROOT_PASSWORD

Run the application

The quickest way is the Make target, from the project root:

make run

It starts the container machine if needed (Podman only), starts the database services, then runs the app on http://localhost:8080/ (stop it with Ctrl+C).

Alternatively, run the underlying commands yourself:

# Make sure the required versions of Java and Maven are active for this shell
sdk env 

# Ensure the Podman "machine" is up and running 
podman info >/dev/null 2>&1 || podman machine start

# Start the "Docker" services for the application 
docker compose up -d

# Run the app from the project root
./mvnw spring-boot:run

The first command starts the Podman machine if it is not already running.
Then docker compose up -d starts all the application Docker services as declared in docker-compose.yaml (the Docker Compose configuration file), like this. For each service (postgres and mongo):

  1. Download the Docker image for this service as specified in docker-compose.yaml from the Docker Hub public registry, only if the Docker image is not already cached locally.
  2. Store the downloaded image in the local Docker image cache.
  3. Start a Docker container (if it is not already running) based on this image and the configuration in docker-compose.yaml.

Note

A Docker init script automatically creates the database user and the application database when the postgres service is run for the first time. It does not create the database structure or populate the database.

Note

TODO: Explain how the database is created in MongoDB and when.

Note

For Docker or Podman to run on macOS and Windows they need a Linux OS.

Why?
Containers rely on Linux kernel features (namespaces and cgroups).
Windows and macOS do not have a Linux kernel.
This is why Docker Desktop and Podman run a lightweight Linux VM behind the scenes. The containers run inside that hidden VM, not directly on macOS/Windows.

Stop the Application

This command stops all the application services containers declared in the Docker Compose file (docker-compose.yaml):

docker compose stop

Docker Terminology

I use Docker Compose (a CLI tool) to describe and handle the lifecycle of services that comprise my application.

A service is basically a component of the application packaged as a Docker container. It specifies the Docker image and version, configuration, and the network and Docker volume(s) if any.

A Docker image is pre-packaged piece of software that can work as a standalone on Linux. Docker Hub is a public registry that hosts and serves public Docker images.

Postgres Service

Once the postgres service container and its named data volume have been created with docker compose up -d, you can stop then restart the postgres service container individually. Make sure you stopped the application beforehand.

Stop Postgres

docker compose stop postgres

This command stops the postgres service container. It does NOT remove its data volume (its databases).

Start Postgres

This command restarts the existing stopped postgres service container.
If the service container does not already exist, use docker compose up -d to create it.

docker compose start postgres

Now, check that postgres is running:

docker compose ps | grep postgres

To recreate the database, and start from scratch you need to stop the postgres container and remove the (data) volumes.
See the Remove the Postgres Databases section for details.

Remove the Postgres Databases

Stops and remove the postgres service container and its data volumes (meaning all its databases).

Caution

This destructive command will:

  • stop and remove the postgres service container,
  • remove ALL its databases: structure and content, (i.e., everything created by Postgres running in the container).
docker compose down -v postgres

Mongo Service

Once the mongoservice container has been created with docker compose up -d, you can stop then restart the mongo service container individually.

Stop MongoDB

docker compose stop mongo

This command stops the mongo service container. It does NOT remove its data volume (i.e., the MongoDB databases created in this container).

Start MongoDB

This command restarts the existing stopped mongo service container.
If the service container does not already exist, use docker compose up -d to create it.

docker compose start mongo

Now, check that mongo is running:

docker compose ps | grep mongo

Remove MongoDB and its Databases

Caution

This destructive command will:

  • stop and remove the mongo service container,
  • remove its data volumes (i.e., ALL the databases created by MongoDB running in the container).
docker compose down -v mongo

Where:

  • -v request Compose to remove the named data volumes created for this service

Project Status

For up-to-date information about the status of the project, visit this link.

Documentation

  • ARCHITECTURE.md — how the pieces fit together (layers, request flow, authentication, data, testing).
  • docs/tech-stacks.md — catalogue of tools, languages, and frameworks with versions used in the project.
  • GLOSSARY.md — definitions of the domain and technical terms used across the project.
  • Architecture Decision Records — A list of design decisions and their trade-offs.

Contributing

CONTRIBUTING.md contains:

License

This project is dual-licensed
under AGPL v3 for open source use
and a commercial license for proprietary use.

See LICENSE for details.

Authors

Eric Bouchut:

Resources

About

An interactive programming learning platform.

github.com/ebouchut/bouchut-eric-dossiers-pros-DWWM

Topics

programming learn

Resources

Readme

License

View license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Contributors

Languages