- @README.md
- @ADDING-APPS.md

## Finding good sources of documentation for adding a new app to the Wild Cloud Directory

- A good starting point is to:
  - look for an app's official documentation on running in Kubernetes or a containerized environment
  - look at the app's official docker compose
  - look for official or common helm packages
  - look at the source code repository for the app

These sources will oftentimes not use the latest version. Check to make sure you are adding the latest app version.

- Don't use helm for the final deployement, however it is a good idea to unpack a helm package to investigate best practices and to overcome tricky configurations

## App package development lifecycle

- when developing a new app, test on the `test-cloud` instance in the `/home/payne/repos/wild-cloud-dev/wild-cloud-redmond-data` wild data dir. Prefer the `wild` CLI for managing app lifecycle as it takes care of copying and compiling kustomize templates. Example commands:
    - `wild instance use test-cloud`
    - `wild app add <app>`
    - `wild app deploy <app>`
    - `wild app delete`
- But you can always use `kubectl` directly. Just make sure you use the `test-cloud` `kubeconfig` and, when applying resources, use the `-k` flag so kustomize templates get copied.
    - kubectl --kubeconfig=/home/payne/repos/wild-cloud-redmond-data/instances/test-cloud/kubeconfig get pods -n <app>
- While we test in `/home/payne/repos/wild-cloud-dev/wild-cloud-redmond-data/instances/test-cloud`, the final product (our app package) must be in `/home/payne/repos/wild-cloud-dev/wild-directory`. Always make sure that, in the end, whatever is in `wild-directory` can be deployed into `test-cloud`.
- If you run into difficulties, revisit helm charts, docker compose files, and most importantly, the source code to determine how existing deployments are functioning correctly.

## App Icons

Icon Search Process

  1. Primary Source: Dashboard Icons (homarr-labs)

  - URL Pattern: https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/{app-name}.svg
  - Why: Curated collection specifically for self-hosted apps, consistent style, reliable CDN
  - Format: SVG (preferred for scalability)
  - Check: Visit https://dashboardicons.com/icons/{app-name} to see if it exists

  2. Fallback: Vector Logo Zone

  - URL Pattern: https://www.vectorlogo.zone/logos/{app-name}/
  - Why: Large collection of official logos in standardized formats
  - Options:
    - {app-name}-icon.svg (logo only, no text)
    - {app-name}-ar21.svg (logo with text)
  - Best for: Apps not in Dashboard Icons

  3. Official Sources

  - Check the app's official website for logo/brand pages
  - Look for /brand, /logos, /assets paths
  - Example: https://www.loomio.com/brand/logo_gold.svg

  4. Community CDNs

  - LobeHub Icons: For AI/LLM tools (vLLM, etc.)
    - https://unpkg.com/@lobehub/icons-static-png@latest/dark/{app-name}.png
  - Simple Icons: For popular brands
    - https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/{app-name}.svg

  Validation Process

  For each candidate URL:
  1. Test the URL using WebFetch to confirm it returns a valid image
  2. Verify format: SVG preferred, PNG acceptable
  3. Check content: Logo-only preferred over logo+text
  4. Confirm it works: Actually loads in a browser/img tag

  Icon Preferences

  1. Format: SVG > PNG (for scalability)
  2. Style: Logo only > Logo with text
  3. Source: Official CDN > Community CDN > Direct hosting
  4. Consistency: Similar visual style across all apps

  Search Strategy

  ### For each app:
  1. Try Dashboard Icons first: dashboardicons.com/icons/{app}
  2. If not found, try Vector Logo Zone: vectorlogo.zone/logos/{app}
  3. If still not found, search: "{app} official logo CDN SVG URL"
  4. Validate the URL actually works
  5. Prefer icon-only versions when multiple options exist

  This systematic approach ensures consistent, reliable, and high-quality icons across all Wild Cloud apps.

## IMPORTANT

- NEVER under any circumstances work on any Wild Cloud instance other than `test-cloud`
- `secrets.yaml` is NOT checked in and any values unrelated to your current task should be preserved
- When adding a new app to the directory, check to make sure you are adding the latest app version.
- set `namespace` in default config and refer to it using `{{ .namespace }}` in the `namespace.yaml` definition file and the `kustomization.yaml` file.
- If the app requires a specific platform (amd64, arm64, etc.), make sure it is called out in the manifest and the k8s tags are set
- Use traefik for ingress.
- Use postgres for database if supported.
- Keep config key naming (including nesting) consistent with other apps.