stack.basicstack.de/apps/README.md

# Applications

This directory contains deployment configurations for all applications running on the basicstack.de cluster.

## ArgoCD Application Management

Each application has two types of files:

1. **`app-<name>.yaml`**: ArgoCD Application manifest that tells ArgoCD to sync the app subdirectory
2. **`<name>/`**: Application-specific Kubernetes manifests and configuration

The `app-*.yaml` files are synced by ArgoCD and create/manage the corresponding Application resources.
Each application's manifests in its subdirectory are then synced by its Application resource.

## Structure

Each application should have its own subdirectory containing:

- **Kubernetes manifests**: Deployment, StatefulSet, Service, ConfigMap, Secret definitions
- **Helm values**: If using Helm charts, include values.yaml files
- **Configuration files**: Application-specific configs (TOML, JSON, YAML)
- **Documentation**: README or guide specific to the application deployment
- **Patches**: Any kubectl patches or modifications needed

## Example: Stalwart

The `stalwart/` directory serves as a reference implementation, containing:
- Multiple deployment variants (basic, with OIDC, etc.)
- Helm values files
- Monitoring dashboard configurations
- Backup/restore procedures
- Operational documentation

## Adding a New Application

1. Create a new directory: `apps/<application-name>/`
2. Add your Kubernetes manifests
3. Include a README.md explaining:
   - What the application does
   - How to deploy it
   - Configuration options
   - Troubleshooting steps
4. Test the deployment in a dev environment
5. Commit with a descriptive message

## Naming Conventions

- Directory names: lowercase, hyphen-separated (e.g., `my-app`)
- Manifest files: descriptive names indicating resource type (e.g., `deployment.yaml`, `service.yaml`)
- Use consistent naming across applications