{"id":27923325,"url":"https://github.com/slemke/keycloak-testcontainer","last_synced_at":"2025-05-06T22:32:27.491Z","repository":{"id":215058060,"uuid":"676066054","full_name":"slemke/keycloak-testcontainer","owner":"slemke","description":"Run a Keycloak testcontainer from node.js","archived":false,"fork":false,"pushed_at":"2025-05-06T07:03:25.000Z","size":718,"stargazers_count":4,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-06T07:57:18.847Z","etag":null,"topics":["container","docker","keycloak","node","testcontainers","testing","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/slemke.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-08-08T11:03:03.000Z","updated_at":"2025-05-06T07:03:29.000Z","dependencies_parsed_at":"2024-03-17T14:25:22.867Z","dependency_job_id":"0e998421-59ec-4acf-aa30-e77f25c3ee16","html_url":"https://github.com/slemke/keycloak-testcontainer","commit_stats":null,"previous_names":["slemke/keycloak-testcontainer"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slemke%2Fkeycloak-testcontainer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slemke%2Fkeycloak-testcontainer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slemke%2Fkeycloak-testcontainer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slemke%2Fkeycloak-testcontainer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/slemke","download_url":"https://codeload.github.com/slemke/keycloak-testcontainer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252779201,"owners_count":21802901,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["container","docker","keycloak","node","testcontainers","testing","typescript"],"created_at":"2025-05-06T22:31:52.259Z","updated_at":"2025-05-06T22:32:27.478Z","avatar_url":"https://github.com/slemke.png","language":"TypeScript","funding_links":[],"categories":["Community Extensions"],"sub_categories":[],"readme":"# keycloak-testcontainer\n\nThis package adds the ability to start keycloak as a testcontainer in node.js.\n\n## Install\n\n```\nnpm install keycloak-testcontainer --save-dev\n```\n\nES6 import\n```js\nimport KeycloakContainer from 'keycloak-testcontainer';\n```\n\nCommon js import:\n```js\nconst KeycloakContainer = require('keycloak-testcontainer').default;\n```\n\n## Keycloak Version Support\n\nCurrently, this package only supports the latest version of Keycloak.\nOlder releases will work for older versions, but don't expect new releases to work\nfor older Keycloak versions.\n\n## Node Version Support\n\nThis package supports node.js version 18 and higher. This package has also been build and tested for non-lts releases.\n\n## Example\n\nYou can start a keycloak container with a few lines of code:\n\n```js\nimport KeycloakContainer from 'keycloak-testcontainer';\n\ndescribe('Keycloak Testcontainer Example', () =\u003e {\n\n    it('should run against keycloak', async () =\u003e {\n        const container = await new KeycloakContainer().start();\n\n        // do something with the container\n\n        await container.stop();\n    });\n});\n```\n\n## Features\n\nCurrently, this package provides the following features:\n\n### Starting a container\n\n```js\nimport KeycloakContainer from 'keycloak-testcontainer';\n\nconst container = await new KeycloakContainer()\n    .start();\n```\n\nBy default, every container is always a Keycloak in development mode.\n\n\n### Starting a container with a custom version\n\nYou can start the container with a custom version by providing a tag (default: `latest`) to the constructor.\nA list of possible values for the tag can be found on [Keycloaks repository page on quay.io](https://quay.io/repository/keycloak/keycloak?tab=tags).\n\n```js\nimport KeycloakContainer from 'keycloak-testcontainer';\n\nconst container = await new KeycloakContainer({ tag: '26.0' })\n    .start();\n```\n\nUsing the example above a Keycloak container should start with version 26.0 as long as the image with the tag is available on quay.io. If the tag you are using is not available you'll see an error similar to the error below:\n\n```\nError: (HTTP code 404) unexpected - manifest for quay.io/keycloak/keycloak:21 not found: manifest unknown: manifest unknown\n```\n\n### Starting a container with a custom registry\n\nIf you want to run an image from a different registry you can provide a registry to the container like so:\n\n```js\nimport KeycloakContainer from 'keycloak-testcontainer';\n\nconst container = await new KeycloakContainer({\n        registry: 'intern.org/keycloak/keycloak'\n    })\n    .start();\n```\n\nWith the custom registry the testcontainer tries to start with the following image: `intern.org/keycloak/keycloak:latest`.\nYou also can combine this with a custom tag:\n\n```js\nimport KeycloakContainer from 'keycloak-testcontainer';\n\nconst container = await new KeycloakContainer({\n        registry: 'intern.org/keycloak/keycloak',\n        tag: 'intern-rc-22'\n    })\n    .start();\n```\n\nThis would result in the following image being used:  `intern.org/keycloak/keycloak:intern-rc-22`\n\n### Starting a container with Keycloak commands\n\nYou can run this testcontainer with a bunch of different commands to obtain different Keycloak functionality. For a deeper explaination and up to date documentation have a look at the [Keycloak guides](https://www.keycloak.org/guides).\n\n### With metrics\n\nTo enable Keycloaks metrics endpoint start the container with the following command:\n\n```js\nconst container = await new KeycloakContainer()\n    .withMetrics()\n    .start();\n```\n\n### With features\n\nKeycloak provides different additional or experimental features. A list of the supported features can be found [here](https://www.keycloak.org/server/features#_supported_features). To enable additional features start the container with the following command:\n\n```js\nconst container = await new KeycloakContainer()\n    .withFeatures([\n        'docker',\n        'token-exchange'\n    ])\n    .start();\n```\n\n### With disabled features\n\nKeycloak allows to disable certain features. A list of the supported features can be found [here](https://www.keycloak.org/server/features#_supported_features). To disable certain features start the container with the following command:\n\n```js\nconst container = await new KeycloakContainer()\n    .withDisabledFeatures([\n        'impersonation',\n    ])\n    .start();\n```\n\n### With custom admin user\n\nTo start the Keycloak container with a custom admin user start the container with the following command:\n\n```js\nconst container = await new KeycloakContainer()\n    .withAdminUser({\n        username: 'admin',\n        password: 'password'\n    })\n    .start();\n```\n\n### With database\n\nKeycloak runs by default with a h2 database. To run Keycloak with a different database (for example postgres) you can start the container with the following command:\n\n```js\nconst container = await new KeycloakContainer()\n    .withDatabase({\n        vendor: 'postgres',\n        url: 'your-jdbc-url-here',\n        username: 'dbuser',\n        password: 'dbpassword'\n    });\n    .start();\n```\n\n### With realm import\n\nTo start the Keycloak container with a custom realm you can start the container with the following command:\n\n```js\nconst container = await new KeycloakContainer()\n    .withRealmImport('/path/to/realm/data')\n    .start();\n```\n\n### With providers\n\nTo add custom providers start the container with the following command:\n\n```js\nconst container = await new KeycloakContainer()\n    .withProviders('/path/to/providers')\n    .start();\n```\n\n### With health\n\nTo enable Keycloaks health endpoint start the container with the following command:\n\n```js\nconst container = await new KeycloakContainer()\n    .withHealth()\n    .start();\n```\n\n### With custom hostname\n\nTo run Keycloak with a custom hostname start the container with the following command:\n\n```js\nconst container = await new KeycloakContainer()\n    .withHostname('localhost')\n    .start();\n```\n\n### With custom hostname path\n\nTo run Keycloak with a custom hostname path (default: `/`) start the container with the following command:\n\n```js\nconst container = await new KeycloakContainer()\n    .withHostnamePath('/auth')\n    .start();\n```\n\n### With management port\n\nYou can change the default management port (`9000`) with the following command:\n\n```js\nconst container = await new KeycloakContainer()\n    .withManagementPort(9001)\n    .start();\n```\n\n### With management path\n\nYou can change the default path for the management interface (`/`) with the following command:\n\n```js\nconst container = await new KeycloakContainer()\n    .withManagementPath('/admin')\n    .start();\n```\n\n### With theme caching disabled\n\nTo disable theme caching start the container with the following command:\n\n```js\nconst container = await new KeycloakContainer()\n    .withThemeCacheDisabled()\n    .start();\n```\n\n### Stopping a container\n\n```js\nimport KeycloakContainer from 'keycloak-testcontainer';\n\nconst container = await new KeycloakContainer()\n    .start();\nawait container.stop();\n```\n\n### Restarting a container\n\n```js\nimport KeycloakContainer from 'keycloak-testcontainer';\n\nconst container = await new KeycloakContainer()\n    .start();\nawait container.restart();\n```\n\n### Admin Client\n\nIt is possible to obtain an [admin client](https://www.npmjs.com/package/@keycloak/keycloak-admin-client) for the test container after starting the container. This admin client can be used to change configuration for different tests. You can obtain an admin client with the following command:\n\n```js\nconst container = await new KeycloakContainer()\n    .start();\n\ncontainer.getAdminClient({\n    baseUrl: 'http://localhost:8080',\n    realmName: 'master',\n    totp: '123456'\n});\n```\n\nThe admin client can be customized by using an options object. By default the admin client uses `http://localhost:8080` as the base url and the default admin credentials. If you changed the admin credentials by using `withAdminUser(username, password)` the new credentials will be used by the admin client and don't need to be passed as an option.\n\nCurrently, the client accepts the following options (all of them are optional):\n\n* `baseUrl`: The url pointing to keycloak\n* `realmName`: The name of the realm (default: `master`)\n* `totp`: optional one-time password (if required)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslemke%2Fkeycloak-testcontainer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fslemke%2Fkeycloak-testcontainer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslemke%2Fkeycloak-testcontainer/lists"}