From 963929475c64b305d19d6cf382d3a3d5588fc6cb Mon Sep 17 00:00:00 2001 From: Paul Payne Date: Sun, 4 Jan 2026 19:36:54 +0000 Subject: [PATCH] Update CLAUDE.md. --- CLAUDE.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 88 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index e2bd7c9..1bbafc4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,15 +1,97 @@ - @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 ` + - `wild app deploy ` + - `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. -- Don't use helm -- 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 -- when developing a new app: - - test with: - - reset to a fresh state between tests: -- secrets.yaml is not checked in and any values unrelated to your current task should be preserved +