README.md

# Keycloak Workbench

Simple setup to run Keycloak and work on theme development.

## How to run

Install Docker and Docker Compose on Linux, or [Docker Desktop](https://docs.docker.com/desktop/install/mac-install/) on Windows/Mac, then run:

```bash
docker compose up    # Start
docker compose down  # Stop
```

After ~1m Keycloak should be reachable at the following URLs:

- [http://localhost:8080](http://localhost:8080) - Welcome page
  - This is what users will see when they'll manually type in the browser URL `sso.rev.ng` - it's not something we want them to access unless they try hard
- [http://localhost:8080/admin](http://localhost:8080/admin) - Keycloak admin console
  - This is where you change the Keycloak settings
  - Default credentials are `admin:admin` (configured in `.env` if you want to change them)
- [http://localhost:8080/realms/users/account/](http://localhost:8080/realms/users/account/) - Account console
  - This is where users sign in, sign up, create anonymous accounts, change the email and password
  - Note that the "Try anonymously" and "GitHub" login buttons are there so you can style them, but they are not functional.
  - There's no user account by default, you can create user accounts either by signing up or from the admin console.
- [http://localhost:8025](http://localhost:8025) - Test email server
  - All emails sent by Keycloak will be displayed here (such as account activation emails).


## Important!

If you access the Keycloak Admin to change the settings, make sure you select the `users` realm in the menu on the left sidebar!

Otherwise you will be changing settings that apply only to the administration pages.

Do not apply the `revng` theme to the admin console from the Keycloak settings! It will break!

## Theme development

You can change any files in `theme` and changes should be applied automatically.

We set it up to use `sassc`; the `kc-autorebuild-theme` Docker container will rebuild the CSS files for you.

Feel free to throw it away if you don't like it or make any changes you want.

The themes extend the default themes from Keycloak, so if you read `parent: base` or `parent: keycloak` in `theme.properties`, that's what they refer to.

You can find them on GitHub:

https://github.com/keycloak/keycloak/tree/20.0.3/themes/src/main/resources/theme

## Reset the database / settings

Just stop `docker compose` and delete the `database` folder.