Release candidate

keycloak start command options support in config

.all-contributorsrc

@@ -231,6 +231,15 @@
       "contributions": [
         "code"
       ]
+    },
+    {
+      "login": "madmadson",
+      "name": "Tobias Matt",
+      "avatar_url": "https://avatars.githubusercontent.com/u/798831?v=4",
+      "profile": "https://github.com/madmadson",
+      "contributions": [
+        "code"
+      ]
     }
   ],
   "contributorsPerLine": 7,

README.md

@@ -43,7 +43,8 @@
 
 Keycloakify is fully compatible with Keycloak 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, [~~22~~](https://github.com/keycloakify/keycloakify/issues/389#issuecomment-1822509763), 23, 24, 25...[and beyond](https://github.com/keycloakify/keycloakify/discussions/346#discussioncomment-5889791)
 
-> NOTE: Keycloakify 10 is still in release-candidate state. [Follow progress](https://github.com/keycloakify/keycloakify/pull/538).
+> NOTE: Keycloakify 10, while still being tagged as release candidate is the version you should use if you are starting today.  
+> Use `yarn add keycloakify@next` or pin [the latest version candidate](https://www.npmjs.com/package/keycloakify?activeTab=versions).
 
 ## Sponsors
 
@@ -130,7 +131,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
       <td align="center" valign="top" width="14.28%"><a href="https://m-siemens.de/"><img src="https://avatars.githubusercontent.com/u/1873922?v=4?s=100" width="100px;" alt="Markus Siemens"/><br /><sub><b>Markus Siemens</b></sub></a><br /><a href="https://github.com/keycloakify/keycloakify/commits?author=msiemens" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/law108000"><img src="https://avatars.githubusercontent.com/u/8112024?v=4?s=100" width="100px;" alt="Rlok"/><br /><sub><b>Rlok</b></sub></a><br /><a href="https://github.com/keycloakify/keycloakify/commits?author=law108000" title="Code">💻</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/Moulyy"><img src="https://avatars.githubusercontent.com/u/115405804?v=4?s=100" width="100px;" alt="Moulyy"/><br /><sub><b>Moulyy</b></sub></a><br /><a href="https://github.com/keycloakify/keycloakify/commits?author=Moulyy" title="Code">💻</a></td>
-      <td align="center" valign="top" width="14.28%"><a href="https://github.com/giorgoslytos"><img src="https://avatars.githubusercontent.com/u/50946162?v=4?s=100" width="100px;" alt="giorgoslytos"/><br /><sub><b>giorgoslytos</b></sub></a><br /><a href="https://github.com/keycloakify/keycloakify/commits?author=giorgoslytos" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/madmadson"><img src="https://avatars.githubusercontent.com/u/798831?v=4?s=100" width="100px;" alt="Tobias Matt"/><br /><sub><b>Tobias Matt</b></sub></a><br /><a href="https://github.com/keycloakify/keycloakify/commits?author=madmadson" title="Code">💻</a></td>
     </tr>
   </tbody>
 </table>

package.json

@@ -1,6 +1,6 @@
 {
     "name": "keycloakify",
-    "version": "10.0.0-rc.128",
+    "version": "10.0.0-rc.139",
     "description": "Create Keycloak themes using React",
     "repository": {
         "type": "git",
@@ -85,7 +85,7 @@
         "@types/yauzl": "^2.10.3",
         "@vercel/ncc": "^0.38.1",
         "chalk": "^4.1.2",
-        "cheerio": "^1.0.0-rc.12",
+        "cheerio": "1.0.0-rc.12",
         "chokidar-cli": "^3.0.0",
         "cli-select": "^1.1.2",
         "husky": "^4.3.8",
@@ -103,7 +103,7 @@
         "termost": "^v0.12.1",
         "tsc-alias": "^1.8.10",
         "tss-react": "^4.9.10",
-        "typescript": "^4.9.1-beta",
+        "typescript": "^4.9.4",
         "vite": "^5.2.11",
         "vitest": "^1.6.0",
         "yauzl": "^2.10.0",

scripts/link-in-starter.ts

@@ -2,8 +2,33 @@ import * as child_process from "child_process";
 import * as fs from "fs";
 import { join } from "path";
 import { startRebuildOnSrcChange } from "./startRebuildOnSrcChange";
+import { crawl } from "../src/bin/tools/crawl";
+
+{
+    const dirPath = "node_modules";
+
+    try {
+        fs.rmSync(dirPath, { recursive: true, force: true });
+    } catch {
+        // NOTE: This is a workaround for windows
+        // we can't remove locked executables.
+
+        crawl({
+            dirPath,
+            returnedPathsType: "absolute"
+        }).forEach(filePath => {
+            try {
+                fs.rmSync(filePath, { force: true });
+            } catch (error) {
+                if (filePath.endsWith(".exe")) {
+                    return;
+                }
+                throw error;
+            }
+        });
+    }
+}
 
-fs.rmSync("node_modules", { recursive: true, force: true });
 fs.rmSync("dist", { recursive: true, force: true });
 fs.rmSync(".yarn_home", { recursive: true, force: true });
 

src/bin/initialize-account-theme/initializeAccountTheme_singlePage.ts

@@ -2,7 +2,10 @@ import { join as pathJoin, relative as pathRelative, dirname as pathDirname } fr
 import type { BuildContext } from "../shared/buildContext";
 import * as fs from "fs";
 import chalk from "chalk";
-import { getLatestsSemVersionedTag } from "../shared/getLatestsSemVersionedTag";
+import {
+    getLatestsSemVersionedTag,
+    type BuildContextLike as BuildContextLike_getLatestsSemVersionedTag
+} from "../shared/getLatestsSemVersionedTag";
 import fetch from "make-fetch-happen";
 import { z } from "zod";
 import { assert, type Equals } from "tsafe/assert";
@@ -12,8 +15,7 @@ import { npmInstall } from "../tools/npmInstall";
 import { copyBoilerplate } from "./copyBoilerplate";
 import { getThisCodebaseRootDirPath } from "../tools/getThisCodebaseRootDirPath";
 
-type BuildContextLike = {
-    cacheDirPath: string;
+type BuildContextLike = BuildContextLike_getLatestsSemVersionedTag & {
     fetchOptions: BuildContext["fetchOptions"];
     packageJsonFilePath: string;
 };
@@ -30,11 +32,11 @@ export async function initializeAccountTheme_singlePage(params: {
     const REPO = "keycloak-account-ui";
 
     const [semVersionedTag] = await getLatestsSemVersionedTag({
-        cacheDirPath: buildContext.cacheDirPath,
         owner: OWNER,
         repo: REPO,
         count: 1,
-        doIgnoreReleaseCandidates: false
+        doIgnoreReleaseCandidates: false,
+        buildContext
     });
 
     const dependencies = await fetch(

src/bin/initialize-email-theme.ts

@@ -30,7 +30,7 @@ export async function command(params: { cliCommandOptions: CliCommandOptions })
         // NOTE: This is arbitrary
         startingFromMajor: 17,
         excludeMajorVersions: [],
-        cacheDirPath: buildContext.cacheDirPath
+        buildContext
     });
 
     const { defaultThemeDirPath } = await downloadKeycloakDefaultTheme({

src/bin/keycloakify/generateFtl/generateFtl.ts

@@ -1,4 +1,4 @@
-import cheerio from "cheerio";
+import * as cheerio from "cheerio";
 import {
     replaceImportsInJsCode,
     BuildContextLike as BuildContextLike_replaceImportsInJsCode

src/bin/keycloakify/generateResources/generateResourcesForMainTheme.ts

@@ -314,7 +314,7 @@ export async function generateResourcesForMainTheme(params: {
         }
 
         const { extractedDirPath } = await downloadAndExtractArchive({
-            url: "https://repo1.maven.org/maven2/org/keycloak/keycloak-account-ui/25.0.1/keycloak-account-ui-25.0.1.jar",
+            urlOrPath: "https://repo1.maven.org/maven2/org/keycloak/keycloak-account-ui/25.0.1/keycloak-account-ui-25.0.1.jar",
             cacheDirPath: buildContext.cacheDirPath,
             fetchOptions: buildContext.fetchOptions,
             uniqueIdOfOnArchiveFile: "bring_in_account_v3_i18n_messages",

src/bin/shared/buildContext.ts

@@ -61,6 +61,18 @@ export type BuildContext = {
         keycloakVersionRange: KeycloakVersionRange;
         jarFileBasename: string;
     }[];
+    startKeycloakOptions: {
+        dockerImage:
+            | {
+                  reference: string;
+                  tag: string;
+              }
+            | undefined;
+        dockerExtraArgs: string[];
+        keycloakExtraArgs: string[];
+        extensionJars: ({ type: "path"; path: string } | { type: "url"; url: string })[];
+        realmJsonFilePath: string | undefined;
+    };
 };
 
 assert<Equals<keyof BuildContext["implementedThemeTypes"], ThemeType | "email">>();
@@ -75,6 +87,13 @@ export type BuildOptions = {
     loginThemeResourcesFromKeycloakVersion?: string;
     keycloakifyBuildDirPath?: string;
     kcContextExclusionsFtl?: string;
+    startKeycloakOptions?: {
+        dockerImage?: string;
+        dockerExtraArgs?: string[];
+        keycloakExtraArgs?: string[];
+        extensionJars?: string[];
+        realmJsonFilePath?: string;
+    };
 } & BuildOptions.AccountThemeImplAndKeycloakVersionTargets;
 
 export namespace BuildOptions {
@@ -301,6 +320,22 @@ export function getBuildContext(params: {
             return id<z.ZodType<TargetType>>(zTargetType);
         })();
 
+        const zStartKeycloakOptions = (() => {
+            type TargetType = NonNullable<BuildOptions["startKeycloakOptions"]>;
+
+            const zTargetType = z.object({
+                dockerImage: z.string().optional(),
+                extensionJars: z.array(z.string()).optional(),
+                realmJsonFilePath: z.string().optional(),
+                dockerExtraArgs: z.array(z.string()).optional(),
+                keycloakExtraArgs: z.array(z.string()).optional()
+            });
+
+            assert<Equals<z.infer<typeof zTargetType>, TargetType>>();
+
+            return id<z.ZodType<TargetType>>(zTargetType);
+        })();
+
         const zBuildOptions = (() => {
             type TargetType = BuildOptions;
 
@@ -321,7 +356,8 @@ export function getBuildContext(params: {
                     groupId: z.string().optional(),
                     loginThemeResourcesFromKeycloakVersion: z.string().optional(),
                     keycloakifyBuildDirPath: z.string().optional(),
-                    kcContextExclusionsFtl: z.string().optional()
+                    kcContextExclusionsFtl: z.string().optional(),
+                    startKeycloakOptions: zStartKeycloakOptions.optional()
                 }),
                 zAccountThemeImplAndKeycloakVersionTargets
             );
@@ -891,6 +927,47 @@ export function getBuildContext(params: {
             }
 
             return jarTargets;
-        })()
+        })(),
+        startKeycloakOptions: {
+            dockerImage: (() => {
+                if (buildOptions.startKeycloakOptions?.dockerImage === undefined) {
+                    return undefined;
+                }
+
+                const [reference, tag, ...rest] =
+                    buildOptions.startKeycloakOptions.dockerImage.split(":");
+
+                assert(
+                    reference !== undefined && tag !== undefined && rest.length === 0,
+                    `Invalid docker image: ${buildOptions.startKeycloakOptions.dockerImage}`
+                );
+
+                return { reference, tag };
+            })(),
+            dockerExtraArgs: buildOptions.startKeycloakOptions?.dockerExtraArgs ?? [],
+            keycloakExtraArgs: buildOptions.startKeycloakOptions?.keycloakExtraArgs ?? [],
+            extensionJars: (buildOptions.startKeycloakOptions?.extensionJars ?? []).map(
+                urlOrPath => {
+                    if (/^https?:\/\//.test(urlOrPath)) {
+                        return { type: "url", url: urlOrPath };
+                    }
+
+                    return {
+                        type: "path",
+                        path: getAbsoluteAndInOsFormatPath({
+                            pathIsh: urlOrPath,
+                            cwd: projectDirPath
+                        })
+                    };
+                }
+            ),
+            realmJsonFilePath:
+                buildOptions.startKeycloakOptions?.realmJsonFilePath === undefined
+                    ? undefined
+                    : getAbsoluteAndInOsFormatPath({
+                          pathIsh: buildOptions.startKeycloakOptions.realmJsonFilePath,
+                          cwd: projectDirPath
+                      })
+        }
     };
 }

src/bin/shared/downloadKeycloakDefaultTheme.ts

@@ -21,7 +21,7 @@ export async function downloadKeycloakDefaultTheme(params: {
     let kcNodeModulesKeepFilePaths_lastAccountV1: Set<string> | undefined = undefined;
 
     const { extractedDirPath } = await downloadAndExtractArchive({
-        url: `https://repo1.maven.org/maven2/org/keycloak/keycloak-themes/${keycloakVersion}/keycloak-themes-${keycloakVersion}.jar`,
+        urlOrPath: `https://repo1.maven.org/maven2/org/keycloak/keycloak-themes/${keycloakVersion}/keycloak-themes-${keycloakVersion}.jar`,
         cacheDirPath: buildContext.cacheDirPath,
         fetchOptions: buildContext.fetchOptions,
         uniqueIdOfOnArchiveFile: "downloadKeycloakDefaultTheme",

src/bin/shared/getLatestsSemVersionedTag.ts

@@ -9,6 +9,8 @@ import { assert, type Equals } from "tsafe/assert";
 import { id } from "tsafe/id";
 import type { SemVer } from "../tools/SemVer";
 import { same } from "evt/tools/inDepth/same";
+import type { BuildContext } from "./buildContext";
+import fetch from "make-fetch-happen";
 
 type GetLatestsSemVersionedTag = ReturnType<
     typeof getLatestsSemVersionedTagFactory
@@ -31,11 +33,23 @@ type Cache = {
     }[];
 };
 
+export type BuildContextLike = {
+    cacheDirPath: string;
+    fetchOptions: BuildContext["fetchOptions"];
+};
+
+assert<BuildContext extends BuildContextLike ? true : false>();
+
 export async function getLatestsSemVersionedTag({
-    cacheDirPath,
+    buildContext,
     ...params
-}: Params & { cacheDirPath: string }): Promise<R> {
-    const cacheFilePath = pathJoin(cacheDirPath, "latest-sem-versioned-tags.json");
+}: Params & {
+    buildContext: BuildContextLike;
+}): Promise<R> {
+    const cacheFilePath = pathJoin(
+        buildContext.cacheDirPath,
+        "latest-sem-versioned-tags.json"
+    );
 
     const cacheLookupResult = (() => {
         const getResult_currentCache = (currentCacheEntries: Cache["entries"]) => ({
@@ -144,9 +158,16 @@ export async function getLatestsSemVersionedTag({
         const octokit = (() => {
             const githubToken = process.env.GITHUB_TOKEN;
 
-            const octokit = new Octokit(
-                githubToken === undefined ? undefined : { auth: githubToken }
-            );
+            const octokit = new Octokit({
+                ...(githubToken === undefined ? {} : { auth: githubToken }),
+                request: {
+                    fetch: (url: string, options?: any) =>
+                        fetch(url, {
+                            ...options,
+                            ...buildContext.fetchOptions
+                        })
+                }
+            });
 
             return octokit;
         })();

src/bin/shared/promptKeycloakVersion.ts

@@ -1,22 +1,31 @@
-import { getLatestsSemVersionedTag } from "./getLatestsSemVersionedTag";
+import {
+    getLatestsSemVersionedTag,
+    type BuildContextLike as BuildContextLike_getLatestsSemVersionedTag
+} from "./getLatestsSemVersionedTag";
 import cliSelect from "cli-select";
+import { assert } from "tsafe/assert";
 import { SemVer } from "../tools/SemVer";
+import type { BuildContext } from "./buildContext";
+
+export type BuildContextLike = BuildContextLike_getLatestsSemVersionedTag & {};
+
+assert<BuildContext extends BuildContextLike ? true : false>();
 
 export async function promptKeycloakVersion(params: {
     startingFromMajor: number | undefined;
     excludeMajorVersions: number[];
-    cacheDirPath: string;
+    buildContext: BuildContextLike;
 }) {
-    const { startingFromMajor, excludeMajorVersions, cacheDirPath } = params;
+    const { startingFromMajor, excludeMajorVersions, buildContext } = params;
 
     const semVersionedTagByMajor = new Map<number, { tag: string; version: SemVer }>();
 
     const semVersionedTags = await getLatestsSemVersionedTag({
-        cacheDirPath,
         count: 50,
         owner: "keycloak",
         repo: "keycloak",
-        doIgnoreReleaseCandidates: true
+        doIgnoreReleaseCandidates: true,
+        buildContext
     });
 
     semVersionedTags.forEach(semVersionedTag => {

src/bin/start-keycloak/appBuild.ts

@@ -40,7 +40,7 @@ async function appBuild_vite(params: {
 
     const dIsSuccess = new Deferred<boolean>();
 
-    console.log(chalk.blue("Running: 'npx vite build'"));
+    console.log(chalk.blue("$ npx vite build"));
 
     const child = child_process.spawn("npx", ["vite", "build"], {
         cwd: buildContext.projectDirPath,
@@ -145,7 +145,7 @@ async function appBuild_webpack(params: {
             continue;
         }
 
-        console.log(chalk.blue(`Running: '${subCommand}'`));
+        console.log(chalk.blue(`$ ${subCommand}`));
 
         const child = child_process.spawn(command, args, {
             cwd: commandCwd,

src/bin/start-keycloak/keycloakifyBuild.ts

@@ -20,7 +20,7 @@ export async function keycloakifyBuild(params: {
 
     const dResult = new Deferred<{ isSuccess: boolean }>();
 
-    console.log(chalk.blue("Running: 'npx keycloakify build'"));
+    console.log(chalk.blue("$ npx keycloakify build"));
 
     const child = child_process.spawn("npx", ["keycloakify", "build"], {
         cwd: buildContext.projectDirPath,

src/bin/start-keycloak/start-keycloak.ts

@@ -4,7 +4,7 @@ import type { CliCommandOptions as CliCommandOptions_common } from "../main";
 import { promptKeycloakVersion } from "../shared/promptKeycloakVersion";
 import { ACCOUNT_V1_THEME_NAME, CONTAINER_NAME } from "../shared/constants";
 import { SemVer } from "../tools/SemVer";
-import { assert } from "tsafe/assert";
+import { assert, type Equals } from "tsafe/assert";
 import * as fs from "fs";
 import {
     join as pathJoin,
@@ -26,6 +26,7 @@ import { keycloakifyBuild } from "./keycloakifyBuild";
 import { isInside } from "../tools/isInside";
 import { existsAsync } from "../tools/fs.existsAsync";
 import { rm } from "../tools/fs.rm";
+import { downloadAndExtractArchive } from "../tools/downloadAndExtractArchive";
 
 export type CliCommandOptions = CliCommandOptions_common & {
     port: number;
@@ -88,30 +89,65 @@ export async function command(params: { cliCommandOptions: CliCommandOptions })
 
     const buildContext = getBuildContext({ cliCommandOptions });
 
-    const { keycloakVersion } = await (async () => {
+    const { dockerImageTag } = await (async () => {
         if (cliCommandOptions.keycloakVersion !== undefined) {
+            return { dockerImageTag: cliCommandOptions.keycloakVersion };
+        }
+
+        if (buildContext.startKeycloakOptions.dockerImage !== undefined) {
             return {
-                keycloakVersion: cliCommandOptions.keycloakVersion,
-                keycloakMajorNumber: SemVer.parse(cliCommandOptions.keycloakVersion).major
+                dockerImageTag: buildContext.startKeycloakOptions.dockerImage.tag
             };
         }
 
         console.log(
-            chalk.cyan("On which version of Keycloak do you want to test your theme?")
+            [
+                chalk.cyan(
+                    "On which version of Keycloak do you want to test your theme?"
+                ),
+                chalk.gray(
+                    "You can also explicitly provide the version with `npx keycloakify start-keycloak --keycloak-version 25.0.2` (or any other version)"
+                )
+            ].join("\n")
         );
 
         const { keycloakVersion } = await promptKeycloakVersion({
             startingFromMajor: 18,
             excludeMajorVersions: [22],
-            cacheDirPath: buildContext.cacheDirPath
+            buildContext
         });
 
         console.log(`→ ${keycloakVersion}`);
 
-        return { keycloakVersion };
+        return { dockerImageTag: keycloakVersion };
     })();
 
-    const keycloakMajorVersionNumber = SemVer.parse(keycloakVersion).major;
+    const keycloakMajorVersionNumber = (() => {
+        if (buildContext.startKeycloakOptions.dockerImage === undefined) {
+            return SemVer.parse(dockerImageTag).major;
+        }
+
+        const { tag } = buildContext.startKeycloakOptions.dockerImage;
+
+        const [wrap] = [18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28]
+            .map(majorVersionNumber => ({
+                majorVersionNumber,
+                index: tag.indexOf(`${majorVersionNumber}`)
+            }))
+            .filter(({ index }) => index !== -1)
+            .sort((a, b) => a.index - b.index);
+
+        if (wrap === undefined) {
+            console.warn(
+                chalk.yellow(
+                    `Could not determine the major Keycloak version number from the docker image tag ${tag}. Assuming 25`
+                )
+            );
+            return 25;
+        }
+
+        return wrap.majorVersionNumber;
+    })();
 
     {
         const { isAppBuildSuccess } = await appBuild({
@@ -150,26 +186,50 @@ export async function command(params: { cliCommandOptions: CliCommandOptions })
 
     assert(jarFilePath !== undefined);
 
-    console.log(`Using ${chalk.bold(pathBasename(jarFilePath))}`);
+    const extensionJarFilePaths = await Promise.all(
+        buildContext.startKeycloakOptions.extensionJars.map(async extensionJar => {
+            switch (extensionJar.type) {
+                case "path": {
+                    assert(
+                        await existsAsync(extensionJar.path),
+                        `${extensionJar.path} does not exist`
+                    );
+                    return extensionJar.path;
+                }
+                case "url": {
+                    const { archiveFilePath } = await downloadAndExtractArchive({
+                        cacheDirPath: buildContext.cacheDirPath,
+                        fetchOptions: buildContext.fetchOptions,
+                        urlOrPath: extensionJar.url,
+                        uniqueIdOfOnArchiveFile: "no extraction",
+                        onArchiveFile: async () => {}
+                    });
+                    return archiveFilePath;
+                }
+            }
+            assert<Equals<typeof extensionJar, never>>(false);
+        })
+    );
 
     const realmJsonFilePath = await (async () => {
         if (cliCommandOptions.realmJsonFilePath !== undefined) {
             if (cliCommandOptions.realmJsonFilePath === "none") {
                 return undefined;
             }
-
-            console.log(
-                chalk.green(
-                    `Using realm json file: ${cliCommandOptions.realmJsonFilePath}`
-                )
-            );
-
             return getAbsoluteAndInOsFormatPath({
                 pathIsh: cliCommandOptions.realmJsonFilePath,
                 cwd: process.cwd()
             });
         }
 
+        if (buildContext.startKeycloakOptions.realmJsonFilePath !== undefined) {
+            assert(
+                await existsAsync(buildContext.startKeycloakOptions.realmJsonFilePath),
+                `${pathRelative(process.cwd(), buildContext.startKeycloakOptions.realmJsonFilePath)} does not exist`
+            );
+            return buildContext.startKeycloakOptions.realmJsonFilePath;
+        }
+
         const internalFilePath = await (async () => {
             const dirPath = pathJoin(
                 getThisCodebaseRootDirPath(),
@@ -274,77 +334,89 @@ export async function command(params: { cliCommandOptions: CliCommandOptions })
         });
     } catch {}
 
-    const spawnArgs = [
-        "docker",
-        [
-            "run",
-            ...["-p", `${cliCommandOptions.port}:8080`],
-            ...["--name", CONTAINER_NAME],
-            ...["-e", "KEYCLOAK_ADMIN=admin"],
-            ...["-e", "KEYCLOAK_ADMIN_PASSWORD=admin"],
-            ...(realmJsonFilePath === undefined
-                ? []
-                : [
-                      "-v",
-                      `"${realmJsonFilePath}":/opt/keycloak/data/import/myrealm-realm.json`
-                  ]),
-            ...[
-                "-v",
-                `"${jarFilePath_cacheDir}":/opt/keycloak/providers/keycloak-theme.jar`
-            ],
-            ...(keycloakMajorVersionNumber <= 20
-                ? ["-e", "JAVA_OPTS=-Dkeycloak.profile=preview"]
-                : []),
-            ...[
-                ...buildContext.themeNames,
-                ...(fs.existsSync(
-                    pathJoin(
-                        buildContext.keycloakifyBuildDirPath,
-                        "theme",
-                        ACCOUNT_V1_THEME_NAME
-                    )
-                )
-                    ? [ACCOUNT_V1_THEME_NAME]
-                    : [])
-            ]
-                .map(themeName => ({
-                    localDirPath: pathJoin(
-                        buildContext.keycloakifyBuildDirPath,
-                        "theme",
-                        themeName
-                    ),
-                    containerDirPath: `/opt/keycloak/themes/${themeName}`
-                }))
-                .map(({ localDirPath, containerDirPath }) => [
-                    "-v",
-                    `"${localDirPath}":${containerDirPath}:rw`
-                ])
-                .flat(),
-            ...buildContext.environmentVariables
-                .map(({ name }) => ({ name, envValue: process.env[name] }))
-                .map(({ name, envValue }) =>
-                    envValue === undefined ? undefined : { name, envValue }
-                )
-                .filter(exclude(undefined))
-                .map(({ name, envValue }) => [
-                    "--env",
-                    `${name}='${envValue.replace(/'/g, "'\\''")}'`
-                ])
-                .flat(),
-            `quay.io/keycloak/keycloak:${keycloakVersion}`,
-            "start-dev",
-            ...(21 <= keycloakMajorVersionNumber && keycloakMajorVersionNumber < 24
-                ? ["--features=declarative-user-profile"]
-                : []),
-            ...(realmJsonFilePath === undefined ? [] : ["--import-realm"])
-        ],
-        {
-            cwd: buildContext.keycloakifyBuildDirPath,
-            shell: true
-        }
-    ] as const;
+    const SPACE_PLACEHOLDER = "SPACE_PLACEHOLDER_xKLmdPd";
 
-    const child = child_process.spawn(...spawnArgs);
+    const dockerRunArgs: string[] = [
+        `-p${SPACE_PLACEHOLDER}${cliCommandOptions.port}:8080`,
+        `--name${SPACE_PLACEHOLDER}${CONTAINER_NAME}`,
+        `-e${SPACE_PLACEHOLDER}KEYCLOAK_ADMIN=admin`,
+        `-e${SPACE_PLACEHOLDER}KEYCLOAK_ADMIN_PASSWORD=admin`,
+        ...(realmJsonFilePath === undefined
+            ? []
+            : [
+                  `-v${SPACE_PLACEHOLDER}".${pathSep}${pathRelative(process.cwd(), realmJsonFilePath)}":/opt/keycloak/data/import/myrealm-realm.json`
+              ]),
+        `-v${SPACE_PLACEHOLDER}"./${pathRelative(process.cwd(), jarFilePath_cacheDir)}":/opt/keycloak/providers/keycloak-theme.jar`,
+        ...extensionJarFilePaths.map(
+            jarFilePath =>
+                `-v${SPACE_PLACEHOLDER}".${pathSep}${pathRelative(process.cwd(), jarFilePath)}":/opt/keycloak/providers/${pathBasename(jarFilePath)}`
+        ),
+        ...(keycloakMajorVersionNumber <= 20
+            ? [`-e${SPACE_PLACEHOLDER}JAVA_OPTS=-Dkeycloak.profile=preview`]
+            : []),
+        ...[
+            ...buildContext.themeNames,
+            ...(fs.existsSync(
+                pathJoin(
+                    buildContext.keycloakifyBuildDirPath,
+                    "theme",
+                    ACCOUNT_V1_THEME_NAME
+                )
+            )
+                ? [ACCOUNT_V1_THEME_NAME]
+                : [])
+        ]
+            .map(themeName => ({
+                localDirPath: pathJoin(
+                    buildContext.keycloakifyBuildDirPath,
+                    "theme",
+                    themeName
+                ),
+                containerDirPath: `/opt/keycloak/themes/${themeName}`
+            }))
+            .map(
+                ({ localDirPath, containerDirPath }) =>
+                    `-v${SPACE_PLACEHOLDER}".${pathSep}${pathRelative(process.cwd(), localDirPath)}":${containerDirPath}:rw`
+            ),
+        ...buildContext.environmentVariables
+            .map(({ name }) => ({ name, envValue: process.env[name] }))
+            .map(({ name, envValue }) =>
+                envValue === undefined ? undefined : { name, envValue }
+            )
+            .filter(exclude(undefined))
+            .map(
+                ({ name, envValue }) =>
+                    `--env${SPACE_PLACEHOLDER}${name}='${envValue.replace(/'/g, "'\\''")}'`
+            ),
+        ...buildContext.startKeycloakOptions.dockerExtraArgs.join(SPACE_PLACEHOLDER),
+        `${buildContext.startKeycloakOptions.dockerImage?.reference ?? "quay.io/keycloak/keycloak"}:${dockerImageTag}`,
+        "start-dev",
+        ...(21 <= keycloakMajorVersionNumber && keycloakMajorVersionNumber < 24
+            ? ["--features=declarative-user-profile"]
+            : []),
+        ...(realmJsonFilePath === undefined ? [] : ["--import-realm"]),
+        ...buildContext.startKeycloakOptions.keycloakExtraArgs.join(SPACE_PLACEHOLDER)
+    ];
+
+    console.log(
+        chalk.blue(
+            [
+                `$ docker run \\`,
+                ...dockerRunArgs
+                    .map(arg => arg.replace(new RegExp(SPACE_PLACEHOLDER, "g"), " "))
+                    .map(
+                        (line, i, arr) =>
+                            `    ${line}${arr.length - 1 === i ? "" : " \\"}`
+                    )
+            ].join("\n")
+        )
+    );
+
+    const child = child_process.spawn(
+        "docker",
+        ["run", ...dockerRunArgs.map(line => line.split(SPACE_PLACEHOLDER)).flat()],
+        { shell: true }
+    );
 
     child.stdout.on("data", data => process.stdout.write(data));
 

src/bin/tools/assertNoPnpmDlx.ts

@@ -5,9 +5,11 @@ export function assertNoPnpmDlx() {
     if (__dirname.includes(`${pathSep}pnpm${pathSep}dlx${pathSep}`)) {
         console.log(
             [
-                chalk.red("Please don't use `pnpm dlx keycloakify`"),
+                chalk.red(
+                    "Please don't use `pnpm dlx keycloakify` (download and execute)"
+                ),
                 "\nUse `npx keycloakify` or `pnpm exec keycloakify` instead since you want to use the keycloakify",
-                "version that is installed in your project and not the latest version on NPM."
+                "version that is installed in your project and not download and run the latest NPM version of keycloakify."
             ].join(" ")
         );
         process.exit(1);

src/bin/tools/downloadAndExtractArchive.ts

@@ -1,15 +1,15 @@
 import fetch, { type FetchOptions } from "make-fetch-happen";
 import { mkdir, unlink, writeFile, readdir, readFile } from "fs/promises";
-import { dirname as pathDirname, join as pathJoin } from "path";
+import { dirname as pathDirname, join as pathJoin, basename as pathBasename } from "path";
 import { assert } from "tsafe/assert";
 import { extractArchive } from "./extractArchive";
 import { existsAsync } from "./fs.existsAsync";
-
 import * as crypto from "crypto";
 import { rm } from "./fs.rm";
+import * as fsPr from "fs/promises";
 
 export async function downloadAndExtractArchive(params: {
-    url: string;
+    urlOrPath: string;
     uniqueIdOfOnArchiveFile: string;
     onArchiveFile: (params: {
         fileRelativePath: string;
@@ -21,15 +21,34 @@ export async function downloadAndExtractArchive(params: {
     }) => Promise<void>;
     cacheDirPath: string;
     fetchOptions: FetchOptions | undefined;
-}): Promise<{ extractedDirPath: string }> {
-    const { url, uniqueIdOfOnArchiveFile, onArchiveFile, cacheDirPath, fetchOptions } =
-        params;
+}): Promise<{ extractedDirPath: string; archiveFilePath: string; }> {
+    const {
+        urlOrPath,
+        uniqueIdOfOnArchiveFile,
+        onArchiveFile,
+        cacheDirPath,
+        fetchOptions
+    } = params;
 
-    const archiveFileBasename = url.split("?")[0].split("/").reverse()[0];
+    const isUrl = /^https?:\/\//.test(urlOrPath);
+
+    const archiveFileBasename = isUrl
+        ? urlOrPath.split("?")[0].split("/").reverse()[0]
+        : pathBasename(urlOrPath);
 
     const archiveFilePath = pathJoin(cacheDirPath, archiveFileBasename);
 
     download: {
+        await mkdir(pathDirname(archiveFilePath), { recursive: true });
+
+        if (!isUrl) {
+            await fsPr.copyFile(urlOrPath, archiveFilePath);
+
+            break download;
+        }
+
+        const url = urlOrPath;
+
         if (await existsAsync(archiveFilePath)) {
             const isDownloaded = await SuccessTracker.getIsDownloaded({
                 cacheDirPath,
@@ -48,8 +67,6 @@ export async function downloadAndExtractArchive(params: {
             });
         }
 
-        await mkdir(pathDirname(archiveFilePath), { recursive: true });
-
         const response = await fetch(url, fetchOptions);
 
         response.body?.setMaxListeners(Number.MAX_VALUE);
@@ -136,7 +153,7 @@ export async function downloadAndExtractArchive(params: {
         });
     }
 
-    return { extractedDirPath };
+    return { extractedDirPath, archiveFilePath };
 }
 
 type SuccessTracker = {

src/bin/tools/fetchProxyOptions.ts

@@ -1,6 +1,7 @@
 import { type FetchOptions } from "make-fetch-happen";
 import * as child_process from "child_process";
 import * as fs from "fs";
+import { exclude } from "tsafe/exclude";
 
 export type ProxyFetchOptions = Pick<
     FetchOptions,
@@ -23,12 +24,32 @@ export function getProxyFetchOptions(params: {
             .split("\n")
             .filter(line => !line.startsWith(";"))
             .map(line => line.trim())
-            .map(line => line.split("=", 2) as [string, string])
+            .map(line => {
+                const [key, value] = line.split("=");
+                if (key === undefined) {
+                    return undefined;
+                }
+                if (value === undefined) {
+                    return undefined;
+                }
+                return [key.trim(), value.trim()] as const;
+            })
+            .filter(exclude(undefined))
+            .filter(([key]) => key !== "")
+            .map(([key, value]) => {
+                if (value.startsWith('"') && value.endsWith('"')) {
+                    return [key, value.slice(1, -1)] as const;
+                }
+
+                if (value === "true" || value === "false") {
+                    return [key, value] as const;
+                }
+
+                return undefined;
+            })
+            .filter(exclude(undefined))
             .reduce(
-                (
-                    cfg: Record<string, string | string[]>,
-                    [key, value]: [string, string]
-                ) =>
+                (cfg: Record<string, string | string[]>, [key, value]) =>
                     key in cfg
                         ? { ...cfg, [key]: [...ensureArray(cfg[key]), value] }
                         : { ...cfg, [key]: value },
@@ -37,18 +58,18 @@ export function getProxyFetchOptions(params: {
     })();
 
     const proxy = ensureSingleOrNone(cfg["https-proxy"] ?? cfg["proxy"]);
+
     const noProxy = cfg["noproxy"] ?? cfg["no-proxy"];
 
-    function maybeBoolean(arg0: string | undefined) {
-        return typeof arg0 === "undefined" ? undefined : Boolean(arg0);
-    }
+    const strictSSL = ensureSingleOrNone(cfg["strict-ssl"]) === "true";
 
-    const strictSSL = maybeBoolean(ensureSingleOrNone(cfg["strict-ssl"]));
     const cert = cfg["cert"];
+
     const ca = ensureArray(cfg["ca"] ?? cfg["ca[]"]);
+
     const cafile = ensureSingleOrNone(cfg["cafile"]);
 
-    if (typeof cafile !== "undefined" && cafile !== "null") {
+    if (cafile !== undefined) {
         ca.push(
             ...(() => {
                 const cafileContent = fs.readFileSync(cafile).toString("utf8");
@@ -82,7 +103,7 @@ export function getProxyFetchOptions(params: {
 }
 
 function ensureArray<T>(arg0: T | T[]) {
-    return Array.isArray(arg0) ? arg0 : typeof arg0 === "undefined" ? [] : [arg0];
+    return Array.isArray(arg0) ? arg0 : arg0 === undefined ? [] : [arg0];
 }
 
 function ensureSingleOrNone<T>(arg0: T | T[]) {

src/login/KcContext/KcContext.ts

@@ -79,8 +79,8 @@ export declare namespace KcContext {
         };
         realm: {
             name: string;
-            displayName?: string;
-            displayNameHtml?: string;
+            displayName: string;
+            displayNameHtml: string;
             internationalizationEnabled: boolean;
             registrationEmailAsUsername: boolean;
         };

src/login/Template.tsx

@@ -224,19 +224,17 @@ export default function Template(props: TemplateProps<KcContext, I18n>) {
                         {auth !== undefined && auth.showTryAnotherWayLink && (
                             <form id="kc-select-try-another-way-form" action={url.loginAction} method="post">
                                 <div className={kcClsx("kcFormGroupClass")}>
-                                    <div className={kcClsx("kcFormGroupClass")}>
-                                        <input type="hidden" name="tryAnotherWay" value="on" />
-                                        <a
-                                            href="#"
-                                            id="try-another-way"
-                                            onClick={() => {
-                                                document.forms["kc-select-try-another-way-form" as never].submit();
-                                                return false;
-                                            }}
-                                        >
-                                            {msg("doTryAnotherWay")}
-                                        </a>
-                                    </div>
+                                    <input type="hidden" name="tryAnotherWay" value="on" />
+                                    <a
+                                        href="#"
+                                        id="try-another-way"
+                                        onClick={() => {
+                                            document.forms["kc-select-try-another-way-form" as never].submit();
+                                            return false;
+                                        }}
+                                    >
+                                        {msg("doTryAnotherWay")}
+                                    </a>
                                 </div>
                             </form>
                         )}

src/login/i18n/i18n.tsx

@@ -217,7 +217,13 @@ function createI18nTranslationFunctionsFactory<MessageKey_themeDefined extends s
 
                 messageWithArgsInjected = messageWithArgsInjected.replace(
                     new RegExp(`\\{${i + startIndex}\\}`, "g"),
-                    arg.replace(/</g, "&lt;").replace(/>/g, "&gt;")
+                    (() => {
+                        if (key === "loginTitleHtml") {
+                            return arg;
+                        }
+
+                        return arg.replace(/</g, "&lt;").replace(/>/g, "&gt;");
+                    })()
                 );
             });
 

stories/login/pages/Login.stories.tsx

@@ -122,73 +122,85 @@ export const WithSocialProviders: Story = {
                             loginUrl: "google",
                             alias: "google",
                             providerId: "google",
-                            displayName: "Google"
+                            displayName: "Google",
+                            iconClasses: "fa fa-google"
                         },
                         {
                             loginUrl: "microsoft",
                             alias: "microsoft",
                             providerId: "microsoft",
-                            displayName: "Microsoft"
+                            displayName: "Microsoft",
+                            iconClasses: "fa fa-windows"
                         },
                         {
                             loginUrl: "facebook",
                             alias: "facebook",
                             providerId: "facebook",
-                            displayName: "Facebook"
+                            displayName: "Facebook",
+                            iconClasses: "fa fa-facebook"
                         },
                         {
                             loginUrl: "instagram",
                             alias: "instagram",
                             providerId: "instagram",
-                            displayName: "Instagram"
+                            displayName: "Instagram",
+                            iconClasses: "fa fa-instagram"
                         },
                         {
                             loginUrl: "twitter",
                             alias: "twitter",
                             providerId: "twitter",
-                            displayName: "Twitter"
+                            displayName: "Twitter",
+                            iconClasses: "fa fa-twitter"
                         },
                         {
                             loginUrl: "linkedin",
                             alias: "linkedin",
                             providerId: "linkedin",
-                            displayName: "LinkedIn"
+                            displayName: "LinkedIn",
+                            iconClasses: "fa fa-linkedin"
                         },
                         {
                             loginUrl: "stackoverflow",
                             alias: "stackoverflow",
                             providerId: "stackoverflow",
-                            displayName: "Stackoverflow"
+                            displayName: "Stackoverflow",
+                            iconClasses: "fa fa-stack-overflow"
                         },
                         {
                             loginUrl: "github",
                             alias: "github",
                             providerId: "github",
-                            displayName: "Github"
+                            displayName: "Github",
+                            iconClasses: "fa fa-github"
                         },
                         {
                             loginUrl: "gitlab",
                             alias: "gitlab",
                             providerId: "gitlab",
-                            displayName: "Gitlab"
+                            displayName: "Gitlab",
+                            iconClasses: "fa fa-gitlab"
                         },
                         {
                             loginUrl: "bitbucket",
                             alias: "bitbucket",
                             providerId: "bitbucket",
-                            displayName: "Bitbucket"
+                            displayName: "Bitbucket",
+                            iconClasses: "fa fa-bitbucket"
                         },
                         {
                             loginUrl: "paypal",
                             alias: "paypal",
                             providerId: "paypal",
-                            displayName: "PayPal"
+                            displayName: "PayPal",
+                            iconClasses: "fa fa-paypal"
                         },
                         {
                             loginUrl: "openshift",
                             alias: "openshift",
                             providerId: "openshift",
-                            displayName: "OpenShift"
+                            displayName: "OpenShift",
+                            iconClasses: "fa fa-cloud"
                         }
                     ]
                 }

yarn.lock

@@ -4518,7 +4518,7 @@ cheerio-select@^2.1.0:
     domhandler "^5.0.3"
     domutils "^3.0.1"
 
-cheerio@^1.0.0-rc.12:
+cheerio@1.0.0-rc.12:
   version "1.0.0-rc.12"
   resolved "https://registry.yarnpkg.com/cheerio/-/cheerio-1.0.0-rc.12.tgz#788bf7466506b1c6bf5fae51d24a2c4d62e47683"
   integrity sha512-VqR8m68vM46BNnuZ5NtnGBKIE/DfN0cRIzg9n40EIq9NOv90ayxLBXA8fXC5gquFRGJSTRqBq25Jt2ECLR431Q==
@@ -11332,7 +11332,7 @@ typedarray@^0.0.6:
   resolved "https://registry.yarnpkg.com/typedarray/-/typedarray-0.0.6.tgz#867ac74e3864187b1d3d47d996a78ec5c8830777"
   integrity sha512-/aCDEGatGvZ2BIk+HmLf4ifCJFwvKFNb9/JeZPMulfgFracn9QFcAf5GO8B/mweUjSoblS5In0cWhqpfs/5PQA==
 
-typescript@^4.9.1-beta:
+typescript@^4.9.4:
   version "4.9.5"
   resolved "https://registry.yarnpkg.com/typescript/-/typescript-4.9.5.tgz#095979f9bcc0d09da324d58d03ce8f8374cbe65a"
   integrity sha512-1FXk9E2Hm+QzZQ7z+McJiHL4NW1F2EzMu9Nq9i3zAaGqibafqYwCVU6WyWAuyQRRzOlxou8xZSyXLEN8oKj24g==