{"id":20263638,"url":"https://github.com/springerpe/cf-keycloak-buildpack","last_synced_at":"2026-05-23T16:31:47.863Z","repository":{"id":80987056,"uuid":"225371167","full_name":"SpringerPE/cf-keycloak-buildpack","owner":"SpringerPE","description":"CloudFoundry buildpack to run keycloak","archived":false,"fork":false,"pushed_at":"2019-12-02T15:49:19.000Z","size":92,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-14T04:44:37.207Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SpringerPE.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-12-02T12:35:01.000Z","updated_at":"2023-03-22T03:03:51.000Z","dependencies_parsed_at":null,"dependency_job_id":"b73f1648-a21b-443a-a46c-82658b33f210","html_url":"https://github.com/SpringerPE/cf-keycloak-buildpack","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpringerPE%2Fcf-keycloak-buildpack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpringerPE%2Fcf-keycloak-buildpack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpringerPE%2Fcf-keycloak-buildpack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpringerPE%2Fcf-keycloak-buildpack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SpringerPE","download_url":"https://codeload.github.com/SpringerPE/cf-keycloak-buildpack/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241731744,"owners_count":20010781,"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":[],"created_at":"2024-11-14T11:35:47.828Z","updated_at":"2026-05-23T16:31:42.838Z","avatar_url":"https://github.com/SpringerPE.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Keycloak application in CloudFoundry\n\nThis is a buildpack to run [Keycloak](https://www.keycloak.org) in\nCloud Foundry\n\nYou can find a test application example in `test-app` folder.\n\nBy default, the buildpack does not need any files to get Keycloak\nup and running in Cloud Foundry, but CF refuses to push an \n\"application\" from an empty folder (the manifest does not count\nas application bits!).\n\nIn order to get a single instance (Standalone Mode) of Keycloak up and running:\n\n1. In an empty folder create an empty file (random name): `touch hola.txt`\n2. Create a basic `manifest.yml`\n    ```\n    ---\n    applications:\n    - name: keycloak\n    memory: 1G\n    instances: 1\n    random-route: true\n    stack: cflinuxfs3\n    buildpacks:\n    - https://github.com/springernature/cf-keycloak-buildpack.git\n    env:\n        KEYCLOAK_USER: admin\n        KEYCLOAK_ADMIN_PASSWORD: admin\n        PROXY_ADDRESS_FORWARDING: true\n    ```\n3. Run `cf push` to get the app running in a random route.\n\nWe need the `PROXY_ADDRESS_FORWARDING` environment variable set to be `true`, as in Cloudfoundry the Keycloak app sits behind a load balancer/reverse proxy. This setting tells Keycloak to look at the `X-Forwarded-For` and `X-Forwarded-Proto` HTTP headers to learn which URL the user actually requested in its browser (instead of using the hostname used by the load balancer to reach this Keycloack app instance). See also the [Keycloack docs](https://www.keycloak.org/docs/latest/server_installation/index.html#_setting-up-a-load-balancer-or-proxy) for setting up Keycloak behind a load balancer.\n\nThe buildpack has support to automatically deploy Service Provider Interfaces (SPI's,\n*Keycloak extensions or plugins*). There needs to be a `spis` directory in the application root and the jars need to match this linux file pattern to be found: `spis/*/target/libs/*.jar`. When the application starts, WildFly will load these \nKeycloak plugins and they will be available in the application.\n\nFor extra documentation ...\n* about Cloudfoundry Buildpacks, go to https://github.com/springernature/cf-keycloak-buildpack/blob/master/docs/buildpack-howto.md\n* about Keycloak clustering, go to https://github.com/springernature/cf-keycloak-buildpack/blob/master/docs/keycloak-clustering.md\n\n\n## Considerations\n\n1. **Keycloak is built on top of the WildFly application server** and it’s sub-projects\nlike Infinispan (for caching) and Hibernate (for persistence). This guide only\ncovers basics for infrastructure-level configuration. It is highly recommended\nthat you peruse the documentation for WildFly and its sub projects: http://docs.wildfly.org/13/Admin_Guide.html\n2. Keycloak comes with its own embedded Java-based relational database called H2. \nThis is the default database that Keycloak will use to persist data and really\nonly exists so that you can run the authentication server out of the box. \n**It is highly recommended replace it with a more production ready external database**\n3. Keycloak uses the following as data sources:\n   * A database is used to persist permanent data, such as user information.\n   * An Infinispan cache is used to cache persistent data from the database and\n     also to save some short-lived and frequently-changing metadata, such as for\n     user sessions. Infinispan is usually much faster than a database, however the\n     data saved using Infinispan are not permanent and is not expected to persist\n     across cluster restarts.\n4. **Keycloak asumes that Proxy/LoadBalancers offer support for sticky sessions**, \nwhich means that the load balancer is able to always forward all HTTP requests\nfrom the same user to the same Keycloak instance in same data center.\nIt is generally wise to configure your environment to use loadbalancer with\nsticky sessions. It is beneficial for performance, please read:\nhttps://www.keycloak.org/docs/7.0/server_installation/#sticky-sessions\n\n\n## Optimizations\n\nBecause of previous considerations:\n\n1. Most of the buildpack actions and procedures are WildFly configuration procedures:\n   XML modules, SPI installation, etc . The buildpack is just an automated way of\n   installing the application in a container, so it is convenient understanding\n   the workflow of a manual installation first.\n2. Take into account the amount of memory assigned to the application, because\n   there are different kind of \"memories\" to consider. Also the amount of instances,\n   and load (request/s coming to the application), memory consumption of the SPI modules,\n   etc. Please, consider how much memory is assigned for:\n   * Application instance memory\n   * JVM memory settings\n   * Infinispan memory settings (for caching)\n3. CloudFoundry routing layer (GoRouters) is capable of performing sticky sessions\n   by using **JSESSIONID** cookie: https://docs.cloudfoundry.org/concepts/http-routing.html#sessions\n   and because of how Keycloak handles the sessions, this setting can\n   offer big improvements, specially if the cluster is big and with a lot of load.\n   Keycloak uses different cookie names, but it is possible to change the configuration\n   to define the cookie name.\n\n## Debugging\n\nYou can check the cluster view using `jboss-cli`:\n\n```\ncf ssh keycloak-poc\nexport PATH=$PATH:/home/vcap/deps/0/jdk/bin/:/home/vcap/deps/0/keycloak/bin/\njboss-cli.sh -c  '/subsystem=jgroups/channel=ee:read-attribute(name=view)'\n```\n\nThe result should contains as many instances as you declare:\n\n```\n{\n\"outcome\" =\u003e \"success\",\n\"result\" =\u003e \"[70d3d988-fb5a-4ceb-406c-6d04|1] (2) [70d3d988-fb5a-4ceb-406c-6d04, 14a493d4-3a48-4323-6287-7c56]\"\n}\n```\n\nIn general you can use `jboss-cli` to perform actions and retrieve information:\n\n```\njboss-cli.sh\nYou are disconnected at the moment. Type 'connect' to connect to the server or 'help' for the list of supported commands.\n[disconnected /] connect\n[standalone@localhost:9990 /] help\n\nSYNOPSIS\n\n    help ( [\u003ccommand or operation name\u003e] | [--commands] ) \n\n\nDESCRIPTION\n\n    Print the commands and operations help content.\n    Use completion to discover commands and operations. Here are some of the\n    most basic supported commands:\n    \n    cn (or cd)    - change the current node path to the argument.\n    connect       - connect to the server or domain controller.\n    deploy        - deploy an application.\n    history       - print or disable/enable/clear the history expansion.\n    ls            - list the contents of the node path.\n    pwn (or pwd)  - prints the current working node.\n    quit (or q)   - quit the command line interface.\n    undeploy      - undeploy an application.\n    version       - prints the version and environment information.\n\nALIASES\n\n    h\n\n\nOPTIONS\n\n    --commands  - List of available commands. The resulting listing may depend\n                  on the current context.E.g. some of the commands require an\n                  established connection to the controller (standalone or\n                  domain). These commands won't appear in the listing unless\n                  the connection has been established. Other commands may\n                  depend on the availability of specific subsystems. E.g. if\n                  the messaging subsystem is not available, messaging-related\n                  commands will not be listed.\n\n\nARGUMENT\n\n    The command or operation name.\n\n\n\n[standalone@localhost:9990 /] ls\ncore-service                               interface                                  system-property                            management-minor-version=0                 process-type=Server                        release-codename=                          schema-locations=[]                        \ndeployment                                 path                                       launch-type=STANDALONE                     name=eb41b601-74b8-41e6-4f24-aead          product-name=Keycloak                      release-version=8.0.0.Final                server-state=running                       \ndeployment-overlay                         socket-binding-group                       management-major-version=10                namespaces=[]                              product-version=6.0.1                      running-mode=NORMAL                        suspend-state=RUNNING                      \nextension                                  subsystem                                  management-micro-version=0                 organization=undefined                     profile-name=undefined                     runtime-configuration-state=ok             uuid=b719a480-2745-48d0-9968-b0d4187be6ba  \n\n[standalone@localhost:9990 /] version\nJBoss Admin Command-line Interface\nJBOSS_HOME: /home/vcap/deps/0/keycloak\nRelease: 8.0.0.Final\nProduct: Keycloak 6.0.1\nJAVA_HOME: null\njava.version: 11\njava.vm.vendor: Oracle Corporation\njava.vm.version: 11+28\nos.name: Linux\nos.version: 4.15.0-47-generic\n\n[standalone@localhost:9990 /] help --commands\nCommands available in the current context:\nattachment                              connection-info                         deployment disable-all                  deployment-info                         history                                 patch info                              run-batch                               security enable-http-auth-management    try                                     \nbatch                                   data-source                             deployment enable                       deployment-overlay                      if                                      patch inspect                           security disable-http-auth-http-server  security enable-sasl-management         undeploy                                \ncd                                      deploy                                  deployment enable-all                   echo                                    jdbc-driver-info                        pwd                                     security disable-http-auth-management   security enable-ssl-http-server         unset                                   \nclear                                   deployment deploy-cli-archive           deployment info                         echo-dmr                                ls                                      quit                                    security disable-sasl-management        security enable-ssl-management          version                                 \ncommand                                 deployment deploy-file                  deployment list                         for                                     module                                  read-attribute                          security disable-ssl-http-server        security reorder-sasl-management        xa-data-source                          \ncommand-timeout                         deployment deploy-url                   deployment undeploy                     grep                                    patch apply                             read-operation                          security disable-ssl-management         set                                     \nconnect                                 deployment disable                      deployment undeploy-cli-archive         help                                    patch history                           reload                                  security enable-http-auth-http-server   shutdown                                \nTo read a description of a specific command execute 'help \u003ccommand name\u003e'.\n\n[standalone@localhost:9990 /] deployment-info\nNAME                RUNTIME-NAME        PERSISTENT ENABLED STATUS \nkeycloak-server.war keycloak-server.war false      true    OK     \nnature-theme.jar    nature-theme.jar    false      true    OK     \n\n[standalone@localhost:9990 /] connection-info\nUsername               $local, granted role [\"SuperUser\"] \nLogged since           Thu Oct 10 14:08:20 UTC 2019       \nNot an SSL connection.                                    \n\n[standalone@localhost:9990 /] deployment list               \nkeycloak-server.war  nature-theme.jar     \n\n[standalone@localhost:9990 /] deployment info \nNAME                RUNTIME-NAME        PERSISTENT ENABLED STATUS \nkeycloak-server.war keycloak-server.war false      true    OK     \nnature-theme.jar    nature-theme.jar    false      true    OK     \n\n[standalone@localhost:9990 /] jdbc-driver-info\nNAME SOURCE                 \nh2   com.h2database.h2/main \n\n[standalone@localhost:9990 /] /subsystem=jgroups/channel=ee:read-attribute(name=view)\n{\n    \"outcome\" =\u003e \"success\",\n    \"result\" =\u003e \"[eb41b601-74b8-41e6-4f24-aead|0] (1) [eb41b601-74b8-41e6-4f24-aead]\"\n}\n\n[standalone@localhost:9990 /] quit\n```\n\n\n\n## Development\n\nBased on these resources:\n\n* Official docker images: https://github.com/keycloak/keycloak-containers/tree/master/server\n* Kubernetes helm chart: https://github.com/codecentric/helm-charts\n* Getting Started Guide: https://www.keycloak.org/docs/latest/getting_started/index.html\n* Server Installation and Configuration Guide: https://www.keycloak.org/docs/latest/server_installation/index.html\n* WildFly Getting Started Guide: http://docs.wildfly.org/18/Getting_Started_Guide.html\n\n\n## Author\n\nGerard Laan, Jose Riguera  \nEngineering Enablement, Springer Nature\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspringerpe%2Fcf-keycloak-buildpack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspringerpe%2Fcf-keycloak-buildpack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspringerpe%2Fcf-keycloak-buildpack/lists"}