🎓 Courses Backend

Warning

Rename .env.local to .env before running docker compose or DB connection will fail! [!NOTE] PostgreSQL is not exposed on host port 5432 to avoid conflicts. All services run in a private Docker network. You just need to run docker compose up --pull always --build.

This is the backend API for the Courses App. Built with Java 17, Spring Boot, and PostgreSQL, it exposes a REST API to manage courses and their delivery instances — with proper validation for prerequisites and dependencies.

The backend is fully Dockerized, uses Flyway for DB migrations, and is designed to run as part of a full-stack setup with Docker Compose.

---

🧰 Tech Stack

• Java 17 + Spring Boot
• PostgreSQL (as DB)
• Spring Data JPA
• Flyway (for migrations)
• Docker (multi-stage Maven build)

---

🎯 Features

• Full CRUD for Courses and Course Instances
• Courses can have multiple prerequisites (validated)
• Delivery instances tied to semester and year
• Proper validation with meaningful error responses
• Clean architecture: Controller → Service → Repository
• Preconfigured Docker container
• Flyway-based schema migration

---

🔗 API Endpoints

📘 Course Endpoints

Method	Endpoint	Description
POST	/api/courses	Create a new course
GET	/api/courses	Get all courses
GET	/api/courses/{id}	Get course by ID
DELETE	/api/courses/{id}	Delete course by ID
GET	/api/courses/search?title=…	Search courses by title (partial)

📘 Course Instance Endpoints

Method	Endpoint	Description
POST	/api/instances	Create a course instance
GET	/api/instances/{year}/{semester}	Get all course instances in a given year/semester
GET	/api/instances/{year}/{semester}/{courseId}	Get a specific course instance
DELETE	/api/instances/{year}/{semester}/{courseId}	Delete a specific course instance

🧠 All requests/responses use JSON format.
Prerequisites and instances are validated during creation to prevent circular references or missing courses.

---

🐳 Dockerized Deployment

This app is published as a Docker image on Docker Hub and is designed to run via docker compose.

docker-compose.yml (example):

services:
  db:
    image: postgres:16
    container_name: courses-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: courses
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  courses-backend:
    image: ranxom/courses-backend:latest
    container_name: courses-backend
    ports:
      - "8080:8080"
    depends_on:
      - db
    env_file:
      - .env
    restart: unless-stopped

volumes:
  postgres_data:

.env file

SPRING_DATASOURCE_URL=jdbc:postgresql://courses-db:5432/courses
SPRING_DATASOURCE_USERNAME=postgres
SPRING_DATASOURCE_PASSWORD=postgres

🔐 This file is required to configure DB credentials and connection inside Docker.

---

📝 Notes

• This project includes Flyway migrations; DB schema is automatically created at startup.

• Make sure to link the .env file properly or it will fail DB connection.

• If building locally instead of pulling image, run:

  docker build -t ranxom/courses-backend:latest .

---

▶️ How to Run

1. Ensure Docker & Docker Compose are installed
2. Clone both backend and frontend repos
3. Create .env file in backend directory (as shown above)
4. Ensure docker-compose.yml includes the backend and frontend services
5. Run:

docker-compose up

API will be available at: http://localhost:8080/api

---

🛠️ Local Development (Optional)

If you prefer to run the backend without Docker:

./mvnw spring-boot:run

Ensure PostgreSQL is running locally and .env or application.properties is configured accordingly.

---

🧾 Project Structure

📦 courses-backend
 ┣ 📂src
 ┃ ┣ 📂main
 ┃ ┃ ┣ 📂java
 ┃ ┃ ┃ ┗ 📦 com.shizain.courses_backend
 ┃ ┃ ┣ 📂resources
 ┃ ┃ ┃ ┣ application.properties
 ┃ ┃ ┃ ┗ db/migration/V1__init.sql (Flyway)
 ┣ 📄 Dockerfile
 ┣ 📄 docker-compose.yml (if colocated)
 ┣ 📄 .env
 ┣ 📄 pom.xml
 ┗ 📄 README.md

---

🧑‍💻 Author

Built with 💻 and ☕ by Shizain

---

📜 License

MIT