# Wild Cloud Apps Directory

This is the official Wild Cloud apps repository containing a curated collection of self-hosted applications that can be deployed to your Wild Cloud cluster.

## What are Wild Cloud Apps?

Wild Cloud apps are pre-packaged Kubernetes applications using Kustomize that follow standardized conventions for configuration, secrets management, and deployment. Each app includes:

- **App manifest** (`manifest.yaml`) - Metadata, dependencies, and default configuration
- **Kustomization** (`kustomization.yaml`) - Kubernetes resource definitions
- **Configuration templates** - Deployments, services, ingresses, and other resources

Apps use gomplate templates that compile with your Wild Cloud configuration when added, making them easy to customize while maintaining a consistent deployment experience.

## Using Wild Cloud Apps

### Web App (Recommended)

The easiest way to manage apps is through the Wild Cloud web app:

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 <app-name>

# Deploy app
wild app deploy <app-name>

# List deployed apps
wild app list-deployed

# Get app status
wild app status <app-name>

# Delete app
wild app delete <app-name>
```

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**: 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

Some apps require other apps to function. For example:
- **Immich** requires PostgreSQL and Redis
- **OpenProject** requires PostgreSQL and Memcached
- **Gitea** requires PostgreSQL

When you add an app, check its `requires` field in the manifest and ensure dependencies are added first.

## Available Apps

This repository includes apps for:
- Content management (Ghost, Discourse)
- Project management (OpenProject)
- Photo management (Immich)
- Code hosting (Gitea)
- Email marketing (Listmonk, Keila)
- AI interfaces (Open WebUI, vLLM)
- Databases (PostgreSQL, MySQL, Redis, Memcached)
- And more...

Browse the full catalog with descriptions through the web app, CLI, or via the API endpoint `/api/v1/apps/available`.

## Contributing

Want to add a new app or improve an existing one? See [ADDING-APPS.md](ADDING-APPS.md) for detailed guidance on creating Wild Cloud apps.

Contributions are welcome via pull requests. Ensure your app follows the Wild Cloud conventions and includes all required files.

## Notice: Third-Party Software

The Kubernetes manifests and Kustomize files in this directory are designed to deploy **third-party software**.

Unless otherwise stated, the software deployed by these manifests **is not authored or maintained** by this project. All copyrights, licenses, and responsibilities for that software remain with the respective upstream authors.

These files are provided solely for convenience and automation. Users are responsible for reviewing and complying with the licenses of the software they deploy.

This project is licensed under the GNU AGPLv3 or later, but this license does **not apply** to the third-party software being deployed.

See individual deployment directories for upstream project links and container sources.