Webfragments with Keycloak

This project demonstrates a microfrontend architecture using web fragments, a central shell app, and Keycloak for authentication and authorization.

The goal is to develop multiple frontends and backends modularly, deploy them independently, and integrate them dynamically within a shared shell.

Prerequisites

• Node.js (v20 or newer)
• pnpm (preferred package manager)
• Docker
• Docker Compose

Getting started

Project structure

• containerization/
  • keycloak-realm/ → Keycloak configuration
  • compose.yml → Compose setup
  • default.env → Environment file
• fragment/
  • backend/ → Fragment backend (API and BFF)
  • frontend/ → Fragment frontend (Angular)
• shell/
  • backend/ → Shell backend
  • frontend/ → Shell frontend (Angular)
• README.md

Install dependencies

Go to fragment and install dependencies for backend and frontend.

cd fragment/frontend
pnpm install

cd fragment/backend
pnpm install

Go to shell and install dependencies for backend and frontend.

cd shell/frontend
pnpm install

cd shell/backend
pnpm install

Docker Setup

Define environment variables

Create an environment file .env in containerization.

cd containerization
cp default.env .env

Start compose

cd containerization
docker compose up -d

Build and start apps

Build and start fragment

Go to fragment to build and start app.

cd fragment/frontend
pnpm build

cd fragment/backend
pnpm start

# reachable on http://localhost:8000/

Build and start shell

Open a new/extra or second terminal. Go to shell to build and start app.

cd shell/frontend
pnpm build

cd shell/backend
pnpm start

# reachable on http://localhost:3000/

Login

Open in browser http://localhost:8081/admin to login to admin console of keycloak. Use as user = password = admin.

Open in browser http://localhost:3000/ to login to shell. Use as user = password = webfragements.

You should see the shell and the fragment loaded with a button. Clicking the button calls a request to load text Hello World. But this works not in current situation, but should. This is because we use in the fragment keycloak onLoad Option with 'check-sso'. It works with the value undefined but that is not desired.

Optional

Export keycloak realms

The following commands are for exporting changes in keycloak realms and save them for later. You need to stop the compose before running the commands.

The realms will be imported on startup of the compose file.

cd containerization

# export realms
docker compose run --rm keycloak export --dir /opt/keycloak/data/import