wild-directory/CLAUDE.md at 763ac922d5341dea89addb9065ed83ba5c46930d

Files

Paul Payne 4d983819c9 feat(supabase): add services and statefulset for database management

feat(synapse): update ingress to use traefik ingress class and bump version

feat(syncthing-discovery): introduce syncthing discovery service with deployment and ingress

feat(syncthing-relay): add syncthing relay server with deployment and ingress configuration

fix(taiga): update liveness and readiness probes to use tcpSocket for health checks

fix(taiga): change PVC access mode to ReadWriteMany for media and static storage

feat(traefik): add icon and ignore rules for traefik service

docs(ushahidi): add notes for Redis configuration and Laravel startup probe adjustments

feat(ushahidi): implement dedicated Redis deployment for Ushahidi

fix(vllm): update deployment strategy and readiness/liveness probes for improved stability

fix(writefreely): pin writefreely image version to v0.15.1 for consistency

docs(zulip): add notes for TLS-terminating reverse proxy configuration and expected behavior

2026-07-02 21:34:27 +00:00

4.8 KiB

Raw Blame History

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

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

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

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

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:

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

Icon Preferences

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

Search Strategy

For each app:

Try Dashboard Icons first: dashboardicons.com/icons/{app}
If not found, try Vector Logo Zone: vectorlogo.zone/logos/{app}
If still not found, search: "{app} official logo CDN SVG URL"
Validate the URL actually works
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.