{"id":26996007,"url":"https://github.com/peter-mghendi/cloakroom","last_synced_at":"2025-04-04T01:16:50.926Z","repository":{"id":274312509,"uuid":"914492987","full_name":"peter-mghendi/cloakroom","owner":"peter-mghendi","description":"Minimal plugin manager for Keycloak.","archived":false,"fork":false,"pushed_at":"2025-01-26T14:18:25.000Z","size":51,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-26T14:28:19.392Z","etag":null,"topics":["keycloak","plugin-manager"],"latest_commit_sha":null,"homepage":"","language":"Go","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/peter-mghendi.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":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-09T17:49:13.000Z","updated_at":"2025-01-26T14:18:28.000Z","dependencies_parsed_at":"2025-01-26T14:39:47.607Z","dependency_job_id":null,"html_url":"https://github.com/peter-mghendi/cloakroom","commit_stats":null,"previous_names":["peter-mghendi/cloakroom"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-mghendi%2Fcloakroom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-mghendi%2Fcloakroom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-mghendi%2Fcloakroom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peter-mghendi%2Fcloakroom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peter-mghendi","download_url":"https://codeload.github.com/peter-mghendi/cloakroom/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247103296,"owners_count":20884024,"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":["keycloak","plugin-manager"],"created_at":"2025-04-04T01:16:50.522Z","updated_at":"2025-04-04T01:16:50.916Z","avatar_url":"https://github.com/peter-mghendi.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Build + Test](https://github.com/peter-mghendi/cloakroom/actions/workflows/build.yml/badge.svg)](https://github.com/peter-mghendi/cloakroom/actions/workflows/build.yml)\n\n# Cloakroom\n\u003e **Minimal plugin manager for Keycloak**  \n\u003e Centralize, streamline, and automate your Keycloak plugin management with Cloakroom.\n\n---\n\n## TL;DR\n\nCloakroom transforms your plugin installation process from a **long series of ADD lines** into a **single restore step**. \nInstead of cluttering your Dockerfile (or bash scripts) with multiple calls to fetch JARs from GitHub Releases, you simply define your plugins in Cloakroom’s manifest. \nCloakroom then downloads them all in one go.\n\nBefore (manual plugin additions):\n\n```dockerfile\nFROM quay.io/keycloak/keycloak:26.1.0\n\nADD --chown=keycloak:keycloak https://github.com/klausbetz/apple-identity-provider-keycloak/releases/download/1.7.1/apple-identity-provider-1.7.1.jar /opt/keycloak/providers/apple-identity-provider-1.7.1.jar\nADD --chown=keycloak:keycloak https://github.com/mesutpiskin/keycloak-2fa-email-authenticator/releases/download/v0.4/keycloak-2fa-email-authenticator-v0.4-KC21.1.1.jar /opt/keycloak/providers/keycloak-2fa-email-authenticator-v0.4-KC21.1.1.jar\nADD --chown=keycloak:keycloak https://github.com/slemke/keycloak-backup-email/releases/download/v0.0.1/keycloak-backup-email.jar /opt/keycloak/providers/keycloak-backup-email.jar\nADD --chown=keycloak:keycloak https://github.com/leroyguillaume/keycloak-bcrypt/releases/download/v1.6.0/keycloak-bcrypt-1.6.0.jar /opt/keycloak/providers/keycloak-bcrypt-1.6.0.jar\nADD --chown=keycloak:keycloak https://github.com/wadahiro/keycloak-discord/releases/download/v0.5.0/keycloak-discord-0.5.0.jar /opt/keycloak/providers/keycloak-discord-0.5.0.jar\nADD --chown=keycloak:keycloak https://github.com/SnuK87/keycloak-kafka/releases/download/1.2.0/keycloak-kafka-1.2.0-jar-with-dependencies.jar /opt/keycloak/providers/keycloak-kafka-1.2.0-jar-with-dependencies.jar\nADD --chown=keycloak:keycloak https://github.com/aerogear/keycloak-metrics-spi/releases/download/7.0.0/keycloak-metrics-spi-7.0.0.jar /opt/keycloak/providers/keycloak-metrics-spi-7.0.0.jar\nADD --chown=keycloak:keycloak https://github.com/slemke/keycloak-terms-authenticator/releases/download/v0.0.1/keycloak-terms-authenticator-0.0.1.jar /opt/keycloak/providers/keycloak-terms-authenticator-0.0.1.jar\n\n# etc etc\n\nENTRYPOINT [\"/opt/keycloak/bin/kc.sh\", \"start\", \"--optimized\"]\n```\n\nAfter (using Cloakroom):\n\n```dockerfile\nFROM quay.io/keycloak/keycloak:26.1.0\n\nARG CLOAKROOM_WARDROBE=/opt/keycloak/providers\nADD --chmod=+x https://github.com/peter-mghendi/cloakroom/releases/download/v0.1.2/cloakroom-v0.1.2_linux_x86_64 /usr/local/bin/cloakroom\nRUN cloakroom restore\n\nENTRYPOINT [\"/opt/keycloak/bin/kc.sh\", \"start\", \"--optimized\"]\n```\n\nNo more repetitive lines for each plugin—Cloakroom’s manifest contains those details.\nA single cloakroom restore command downloads everything, keeping your Dockerfile (and your sanity) intact.\n\n---\n\n## Table of Contents\n1. [What is Cloakroom?](#what-is-cloakroom)\n2. [Why Use Cloakroom?](#why-use-cloakroom)\n3. [Features](#features)\n4. [Installation \u0026 Setup](#installation--setup)\n5. [Configuration Overview](#configuration-overview)\n6. [Usage](#usage)\n   - [Commands](#commands)\n   - [Examples](#examples)\n7. [Configuration Examples](#configuration-examples)\n8. [Handling Multiple Manifests](#handling-multiple-manifests)\n9. [FAQ](#faq)\n10. [Contributing](#contributing)\n11. [License](#license)\n\n---\n\n## What is Cloakroom?\nCloakroom is a **command-line utility** for managing **Keycloak** plugins in a straightforward way. Instead of manually fetching JARs from GitHub Releases (or other endpoints) within your Dockerfiles or scripts, you define them in Cloakroom’s **manifest**. Cloakroom then downloads these artifacts into your Keycloak providers directory as specified by the `CLOAKROOM_WARDROBE` environment variable.\n\n---\n\n## Why Use Cloakroom?\n1. **Minimal \u0026 Focused**: Designed exclusively for Keycloak plugin management—no extraneous features to distract you.\n2. **Predictable Builds**: Pin plugins to specific tags and artifacts (with optional hashes) for consistent deployments.\n3. **Clean Dockerfiles**: Drop all the manual fetches—let Cloakroom handle the plugin retrieval.\n4. **Easy Setup**: A single environment variable, `CLOAKROOM_WARDROBE`, points to your Keycloak provider directory.\n\n---\n\n## Features\n- **Manifest-Driven**: Centralize plugin definitions in a file like `cloakroom.json` (or TOML/INI/HCL/YAML).\n- **GitHub Releases**: Download JARs using `tag` (e.g., `\"v1.2.0\"`) and an `artifact`.\n- **Optional Hash Verification**: Provide a **SHA3-512** `hash` to verify each download’s integrity.\n- **Flexible Configuration Formats**: Use JSON, TOML, INI, HCL, or YAML—whichever suits your workflow.\n- **Environment-Aware**: Respects `CLOAKROOM_WARDROBE`, so you can easily switch directories across environments.\n\n---\n\n## Installation \u0026 Setup\n\n1. **Download the Binary**  \n   Grab the latest release from the [Cloakroom GitHub Releases](https://github.com/peter-mghendi/cloakroom/releases).\n\n2. **Install**\n   ```bash\n   chmod +x cloakroom\n   mv cloakroom /usr/local/bin/\n   ```\n\n3. **Verify**\n   ```bash\n   cloakroom --help\n   ```\n\n4. **Set `CLOAKROOM_WARDROBE`**\n   ```bash\n   export CLOAKROOM_WARDROBE=\"/opt/keycloak/providers\"\n   ```\n   (On Windows, set it in your System Environment Variables.)\n\n---\n\n## Configuration Overview\n\n### Environment Variables\n- **`CLOAKROOM_WARDROBE`** (required):  \n  The Keycloak provider directory where Cloakroom places the downloaded JARs.\n   - Cloakroom refuses to run if not set.\n\n### Manifest File\nIf the `--manifest` option is specified, cloakroom attempts to load that file, failing if it does not exist or is invalid.\nOtherwise, cloakroom searches the current directory for a `cloakroom.{format}` file, where `{format}` is one of:\n- [HCL](https://developer.hashicorp.com/terraform/language/syntax/configuration)\n- [INI](https://en.wikipedia.org/wiki/INI_file)\n- [JSON](https://json.org)\n- [TOML](https://toml.io)\n- [YAML](https://yaml.org)\n\nWithin your manifest, you typically define:\n- **`version`**: Mnifest version. The only valid value is `\"1.0\"`.\n- **`host`**: A host that is compatible with the GitHub releases format, e.g. `\"github.com\"`, or a URL to a hosted GitHub or Gitea server. \n- **`plugins`** (required): a map of `user/repo` → plugin definition.\n\nEach plugin definition contains:\n- **`tag`** (required): The title of the release e.g. `\"v1.2.0\"`.\n- **`artifact`** (required): the name of the JAR in that release.\n- **`hash`** (optional): A **SHA3-512** hash for integrity checks.\n\n---\n\n## Usage\n\n### Commands\n\n#### `init`\nGenerates a minimal configuration file:\n```\ncloakroom init\n```\n\n#### `add`\nAdds a plugin to your manifest:\n```\ncloakroom add aerogear/keycloak-metrics-spi --tag 7.0.0 --artifact keycloak-metrics-spi-7.0.0.jar\n```\nUse `--fetch` to download the plugin right away.\n\n#### `remove`\nRemoves a plugin from your manifest:\n```\ncloakroom remove aerogear/keycloak-metrics-spi\n```\nUse `--purge` to also delete the local JAR file.\n\n#### `restore`\nInstalls or updates **all** plugins from your manifest:\n```\ncloakroom restore\n```\n- `--clean`: Empties the directory defined by `CLOAKROOM_WARDROBE` before downloading.\n- `--force`: Overwrites existing JAR files if present.\n\n#### `clean`\nCompletely clears the directory specified by `CLOAKROOM_WARDROBE`, without modifying your manifest:\n```\ncloakroom clean\n```\n\n#### `list`\nLists all plugins in the manifest, including `tag`, `artifact`, etc.:\n```\ncloakroom list\n```\n\n### Examples\n\n1. **Initialize**\n   ```\n   cloakroom init\n   # Creates cloakroom.json with minimal defaults\n   ```\n\n2. **Add a Plugin \u0026 Fetch**\n   ```\n   cloakroom add klausbetz/apple-identity-provider-keycloak \\\n       --tag 1.7.1 \\\n       --artifact apple-identity-provider-1.7.1.jar \\\n       --fetch\n   ```\n\n3. **Remove a Plugin \u0026 Purge**\n   ```\n   cloakroom remove klausbetz/apple-identity-provider-keycloak --purge\n   ```\n\n4. **Restore Plugins**\n   ```\n   cloakroom restore --clean\n   # Empties CLOAKROOM_WARDROBE, then downloads everything fresh\n   ```\n\n---\n\n## Configuration Examples\n\n**HCL**\n```hcl\nversion = \"1.0\"\nhost    = \"github.com\"\n\nplugins \"example/my-plugin\" {\n   tag      = \"v1.2.0\"\n   artifact = \"my-plugin-1.2.0.jar\"\n   hash     = \"a69f73cca23a9ac5c8b567dc185a756e97c982164fe25859e0d1dcc1475c80a615b2123af1f5f94c11e3e9402c3ac558f500199d95b6d3e301758586281dcd26\"\n}\n```\n\n**INI**\n```ini\nversion = 1.0\nhost = github.com\n\n[plugins \"example/my-plugin\"]\ntag = v1.2.0\nartifact = my-plugin-1.2.0.jar\nhash = a69f73cca23a9ac5c8b567dc185a756e97c982164fe25859e0d1dcc1475c80a615b2123af1f5f94c11e3e9402c3ac558f500199d95b6d3e301758586281dcd26\n```\n\n**JSON**:\n```json\n{\n  \"version\": \"1.0\",\n  \"host\": \"github.com\",\n  \"plugins\": {\n    \"example/my-plugin\": {\n      \"tag\": \"v1.2.0\",\n      \"artifact\": \"my-plugin-1.2.0.jar\",\n      \"hash\": \"a69f73cca23a9ac5c8b567dc185a756e97c982164fe25859e0d1dcc1475c80a615b2123af1f5f94c11e3e9402c3ac558f500199d95b6d3e301758586281dcd26\"\n    }\n  }\n}\n```\n\n**TOML**:\n```toml\nversion = \"1.0\"\nhost = \"github.com\"\n\n[plugins.\"example/my-plugin\"]\ntag = \"v1.2.0\"\nartifact = \"my-plugin-1.2.0.jar\"\nhash = \"a69f73cca23a9ac5c8b567dc185a756e97c982164fe25859e0d1dcc1475c80a615b2123af1f5f94c11e3e9402c3ac558f500199d95b6d3e301758586281dcd26\"\n```\n\n**YAML**\n```yaml\nversion: \"1.0\"\nhost: \"github.com\"\n\nplugins:\n  \"example/my-plugin\":\n    tag: \"v1.2.0\"\n    artifact: \"my-plugin-1.2.0.jar\"\n    hash: \"a69f73cca23a9ac5c8b567dc185a756e97c982164fe25859e0d1dcc1475c80a615b2123af1f5f94c11e3e9402c3ac558f500199d95b6d3e301758586281dcd26\"\n```\n---\n\n## Handling Multiple Manifests\n\nIf Cloakroom finds more than one matching manifest (e.g. `cloakroom.json` and `cloakroom.toml`) without a specific `--manifest`:\n1. **Fail Immediately**:\n   ```\n   [ERROR] Found multiple manifests:\n   - cloakroom.json\n   - cloakroom.toml\n\n   Cloakroom does not support multiple manifests at once.\n   ```\n2. **Merge** *(planned)*: Cloakroom may eventually merge them, but only if no collisions are detected.\n\n---\n\n## FAQ\n\n**1. Where does Cloakroom store plugins?**  \nIn the directory defined by `CLOAKROOM_WARDROBE`. If it’s missing, Cloakroom exits with an error.\n\n**2. Can I use private GitHub Repos or GitHub Enterprise?**  \nFor now, Cloakroom focuses on public GitHub releases. Other hosts (e.g. Gitea) might work if they follow a similar releases structure.\n\n**3. What happens if the JAR already exists?**  \nBy default, Cloakroom skips it. Use `--force` to overwrite or `--clean` to remove existing files before fetching.\n\n**4. Does Cloakroom handle semver ranges or advanced versioning?**  \nCurrently, you pin a specific tag. Advanced version logic is on the roadmap.\n\n---\n\n## Contributing\nI'd love your contributions—whether that’s opening an issue, suggesting a feature, or sending a pull request. See [CONTRIBUTING.md](#contributing) for details.\n\n---\n\n## License\n[MIT License](LICENSE) © 2025 Peter Mghendi\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeter-mghendi%2Fcloakroom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeter-mghendi%2Fcloakroom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeter-mghendi%2Fcloakroom/lists"}