18bdb78429
Created detailed documentation covering: - Authentication and SSO login flow - Adding new applications (Git and UI methods) - Repository credential rotation procedure - Emergency recovery procedures (with critical safety warnings) - Self-management architecture - Monitoring, maintenance, and troubleshooting - Backup and disaster recovery Updated README.md with Argo CD section and links to docs. Updated docs/README.md to index the new Argo CD documentation. Co-Authored-By: Paperclip <noreply@paperclip.ing>
78 lines
No EOL
3.1 KiB
Markdown
78 lines
No EOL
3.1 KiB
Markdown
# stack.basicstack.de
|
|
|
|
CD/CI deployment manifests and configurations for the basicstack.de Kubernetes cluster.
|
|
|
|
## Repository Structure
|
|
|
|
```
|
|
stack.basicstack.de/
|
|
├── apps/ # Application deployments
|
|
│ ├── stalwart/ # Stalwart mail server (example)
|
|
│ └── forgejo/ # Forgejo Git service (placeholder)
|
|
├── infrastructure/ # Infrastructure-level configurations
|
|
│ ├── networking/ # Network policies, ingress, DNS
|
|
│ └── monitoring/ # Monitoring, logging, observability
|
|
└── docs/ # Documentation and guides
|
|
```
|
|
|
|
## Purpose
|
|
|
|
This repository serves as the central source of truth for all deployment configurations targeting the `basicstack.de` Kubernetes cluster. It follows GitOps principles where infrastructure and application state is declaratively defined and version-controlled.
|
|
|
|
## Directory Details
|
|
|
|
### `apps/`
|
|
Contains deployment configurations for individual applications and services running on the cluster. Each application should have its own subdirectory with:
|
|
- Kubernetes manifests (Deployments, StatefulSets, Services, etc.)
|
|
- Helm values files
|
|
- Configuration files
|
|
- Application-specific documentation
|
|
|
|
**Example:** The `stalwart/` directory contains the complete deployment configuration for the Stalwart mail server, including multiple deployment variants, monitoring setup, and operational guides.
|
|
|
|
### `infrastructure/`
|
|
Contains cluster-wide infrastructure configurations:
|
|
- **networking/**: Ingress controllers, network policies, DNS configurations, load balancers
|
|
- **monitoring/**: Prometheus, Grafana, logging infrastructure, observability tools
|
|
|
|
### `docs/`
|
|
General documentation including:
|
|
- Deployment procedures
|
|
- Cluster architecture
|
|
- Troubleshooting guides
|
|
- Best practices
|
|
|
|
## GitOps with Argo CD
|
|
|
|
This repository is managed via **Argo CD**, the GitOps deployment platform for the cluster.
|
|
|
|
- **Argo CD UI**: https://argo.basicstack.de
|
|
- **Authentication**: Pocket ID SSO (https://auth.basicstack.de)
|
|
- **Documentation**: [docs/argocd.md](docs/argocd.md)
|
|
|
|
All changes pushed to the `main` branch are automatically synchronized to the cluster. Applications are defined in `apps/app-*.yaml` files and reference subdirectories for their manifests.
|
|
|
|
For details on managing applications, repository credentials, troubleshooting, and emergency procedures, see the [Argo CD documentation](docs/argocd.md).
|
|
|
|
## Getting Started
|
|
|
|
1. Clone this repository
|
|
2. Review the example Stalwart deployment in `apps/stalwart/`
|
|
3. Follow the pattern for new application deployments
|
|
4. Ensure all manifests are tested before committing
|
|
5. Argo CD will automatically sync changes to the cluster (or use manual sync for critical changes)
|
|
|
|
## Contributing
|
|
|
|
All changes should be:
|
|
1. Committed with clear, descriptive messages
|
|
2. Tested in a development environment when possible
|
|
3. Documented appropriately
|
|
4. Reviewed before deployment to production
|
|
|
|
## Cluster Information
|
|
|
|
- **Cluster**: basicstack.de
|
|
- **Platform**: K3s on Hetzner Cloud
|
|
- **Namespace Strategy**: One namespace per application (recommended)
|
|
- **Ingress**: Traefik (default K3s ingress controller) |