Skip to content

CyberLions/KeycloakTheme

Repository files navigation

⚠️ Please read the two following notices ⚠️

This setup is for CSS-level customization, if you want to customize the pages at the component level heads over to the look_and_feel branch.

If you are only looking to create a theme and don't care about integrating it into a preexisting React app there are a lot of things that you can remove. Please read this.

Introduction

This repo constitutes an easily reusable CI setup for SPA React App in general, and Apps that generates Keycloaks's theme using keycloakify in particular.

The CI workflow

  • This CI is configured to both publish on GitHub Pages and on DockerHub. In practice you probably want one or the other but not both.
    We deploy the demo app at demo-app.keycloakify.dev using GitHub page on the branch gh-pages (you have to enable it).
    To configure your own domain name please refer to this documentation.
  • To release don't create a tag manually, the CI do it for you. Just update the package.json's version field and push.
  • The .jar files that bundle the Keycloak theme will be attached as an asset with every GitHub release. Example. The permalink to download the latest version is: https://github.com/USER/PROJECT/releases/latest/download/keycloak-theme.jar. For this demo repo it's here
  • The CI publishes the app docker image on DockerHub. <org>/<repo>:main for each commit on main, <org>/<repo>:<feature-branch-name> for each pull-request on main and when releasing a new version: <org>/<repo>:latest and <org>/<repo>:X.Y.Z See on DockerHub
  • A CHANGELOG.md will be maintained for you using the commit messages between releases. If you don't want a specific commit to appear in the changelog do something like. git commit -am "yadi yada (changelog ignore).

image

image

If you want an example of an app that put that setup in production checkout onyxia-ui: the repo, the login, the app.

This repo is currently configured to build the theme with --external-assets. If your keycloak pages need to stay up even when your app is down you should remove --external-assets here.

Docker

docker build -f Dockerfile -t garronej/keycloakify-demo-app:test .
#OR (to reproduce how the image is built in the ci workflow):
yarn && yarn build && tar -cvf build.tar ./build && docker build -f Dockerfile.ci -t garronej/keycloakify-demo-app:test . && rm build.tar

docker run -it -dp 8083:80 garronej/keycloakify-demo-app:test

DockerHub credentials

To enables the CI to publish on DockerHub on your behalf go to repository Settings tab, then Secrets you will need to add two new secrets:

  • DOCKERHUB_TOKEN, you Dockerhub authorization token.
  • DOCKERHUB_USERNAME, Your Dockerhub username.

Standalone keycloak theme

If you are only looking to create a keycloak theme, there are a lot of things you should remove after clicking image:

  • You can remove all things related to building a docker image and publishing on github pages: remove these lines and this line from .github/workflows/ci.yaml.
  • All the assets will need to be served by Keycloak: remove --external-assets from this line.
  • You can remove /Dockerfile, Dockerfile.ci ,/.dockerignore and /nginx.conf
  • You can assume the app will only run in the context of Keycloak so you can remove these lines in src/index.tsx (and you can, of course, remove src/App.tsx, App.css ect...).
  • You can remove the homepage field from the package.json

For the rest all stays the same, when your theme is ready, just upgrade the version in package.json and push.
You will find your theme packaged in a .tar file in the GitHub releases of your project.