From 869053afe64314c673bea80c2ea011942ed28ca6 Mon Sep 17 00:00:00 2001 From: Paul Payne Date: Sat, 1 Aug 2026 20:47:11 +0000 Subject: [PATCH] Agentfile update. --- AGENTS.md | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 100 +---------------------------------------------------- 2 files changed, 102 insertions(+), 99 deletions(-) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..e199447 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,101 @@ +# Wild Directory + +- @README.md + +- ADDING-APPS.md is the expert advice you need when adding new apps to the Wild Cloud Directory. +- docs/ contains deep-dive guides — runtime-specific (nodejs, python, php, ruby, jvm, nginx, linuxserver) and topic-specific (database, redis, traefik, scripts). + +## 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. + diff --git a/CLAUDE.md b/CLAUDE.md index b8f1852..8d770e2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,99 +1 @@ -- @README.md - -- ADDING-APPS.md is the expert advice you need when adding new apps to the Wild Cloud Directory. -- docs/ contains deep-dive guides — runtime-specific (nodejs, python, php, ruby, jvm, nginx, linuxserver) and topic-specific (database, redis, traefik, scripts). - -## 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. - +Read @AGENTS.md