mkopp.dev - A Portfolio in Action

This repository contains the source code for mkopp.dev. Unlike a traditional portfolio that links to external projects, this project follows a "show, don't just tell" philosophy: the website itself is the portfolio.

It is designed to be a living, breathing showcase of enterprise-level full-stack engineering, real-world DevOps practices, and transparent design decisions.

Core Philosophy

• The Project is the Product: The primary goal is to demonstrate skills in architecture, development, and deployment through the platform itself.
• Radical Transparency: All design documents, architectural decisions (ADRs), and project planning are public.
• A Learning Resource: The platform serves as a teaching tool through blog posts and documentation that explain how it was built.

---

Tech Stack

This project is a full-stack application built within an Nx monorepo.

Category	Technology
Frontend	Angular (with SSR)
Backend	Spring Boot (Java)
Database	PostgreSQL
Authentication	Keycloak (planned)
DevOps	Docker, Docker Compose, GitHub Actions, Traefik, SSH
Monorepo Tool	Nx

---

Architecture Overview

The system is deployed on a single VPS and orchestrated with Docker Compose. Traefik acts as a reverse proxy, handling SSL and routing requests to a cluster of redundant frontend and backend services.

flowchart TD
  subgraph VPS
    subgraph Traefik
      T[Reverse Proxy & SSL]
    end
    subgraph FrontendCluster ["Angular SSR Frontend (3x)"]
      F1[Frontend-1]
      F2[Frontend-2]
      F3[Frontend-3]
    end
    subgraph BackendCluster ["Spring Boot Backend (3x)"]
      B1[Backend-1]
      B2[Backend-2]
      B3[Backend-3]
    end
    DB[(PostgreSQL)]
    KC[Keycloak planned]
  end

T --> F1
T --> F2
T --> F3
F1 --> B1
F2 --> B2
F3 --> B3
B1 --> DB
B2 --> DB
B3 --> DB
KC --> B1
KC --> B2
KC --> B3

Loading

For a full rationale and implementation details, see ADR 004 – Deployment with Docker + Traefik.

---

Local Development

Prerequisites

• Docker & Docker Compose
• Java 17: The backend is a Spring Boot application which requires Java 17.
• Node.js v22.2.0+: The frontend is an Angular application.
• npm 10.8.0+: Package manager for the frontend.
• An IDE (e.g., VS Code, IntelliJ IDEA)

Setup

1. Clone the repository:

   git clone https://github.com/MichaelJGKopp/mkopp.dev.git
   cd mkopp.dev

2. Configure Environment Variables:

   • Copy the example environment file:

     cp .env.example .env

   • Open the new .env file and replace the placeholder values with your local configuration.

3. Launch the Application:

   • Use Docker Compose to build and run all the services:

     docker-compose up --build

4. Access the Application:

   • Frontend: http://localhost (or your configured domain)
   • Traefik Dashboard: http://traefik.localhost (Requires basic auth credentials from your .env file).

Running Tests

You can run the tests for the frontend and backend separately.

• Frontend (Angular):

  npx nx test mysite-frontend

• Backend (Spring Boot):

  npx nx test mysite-backend

---

Production Deployment

Production deployment uses a separate docker-compose.prod.yml file and is automated via a CI/CD pipeline.

CI/CD Flow

1. Push to main branch: A push or merge to the main branch triggers the GitHub Actions workflow.
2. Build & Test: The workflow builds and tests the frontend and backend applications.
3. Publish Docker Images: On success, multi-stage Docker images are built and pushed to DockerHub.
4. Deploy to VPS: The deploy.sh script is executed on the production VPS via SSH. This script pulls the latest images from DockerHub and restarts the services using docker-compose -f docker-compose.prod.yml up -d.

This process ensures automated, consistent deployments to the production environment.

---

Project Structure

This is an Nx monorepo. Key directories include:

• apps/: Contains the two main applications:
  • mysite-frontend/: The Angular SSR frontend.
  • mysite-backend/: The Spring Boot (Java) backend.
• docs/: Contains all project documentation, including this README, the Design Document, and Architecture Decision Records (ADRs).

To visualize the project graph and dependencies, run:

npx nx graph

---

Contributing

Contributions are welcome! Please see our Contributing Guidelines for more information on how to get started.

---

Code of Conduct

This project is governed by the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

---

Development Process

This project follows an agile approach using a public Kanban board to track user stories, epics, and progress. For more details, see the Design Document.