From 351f58b80d75d67d0e141b8ca50ac3c5eecc3c57 Mon Sep 17 00:00:00 2001 From: Paul Payne Date: Wed, 22 Oct 2025 22:36:53 +0000 Subject: [PATCH] Update docs for adding apps. --- ADDING-APPS.md | 10 +++--- CLAUDE.md | 26 ++++++++++++---- README.md | 83 ++++++++++++++++++++++++++++++++++++++++--------- gitea/README.md | 6 ++-- 4 files changed, 97 insertions(+), 28 deletions(-) diff --git a/ADDING-APPS.md b/ADDING-APPS.md index 5298e5c..cb9ae72 100644 --- a/ADDING-APPS.md +++ b/ADDING-APPS.md @@ -111,7 +111,7 @@ This means individual resources can use simple, component-specific selectors lik ### Gomplate Templating -Resource files in this repository are **templates** that get compiled when operators run `wild-app-add`. Use gomplate syntax to reference configuration: +Resource files in this repository are **templates** that get compiled when users add apps via the web app, CLI, or API. Use gomplate syntax to reference configuration: ```yaml # Common template variables @@ -125,7 +125,7 @@ dbHost: {{ .apps.myapp.dbHostname }} # App-specific config 1. Standard Wild Cloud variables (`{{ .cloud.* }}`, `{{ .operator.* }}`) 2. App-specific variables defined in your manifest's `defaultConfig` -All template variables must be defined in one of these locations. The compiled files are placed in the operator's Wild Cloud home directory as standard Kubernetes manifests. +All template variables must be defined in one of these locations. The compiled files are placed in the instance's directory as standard Kubernetes manifests. ### External DNS @@ -177,7 +177,7 @@ When apps need database URLs with embedded credentials, **always use a dedicated key: apps.myapp.dbUrl ``` -Add `apps.myapp.dbUrl` to your manifest's `requiredSecrets`, and `wild-app-add` will generate the complete URL with embedded credentials automatically. +Add `apps.myapp.dbUrl` to your manifest's `requiredSecrets`, and the system will generate the complete URL with embedded credentials automatically when the app is added. ## Security Requirements @@ -232,8 +232,8 @@ env: **Secret workflow:** 1. List secrets in manifest's `requiredSecrets` -2. `wild-app-add` generates random values in operator's `secrets.yaml` -3. `wild-app-deploy` creates a Kubernetes Secret named `-secrets` +2. When adding an app, the system generates random values in the instance's `secrets.yaml` +3. When deploying, the system creates a Kubernetes Secret named `-secrets` 4. Resources reference secrets using full dotted paths **Important:** Never commit `secrets.yaml` to Git. Templates should only reference secrets, never contain actual secret values. diff --git a/CLAUDE.md b/CLAUDE.md index 004e967..2e7b79f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -23,7 +23,7 @@ Configuration files use **gomplate templating** to reference operator configurat - Use `{{ .operator.email }}` for operator email - All template variables must be defined in either the app's `manifest.yaml` under `defaultConfig` or be standard Wild Cloud operator variables -Templates are compiled by `wild-app-add` when operators add apps to their Wild Cloud home directory. +Templates are compiled when users add apps to their Wild Cloud instance via the web app, CLI, or API. ### Label Strategy @@ -132,13 +132,27 @@ Then: 5. Add standard Wild Cloud labels to `kustomization.yaml` 6. Add security contexts to all pods -## Common Wild Cloud Commands +## Managing Wild Cloud Apps -These commands are run by operators from their Wild Cloud home directory (not this repository): +Users can manage apps through: -- `wild-apps-list` - List all available apps -- `wild-app-add ` - Add an app (compiles templates, updates config/secrets) -- `wild-app-deploy ` - Deploy an app to the cluster +1. **Web App**: Navigate to the Apps page in your instance to browse, add, configure, and deploy apps + +2. **CLI**: Use the Wild CLI for terminal-based workflows: + - `wild app list` - List all available apps + - `wild app add ` - Add an app (compiles templates, updates config/secrets) + - `wild app deploy ` - Deploy an app to the cluster + - `wild app list-deployed` - List deployed apps + - `wild app status ` - Get app status + - `wild app delete ` - Delete an app + +3. **API**: Use the Wild Central API endpoints for automation: + - `GET /api/v1/apps/available` - List all available apps + - `GET /api/v1/apps/available/{app-name}` - Get app details + - `POST /api/v1/instances/{instance-name}/apps` - Add an app (compiles templates, updates config/secrets) + - `POST /api/v1/instances/{instance-name}/apps/{app-name}/deploy` - Deploy an app to the cluster + - `GET /api/v1/instances/{instance-name}/apps` - List deployed apps + - `GET /api/v1/instances/{instance-name}/apps/{app-name}/status` - Get app status ## Validation diff --git a/README.md b/README.md index d329712..55674c8 100644 --- a/README.md +++ b/README.md @@ -14,24 +14,79 @@ Apps use gomplate templates that compile with your Wild Cloud configuration when ## Using Wild Cloud Apps -### Commands +### Web App (Recommended) -Run these commands from your Wild Cloud home directory: +The easiest way to manage apps is through the Wild Cloud web app: -- **`wild-apps-list`** - Browse all available apps in the repository -- **`wild-app-add `** - Add an app to your cluster: - - Copies the app manifest to your `apps` directory - - Adds default configuration to your `config.yaml` - - Generates required secrets in your `secrets.yaml` - - Compiles templates with your configuration -- **`wild-app-deploy `** - Deploy or update the app in your cluster +1. **Navigate to Apps**: Access your instance in the web app and go to the Apps page +2. **Browse Available Apps**: View all available apps from the Wild Directory with descriptions and icons +3. **Add an App**: Click on an app to view details and click "Add" to: + - Copy the app manifest to your instance's `apps` directory + - Add default configuration to your `config.yaml` + - Generate required secrets in your `secrets.yaml` + - Compile templates with your configuration +4. **Configure** (optional): Modify app settings before deployment +5. **Deploy**: Click "Deploy" to apply the app to your cluster +6. **Monitor**: View app status, logs, and manage deployments + +### CLI + +For terminal-based workflows, use the Wild CLI: + +```bash +# List available apps +wild app list + +# Add app to instance +wild app add + +# Deploy app +wild app deploy + +# List deployed apps +wild app list-deployed + +# Get app status +wild app status + +# Delete app +wild app delete +``` + +The CLI connects to the Wild Central API (default: `http://localhost:5055`). You can override with `--daemon-url` or set `WILD_API_URI` environment variable. + +### API + +For automation or advanced workflows, use the Wild Central API: + +```bash +# List available apps +curl http://localhost:5055/api/v1/apps/available + +# Get app details +curl http://localhost:5055/api/v1/apps/available/{app-name} + +# List deployed apps for an instance +curl http://localhost:5055/api/v1/instances/{instance-name}/apps + +# Add app to configuration +curl -X POST http://localhost:5055/api/v1/instances/{instance-name}/apps \ + -H "Content-Type: application/json" \ + -d '{"name": "app-name", "config": {}}' + +# Deploy app +curl -X POST http://localhost:5055/api/v1/instances/{instance-name}/apps/{app-name}/deploy + +# Get app status +curl http://localhost:5055/api/v1/instances/{instance-name}/apps/{app-name}/status +``` ### How It Works -1. **Add an app**: `wild-app-add` compiles the app's templates using your Wild Cloud configuration (domain, email, etc.) and creates standard Kustomize files in your Wild Cloud home directory -2. **Customize** (optional): Modify the compiled files in your home directory, or use Kustomize patches/overlays -3. **Deploy**: `wild-app-deploy` applies the Kustomize configuration to your cluster -4. **Manage**: Track changes with Git, update configurations as needed +1. **Add an app**: The system compiles the app's templates using your Wild Cloud configuration (domain, email, etc.) and creates standard Kustomize files in your instance directory +2. **Customize** (optional): Modify app configuration through the web app, CLI, or by editing files directly +3. **Deploy**: The system applies the Kustomize configuration to your cluster +4. **Manage**: Track changes with Git, update configurations, and monitor app health ### Dependencies @@ -54,7 +109,7 @@ This repository includes apps for: - Databases (PostgreSQL, MySQL, Redis, Memcached) - And more... -Run `wild-apps-list` to see the full catalog with descriptions. +Browse the full catalog with descriptions through the web app, CLI, or via the API endpoint `/api/v1/apps/available`. ## Contributing diff --git a/gitea/README.md b/gitea/README.md index 8e8b947..f42fc75 100644 --- a/gitea/README.md +++ b/gitea/README.md @@ -20,7 +20,7 @@ Sensitive configuration is stored in the `gitea-secrets` secret and managed by t - `dbPassword` - Database password - `smtpPassword` - SMTP authentication password -Secrets are defined in `secrets.yaml` and listed in `manifest.yaml` under `requiredSecrets`. The `wild-app-deploy` command automatically ensures all required secrets exist in the `gitea-secrets` secret before deployment. +Secrets are defined in `secrets.yaml` and listed in `manifest.yaml` under `requiredSecrets`. When deploying, the system automatically ensures all required secrets exist in the `gitea-secrets` secret before deployment. ### Persistent Configuration (app.ini) Gitea manages its own `app.ini` file on persistent storage for: @@ -41,13 +41,13 @@ Gitea manages its own `app.ini` file on persistent storage for: ### Non-Secret Settings 1. Edit `gitea.env` with your changes -2. Run `wild-app-deploy gitea` to apply changes +2. Deploy the app via the web app, CLI, or API to apply changes 3. Pod will restart and pick up new configuration ### Secret Settings 1. Edit `secrets.yaml` with your secret values 2. Ensure the secret key is listed in `manifest.yaml` under `requiredSecrets` -3. Run `wild-app-deploy gitea` - this will automatically update the `gitea-secrets` secret and restart the pod +3. Deploy the app via the web app, CLI, or API - this will automatically update the `gitea-secrets` secret and restart the pod ### Web UI Changes Configuration changes made through Gitea's admin web interface are automatically persisted to the `app.ini` file on persistent storage and will survive pod restarts.