Adding READMEs and Icons to Apps in Happa
Your beautiful app deserves to look beautiful in Happa as well. Here are some tips and tricks on how to set the Chart.yaml values of your app so that the frontend can show relevant information in a pleasing way.
It’s in the Chart.yaml
The metadata that Happa eventually sees starts in the Chart.yaml in the app’s repository.
Here is an example from
# Chart.yaml apiVersion: v2 appVersion: 1.17.1 version: [[ .Version ]] name: jaeger-operator description: | Jaeger operator is a implementation of the operator pattern for installing and managing Jaeger deployments. home: https://github.com/giantswarm/jaeger-operator-app icon: https://s.giantswarm.io/app-icons/1/png/jaeger-operator-app-dark.png kubeVersion: ^1.15.0-0 sources: - https://github.com/jaegertracing/jaeger-operator annotations: application.giantswarm.io/readme: https://raw.githubusercontent.com/giantswarm/jaeger-operator-app/v[[ .Version ]]/README.md application.giantswarm.io/team: team-cabbage ui.giantswarm.io/logo: https://s.giantswarm.io/app-icons/jaeger-operator/1/dark.svg
Icon and logo
Happa is designed to work with 2 types of image assets for apps:
Every app should have an icon, and it must fit a square space.
A good example:
A bad example:
While the icon in the second example also technically fits into a square space, it is not designed for it, as evidenced by the unused vertical space. The resulting icon is also difficult to discern when displayed in a space-constrained area.
Icons can be made available to happa by adding a URL to a PNG or SVG file in the Chart.yaml’s
An app may also have a logo for the catalog, to optimize its display in a rectangular space. Logos should only be provided if they have a different shape than the app’s icon. The ideal width:height ratio of logos is 2:1.
Logos can be made available to happa using the
Providing app icons for light and dark backgrounds
Since our app catalog UI in happa (our web UI) shows app icons on a dark background, there is a chance that an icon/logo would end up invisible because it uses black on a dark blue background. To avoid this, you can provide two versions of the icon file and name the files following a specific pattern.
- Light background version: https://s.giantswarm.io/app-icons/rbac-bootstrap/1/light.svg
- Dark background version: https://s.giantswarm.io/app-icons/rbac-bootstrap/1/dark.svg
Here is how that works.
- Make two versions of the app icon. One that works on a light background, one that works on a dark background.
- Store the one that works on light background with a file name ending in
- Store the one that works on dark background with a file name ending in
- In the app metadata, reference the URL ending in
Note: Please use either the SVG or PNG file format. Make sure to use lowercase file names. Make sure both file names only differ in the end at
(light|dark).(svg|png) and the files reside in the same folder.
Happa will attempt to fetch the url in the value of annotation
and display it when users visit the detail page of that app.
Apps packaged using CircleCI job
automatically include an annotation with key
which points to a versioned copy of the apps README residing in the app catalog.
You can find more information about app metadata in spec Representation of apps and their metadata for app catalog entries.
In case you’re not using
app-build-suite, it is possible to manually add
an annotation called
To make sure users see a README that matches the version of the app they
are currently looking at, you can
[ .Version ] to template it in.
annotations: application.giantswarm.io/readme: https://raw.githubusercontent.com/giantswarm/jaeger-operator-app/v[[ .Version ]]/README.md
Adding a README really ties the whole thing together for people that are trying to use the app. Use it to help people understand what the app will actually do, and what values to supply in order to get a working deployment.
Sample readme outline:
- Sample values files for the web interface and API
- Sample App CR and ConfigMap for the management cluster
- Configuration Options Reference (link to more information)
- For developers