Web Architecture - Spring-Vue-Postgres-Keycloak Example

Description

This repository is an architecture for developing a complete website with all the necessary elements: a backend, a frontend, a database, and single sign-on.

All using only open source elements/tools (as much as possible).

Who is this for

This project is for anyone who:

• Wants to learn.
• Is looking for inspiration to build their own architecture.
• Wants to start developing a complete and versatile website.
• Consider a personal/commercial project without licensing fees (see architecture)
• Want to try technologies outside of Big Tech.
• Has lost their way here (Welcome!).

Objectives

The primary goal is to publicly share what I usually do on my own to allow others to be inspired or even motivated to create their own designs.

This repository can serve as a basis for any website project. I hope that its composition corresponds to what you need for your particular case. If you have no specific requirements, I dare say that you have everything you need here to develop your own solution.

I therefore invite you to fork this project or do whatever you like with it as long as it can help/inspire/teach you something.

Architecture

Architecture structure

The architecture is therefore structured as follows:

• A REST API backend
  • Spring (Apache 2.0 License)
    • Spring Web (Apache 2.0 License)
    • Spring Data JPA (Apache 2.0 License)
    • Spring Security (Apache 2.0 License)
  • Redgate Flyway (Apache 2.0 License)
• A frontend
  • Vue.JS (MIT License)
• Single Sign-On (SSO)
  • Keycloak (Apache 2.0 License)
• A database
  • PostgreSQL (PostgreSQL License)

How the architecture works

This diagram assumes that all users have a pre-existing account within the SSO and that the user is attempting to access a "protected" resource (requiring authentication).

When a user attempts to access the website, a series of steps will be triggered to give them the expected result (color code taken from the diagram, not visible on GitHub):

1. First, the user accesses the frontend by going to its URL.
2. If the user is not authenticated, they are immediately redirected to the SSO. The user will then have to enter their credentials to be authenticated by the SSO and in the eyes of the frontend.
3. Once authenticated, the user is redirected to the initial page of the frontend they were trying to access. The frontend will then load the page content.
4. To load content, the frontend may need to call the backend. This call includes a Json Web Token (JWT) containing the identity of the user who made the initial request.
5. To verify the user's identity and permissions, the backend then contacts the SSO with the JWT received to ask if it is valid.
6. If the SSO responds positively, this gives the green light to the backend to respond to the request from the frontend made in step 4.
7. To respond, the backend will often interact with the database to process the data requested by the request.
8. The backend finally responds to the request with the requested content, which will complete that of the frontend.
9. Once the content is loaded, the frontend returns the final result to the user.

Getting started

Here I explain how to start the entire architecture so that you can test it directly. If you want to explore it first to understand it and/or get familiar with it, I suggest you first check the roadmap below.

Needless to mention that everything here is for development purposes. For production, you should assign values and deploy elements according to your own infrastructure.

Prerequisites

Before you begin, make sure you have installed:

• Podman (or Docker) to launch the database and SSO (or the backend and frontend).
  • Podman-Compose (or Docker-Compose) is also recommended. Otherwise, you will need to convert the .yml files into run commands.
• Java 21+ for the Spring backend.
• Maven to build the backend.
• Node.js 22+ and npm for the frontend.

If you haven't already done so, I recommend that you restart your machine once the installation(s) are complete.

Environment variables

The database and single sign-on (SSO) depend on an environment variables file to start. So make sure you create a copy of the .env.*.template file and rename it by removing .template.

This gives:

Item	Template file	Name of the copy
Database	.env.database.template	.env.database
SSO	.env.sso.template	.env.sso

Please note that if you modify the values, you must reflect these changes in the configurations that use them:

• The values in .env.database are used by the backend in its application.properties and its Podman execution scripts (Linux/Windows).
• The values in .env.sso are to be used when logging into the SSO web interface as an administrator (default address: http://localhost:8080).

Once the copies have been created and renamed, you can then start all the elements of the architecture using the commands below.

Commands to run

Make sure to follow the order of execution.

First of all, some elements of the architecture require Podman/Docker, so make sure that the corresponding machine exists and is started:

podman machine init
podman machine start

Database (1/4)

In a new terminal, run the following command to start a Postgres container:

cd ./database/podman/
podman compose -f "podman-compose.yml" up -d

Single Sign-On (SSO) (2/4)

In a new terminal, run the following command to start a Keycloak container (for development):

cd ./sso/podman/dev/
podman compose -f "podman-compose.yml" up -d

Backend (3/4)

In a new terminal, go to the backend application directory:

cd backend/app

Start the application using the following commands:

./mvnw clean install
./mvnw spring-boot:run

Frontend (4/4)

In a new terminal, go to the frontend application directory:

cd frontend/app

Start the application using the following commands:

npm install
npm run dev

All elements are now started and you can begin testing your website by going to http://localhost:5173. But before that, our SSO is gonna say hello to us, so you must first to create your own users.

Once everything started -> Create your users

Once everything is started, you have to add two users into your Keycloak instance. For that, open your browser and go to its address. By default, it's http://localhost:8080.

When the page is shown, enter the credentials you have set into your own .env.sso (be sure to have created it first !).

Then, go to "Manage Realms" and click on "demo-realm". If it is shown as "Current realm", go to "Users" and create two users by setting those values :

Parameter Name	Value User 1	Value User 2
Required user actions	None	None
Email verified	On	On
Username	demo-user	demo-admin
Email	demo-user@example.com	demo-admin@example.com
First name	Demo	Demo
Last name	User	Admin
Groups	demo-users	demo-admins

Once they are created, go to their "Credentials" and click on "Set password". For both, set "demo" as their password and set "Temporary" Off.

Only then you can login into the SSO from the frontend's redirection (should be something starting with "http://localhost:8080/realms/demo-realm/protocol/openid-connect/auth[...]").

Development journey

If you're hesitating to get started, I was in the same situation as you for a long time and I understand. Therefore, I invite you to read the development journey I wrote about this project.

If it can help you feel less alone or even motivate you, I would be delighted.

Roadmap for getting started

Recommended prior knowledge

To get started on this project, I recommend that you first acquire the necessary knowledge to fully understand the concepts discussed here.

I would say that the main concepts you need to know are:

• Container virtualization, in this case Podman.
• What an API is.
  • In this case, a REST API. Note that it is only at level 2 of Richardson's maturity model.
• What a relational database is and what PostgreSQL is.
• The difference between backend and frontend.
• What **[Single Sign-On (SSO)](https://fr.wikipedia.org/wiki/Authentificati