# Red Hat Catalog

LLMS index: [llms.txt](/llms.txt) | Full content: [llms-full.txt](/llms-full.txt)

---

Web UI for browsing Hummingbird container images, security advisories,
and API documentation.

## Features

- **Image Catalog** - Browse container images with tags, architectures, and specifications
- **Security Feed** - Security advisory feed with CVE details
- **API Documentation** - Interactive API documentation browser
- **Image Details** - SBOM, provenance, and release history per image

## Architecture

React 18 + [PatternFly v6][pf] SPA. Data fetching via [TanStack
Query][tsq] against the [container-catalog](container-catalog.md) API
(proxied through webpack-dev-server in development, direct in
production). Webpack 5 build. Hosted on CloudFront + S3 (production)
with MR previews on GitLab Pages.

[pf]: https://www.patternfly.org/
[tsq]: https://tanstack.com/query/latest

## Prerequisites

- Node.js 22+ (for host targets)
- `make` + `podman` (for container targets)

## Usage

Only `make` and `podman` are required for container targets. Host
variants (`*-host`) run without podman.

| Target                      | Description                           |
| --------------------------- | ------------------------------------- |
| `redhat-catalog/setup`      | Install dependencies (container)      |
| `redhat-catalog/check`      | Type-check, lint, and test (container)|
| `redhat-catalog/build`      | Production build (container)          |
| `redhat-catalog/dev`        | Dev server on port 9000 (container)   |
| `redhat-catalog/setup-host` | Install dependencies (host)           |
| `redhat-catalog/check-host` | Type-check, lint, and test (host)     |
| `redhat-catalog/build-host` | Production build (host)               |
| `redhat-catalog/dev-host`   | Dev server (host)                     |

Set `ASSET_PATH` to control the base path for non-root deployments
(used by webpack `output.publicPath` and React Router `basename`).

## Configuration

### Build Variables

| Variable     | Description                                        |
| ------------ | -------------------------------------------------- |
| `ASSET_PATH` | Webpack public path / React Router basename        |

API base URLs are configured in
[`app-config.ts`][app-config].

[app-config]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/redhat-catalog/src/app/app-config.ts

### SAM Parameters

| Parameter           | Description                                                  |
| ------------------- | ------------------------------------------------------------ |
| `ResourcePrefix`    | Prefix for all resource names                                |
| `CatalogDomainName` | Custom domain (optional, leave empty for CloudFront default) |

## Deployment

Production deployment uses a CloudFront + S3 stack defined in
[`template.yaml`][template]. The infrastructure post-deploy script builds
the SPA in a Node.js container, syncs it to S3, and creates a CloudFront
cache invalidation. Custom domain support is optional via the
`CatalogDomainName` SAM parameter. When set, an ACM certificate is
created in-template with DNS validation -- the validation CNAME must
already exist in the external DNS zone before deployment.

[template]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/redhat-catalog/template.yaml

MR previews are deployed to GitLab Pages with `path_prefix` per MR,
auto-cleaned on merge/close with a 1-week expiry.

## Environments and CI promotion

Experimental, staging, and production URLs, MR vs `main` pipelines, deploy
triggers, and UAT sign-off are documented in
[Red Hat Catalog Environment Promotion](redhat-catalog-environments.md)
(monorepo `documentation/`) and
[Red Hat Catalog UAT Program](redhat-catalog-uat.md).

## Development

Detailed contributor documentation lives in-tree:

- [Developer Guide][dev-guide] -- component patterns, state management, data fetching
- [Testing Guide][test-guide] -- Vitest + RTL patterns and commands
- [UAT Checklist][uat] -- human acceptance testing before prod promotion (HUM-2179)
- [Architecture][arch] -- system design, data flow, React Query patterns
- [API Responses][api-resp] -- observed API response shapes
- [Settings Architecture][settings] -- settings/theme system

[dev-guide]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/redhat-catalog/docs/developer-guide.md
[test-guide]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/redhat-catalog/docs/testing-guide.md
[uat]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/redhat-catalog/docs/uat-checklist.md
[arch]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/redhat-catalog/docs/architecture.md
[api-resp]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/redhat-catalog/docs/api-actual-responses.md
[settings]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/redhat-catalog/docs/global-settings-architecture.md

## License

This project is licensed under the GNU General Public License v3.0 or later -
see the [LICENSE][license] file for details.

[license]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/LICENSE