wild-directory/CLAUDE.md

• @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
• 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.