{"id":16283056,"url":"https://github.com/kadel/rhdh-local","last_synced_at":"2025-03-20T02:30:39.186Z","repository":{"id":256184735,"uuid":"852852858","full_name":"redhat-developer/rhdh-local","owner":"redhat-developer","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-14T12:14:51.000Z","size":327,"stargazers_count":15,"open_issues_count":1,"forks_count":21,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-03-14T12:32:28.994Z","etag":null,"topics":["redhat-developer-hub","rhdh"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"benwilcock/backstage-local","license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/redhat-developer.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":"2024-09-05T14:40:19.000Z","updated_at":"2025-03-14T12:14:55.000Z","dependencies_parsed_at":"2024-12-09T16:21:23.689Z","dependency_job_id":"174e98d3-225e-4428-9858-9b4d2e5a3a49","html_url":"https://github.com/redhat-developer/rhdh-local","commit_stats":null,"previous_names":["kadel/backstage-local","kadel/rhdh-local","redhat-developer/rhdh-local"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-developer%2Frhdh-local","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-developer%2Frhdh-local/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-developer%2Frhdh-local/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/redhat-developer%2Frhdh-local/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/redhat-developer","download_url":"https://codeload.github.com/redhat-developer/rhdh-local/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244538531,"owners_count":20468730,"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":["redhat-developer-hub","rhdh"],"created_at":"2024-10-10T19:12:26.872Z","updated_at":"2025-03-20T02:30:39.180Z","avatar_url":"https://github.com/redhat-developer.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Test Locally With Red Hat Developer Hub (RHDH)\n\nWelcome to RHDH Local - the fastest and simplest way for platform engineers to test their software catalogs, techdocs, plugins, templates, homepage customizations, configurations and more with RHDH!\n\nRHDH Local is ideal for trying out the basic features of RHDH (like Software Catalogs or TechDocs) without the need for a Kubernetes cluster. RHDH Local is also great for testing dynamic plugins and their configuration settings. To use RHDH Local, all you really need is basic knowledge of Docker or Podman, a PC, and a web browser. You can run it on your laptop, desktop, or on your homelab. Better still, when you're done working it's easy to remove.\n\n\u003e**RHDH Local is NOT a substitute for Red Hat Developer Hub**. Do not attempt to use RHDH Local as a production system. RHDH Local is designed to help individual developers test various RHDH features. It's not designed to scale and it's not suitable for use by teams (there is no RBAC for example). There's also (currently) no official support for RHDH Local. You use RHDH Local at your own risk. With all that being said, we think it's incredibly useful and any contributions you might have that could improve RHDH Local are welcome!\n\n## What You'll Need Before You Get Started\n\nTo use RHDH Local you'll need a few things:\n\n1. A PC based on an x86 64Bit (amd64) architecture (ARM is on the way)\n1. An installation of Docker or Podman (with adequate resources available)\n1. An internet connection (for downloading container images, plugins, etc.)\n1. (Optional) The `git` command line client for cloning this repository (or you can download and extract the Zip from GitHub)\n1. (Optional) A GitHub account (if you want to integrate GitHub features into RHDH)\n1. (Optional) The node `npx` tool (if you intend to use GitHub authentication in RHDH)\n1. (Optional) A [Red Hat account](https://access.redhat.com/RegistryAuthentication#getting-a-red-hat-login-2) (if you want to use a PostgreSQL database)\n\n## Getting Started With RHDH Local\n\n1. Clone this repository to a location on your PC\n\n   ```sh\n   git clone https://github.com/redhat-developer/rhdh-local.git\n   ```\n\n1. Move to the `rhdh-local` folder.\n\n   ```sh\n   cd rhdh-local\n   ```\n\n1. Create your own local `.env` file by using a copy of the `env.sample` provided.\n\n   ```sh\n   cp env.sample .env\n   ```\n\n   In most cases, when you don't need GitHub Auth or testing different releases you can leave it as it is, and it should work.\n\n1. (Optional) Update `configs/app-config.local.yaml`.\n   If you need features that fetch files from GitHub you should configure `integrations.github`.\n   The recommended way is to use GitHub Apps. You can find hints on how to configure it in [github-app-credentials.example.yaml](configs/github-app-credentials.example.yaml) or a more detailed instruction in [Backstage documentation](https://backstage.io/docs/integrations/github/github-apps).\n\n1. Start RHDH Local.\n   This repository should work with either `docker compose` using Docker Engine or `podman-compose` using Podman. When using Podman there are some exceptions. Check [Known Issues when using Podman Compose](#known-issues-when-using-podman-compose) for more info.\n\n   ```sh\n   podman-compose up -d\n   ```\n\n   If you prefer `docker compose` you can just replace `podman-compose` with `docker compose`\n\n   ```sh\n   docker compose up -d\n   ```\n\n## Changing Your Configuration\n\nWhen you change `app-config.local.yaml` you must restart the `rhdh` container to load RHDH your updated configuration.\n\n```sh\npodman-compose stop rhdh \u0026\u0026 podman-compose start rhdh\n```\n\nWhen you change `dynamic-plugins.yaml` you need to re-run the `install-dynamic-plugins` container and then restart RHDH instance.\n\n```sh\npodman-compose run install-dynamic-plugins\npodman-compose stop rhdh \u0026\u0026 podman-compose start rhdh\n```\n\n## Loading dynamic plugins from a local directory\n\nDuring boot the `install-dynamic-plugins` container reads the contents of the `configs/dynamic-plugins.yaml` file and activates, configures, or downloads any plugins contained in that file. In addition, the `local-plugins` directory is mounted into the `install-dynamic-plugins` container on the path `/opt/app-root/src/local-plugins`. Any plugins in that location can also be activated and configured in the same way (without downloading).\n\nYou can use the `local-plugins` folder install dynamic plugins directly from your local machine using the following steps:\n\n1. Copy the dynamic plugin binary file into the `local-plugins` directory.\n2. Make sure that the permissions are set to allow container to read files (quick and dirty solution is `chmod -R 777 local-plugins`)\n3. Configure your dynamic plugin in `dynamic-plugins.yaml`. See commented out examples in that file for examples.\n4. See [Changing Your Configuration](#changing-your-configuration) section for more information about how to change and load new configuration.\n\n## Changing The Container Image\n\nYou can switch between RHDH and Janus-IDP by changing the container image name hold by the `RHDH_IMAGE` environment variable in your `.env` file.\n\nTo use nightly build of Janus-IDP, set the variable as follows:\n\n```sh\nRHDH_IMAGE=quay.io/janus-idp/backstage-showcase:next\n```\n\nTo use the official release of RHDH 1.4, set the variable as follows:\n\n```sh\nRHDH_IMAGE=quay.io/rhdh/rhdh-hub-rhel9:1.4\n```\n\n## Testing RHDH in a simulated corporate proxy setup\n\nIf you want to test how RHDH would behave if deployed in a corporate proxy environment,\nyou can run `podman-compose` or `docker-compose` by merging both the [`compose.yaml`](./compose.yaml) and [`compose-with-corporate-proxy.yaml`](./compose-with-corporate-proxy.yaml) files.\n\nExample with `podman-compose` (note that the order of the YAML files is important):\n\n```sh\npodman-compose \\\n   -f compose.yaml \\\n   -f compose-with-corporate-proxy.yaml \\\n   up -d\n```\n\nThe [`compose-with-corporate-proxy.yaml`](compose-with-corporate-proxy.yaml) file includes a specific [Squid](https://www.squid-cache.org/)-based proxy container as well as an isolated network, such that:\n\n1. only the proxy container has access to the outside\n2. all containers part of the internal network need to communicate through the proxy container to reach the outside. This can be done with the `HTTP(S)_PROXY` and `NO_PROXY` environment variables.\n\n## Cleanup\n\nTo reset RHDH Local you can use the following command. This will clean up any container attached volumes, but configuration changes made to your `rhdh-local` YAML files will remain.\n\n```sh\npodman-compose down --volumes\n```\n\nTo reset everything in the cloned `rhdh-local` repository, including any configuration changes you've made to your YAML files try:\n\n```sh\ngit reset --hard\n```\n\nTo remove the RHDH containers completely from your system (after you have run a `compose down`):\n\n```sh\ndocker system prune --volumes # For rhdh-local running on docker\npodman system prune --volumes # For rhdh-local running on podman\n```\n\n### Known Issues when using Podman Compose\n\nWorks with `podman-compose` only with image that include this following fix https://github.com/janus-idp/backstage-showcase/pull/1585\n\nOlder images don't work in combination with `podman-compose`.\nThis is due to https://issues.redhat.com/browse/RHIDP-3939. RHDH images currently populate dynamic-plugins-root directory with all plugins that are packaged inside the image.\nBefore podman mounts volume over `dynamic-plugins-root` directory it copies all existing files into the volume. When the plugins are installed using `install-dynamic-plugins.sh` script it create duplicate installations of some plugins, this situation than prevents Backstage to start.\n\nThis also doesn't work with `podman compose` when using `docker-compose` as external compose provider on macOS.\n\nIt fails with\n\n```\ninstall-dynamic-plugins-1  | Traceback (most recent call last):\ninstall-dynamic-plugins-1  |   File \"/opt/app-root/src/install-dynamic-plugins.py\", line 429, in \u003cmodule\u003e\ninstall-dynamic-plugins-1  |     main()\ninstall-dynamic-plugins-1  |   File \"/opt/app-root/src/install-dynamic-plugins.py\", line 206, in main\ninstall-dynamic-plugins-1  |     with open(dynamicPluginsFile, 'r') as file:\ninstall-dynamic-plugins-1  | PermissionError: [Errno 13] Permission denied: 'dynamic-plugins.yaml'\n```\n\nIt looks like `docker-compose` when used with podman doesn't correctly propagate `Z` SElinux label.\n\n## Using PostgreSQL database\n\nBy default, in-memory db is used.\nIf you want to use PostgreSQL with RHDH, here are the steps:\n\n\u003e **NOTE**: You must have [Red Hat Login](https://access.redhat.com/RegistryAuthentication#getting-a-red-hat-login-2) to use `postgresql` image.\n\n1. Login to container registry with *Red Hat Login* credentials to use `postgresql` image\n\n   ```sh\n   podman login registry.redhat.io\n   ```\n\n   If you prefer `docker` you can just replace `podman` with `docker`\n\n   ```sh\n   docker login registry.redhat.io\n   ```\n\n2. Uncomment the `db` service block in [compose.yaml](compose.yaml) file\n\n   ```yaml\n   db:\n     image: \"registry.redhat.io/rhel8/postgresql-16:latest\"\n     volumes:\n       - \"/var/lib/pgsql/data\"\n     env_file:\n       - path: \"./.env\"\n         required: true\n     environment:\n       - POSTGRESQL_ADMIN_PASSWORD=${POSTGRES_PASSWORD}\n     healthcheck:\n       test: [\"CMD\", \"pg_isready\", \"-U\", \"postgres\"]\n       interval: 5s\n       timeout: 5s\n       retries: 5\n   ```\n\n3. Uncomment the `db` section in the `depends_on` section of `rhdh` service in [compose.yaml](compose.yaml)\n\n   ```yaml\n   depends_on:\n     install-dynamic-plugins:\n       condition: service_completed_successfully\n     db:\n       condition: service_healthy\n   ```\n\n4. Comment out the SQLite in-memory configuration in [`app-config.local.yaml`](configs/app-config.local.yaml)\n\n   ```yaml\n   # database:\n   #   client: better-sqlite3\n   #   connection: ':memory:'\n   ```\n\n## Developers: Using VSCode to debug backend plugins\n\nYou can use RHDH-local with a debugger to to debug your backend plugins in VSCode. Here is how:\n\n1. Start RHDH-local with the \"debug\" compose file\n\n   ```sh\n   # in rhdh-local directory\n   podman-compose up -f compose.yaml -f compose-debug.yaml\n   ```\n\n2. Open your plugin source code in VSCode\n3. Export plugin an RHDH \"dynamic\" plugin\n\n   ```sh\n   # in plugin source code directory\n   npx @janus-idp/cli@latest package export-dynamic-plugin\n   ```\n\n4. Copy exported derived plugin package to `dynamic-plugins-root` directory in the `rhdh` container.\n\n   ```sh\n   # in plugin source code directory\n   podman cp dist-dynamic rhdh:/opt/app-root/src/dynamic-plugins-root/\u003cyour-plugin-name\u003e\n   ```\n\n5. If your plugin requires configuration, add it to the `app-config.local.yaml` file in your cloned `rhdh-local` directory.\n\n6. Restart the `rhdh` container\n\n   ```sh\n   # in rhdh-local directory\n   podman-compose stop rhdh\n   podman-compose start rhdh\n   ```\n\n7. Configure VSCode debugger to attach to the `rhdh` container.\n\n   `.vscode/launch.json` example:\n\n   ```json\n   {\n      \"version\": \"0.2.0\",\n      \"configurations\": [\n         {\n            \"name\": \"Attach to Process\",\n            \"type\": \"node\",\n            \"request\": \"attach\",\n            \"port\": 9229,\n            \"localRoot\": \"${workspaceFolder}\",\n            \"remoteRoot\": \"/opt/app-root/src/dynamic-plugins-root/\u003cyour-plugin-name\u003e\",\n         }\n      ]\n   }\n   ```\n\n8. Now, you can start debugging your plugin using VSCode debugger.\n   Source mapping should work, and you should be able to put breakpoints to your TypeScript files.\n   If it doesn't work, most likely you need to adjust `localRoot` and `remoteRoot` paths in `launch.json`.\n\n   Every time you make changes to your plugin source code, you need to repeat steps 3-6.\n\n## Contributing and reporting issues\n\nTo report issues against this repository, please use [JIRA](https://issues.redhat.com/browse/RHIDP) with Component: **RHDH Local**\n\nTo browse the existing issues, you can use this [Query](https://issues.redhat.com/issues/?filter=-4\u0026jql=project%20%3D%20%22Red%20Hat%20Internal%20Developer%20Platform%22%20%20AND%20component%20%3D%20%22RHDH%20Local%22%20AND%20resolution%20%3D%20Unresolved%20ORDER%20BY%20status%2C%20priority%2C%20updated%20%20%20%20DESC).\n\nContributions are welcome!\n\n## License\n\n```txt\nCopyright Red Hat\n\nLicensed under the Apache License, Version 2.0 (the \"License\");\nyou may not use this file except in compliance with the License.\nYou may obtain a copy of the License at\n\n   http://www.apache.org/licenses/LICENSE-2.0\n\nUnless required by applicable law or agreed to in writing, software\ndistributed under the License is distributed on an \"AS IS\" BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\nSee the License for the specific language governing permissions and\nlimitations under the License.\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkadel%2Frhdh-local","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkadel%2Frhdh-local","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkadel%2Frhdh-local/lists"}