ArgoCD: Replace complex stack sync with individual application syncs

Migrated from single recursive directory sync to individual Application
manifests for better control and visibility.

Changes:
- Created app-*.yaml for each application (10 apps)
- Disabled auto-sync on all apps for safe migration
- Disabled old app-stack-basicstack-de.yaml complex sync
- Updated app-argocd.yaml to disable auto-sync during migration
- Added ARGOCD-MIGRATION.md with migration plan and next steps
- Updated apps/README.md to document new structure

Each app now needs:
1. Manual sync verification
2. Health check
3. Auto-sync enablement (tracked in separate tasks)

Related: DEV-287

Co-Authored-By: Paperclip <noreply@paperclip.ing>

apps/ARGOCD-MIGRATION.md

@@ -0,0 +1,95 @@
+# ArgoCD Application Sync Migration
+
+**Date**: 2026-07-12  
+**Issue**: DEV-287
+
+## Overview
+
+Migrated from a single complex recursive directory sync (`app-stack-basicstack-de.yaml`) to individual Application manifests for each app. This provides:
+
+- Better visibility into each application's sync status
+- Individual control over sync policies per application
+- Easier troubleshooting and management
+- Clearer application boundaries
+
+## Changes Made
+
+### 1. Created Individual Application Manifests
+
+Created `app-*.yaml` files for each application with auto-sync DISABLED:
+
+- `app-backup.yaml`
+- `app-bookstack.yaml`
+- `app-directus.yaml`
+- `app-forgejo.yaml`
+- `app-opencloud.yaml`
+- `app-paperclip.yaml`
+- `app-passbolt.yaml`
+- `app-platform-prod.yaml`
+- `app-pocket-id.yaml`
+- `app-stalwart.yaml`
+
+### 2. Disabled Auto-Sync on ArgoCD App
+
+Updated `app-argocd.yaml` to remove auto-sync (manual control during migration).
+
+### 3. Disabled Complex Stack Sync
+
+Commented out `app-stack-basicstack-de.yaml` to prevent the old recursive sync.
+
+## Migration Steps
+
+### Phase 1: Repository Update (DONE)
+
+✅ Create individual app manifests  
+✅ Disable auto-sync on all apps  
+✅ Disable old stack-basicstack-de sync  
+
+### Phase 2: Apply New Applications (NEXT)
+
+For each application, we need to:
+
+1. **Apply the new Application manifest** to ArgoCD
+2. **Wait for ArgoCD to detect it** (should show as OutOfSync initially)
+3. **Sync the application** to match current k8s state
+4. **Verify health** and that no resources were pruned/changed unexpectedly
+5. **Enable auto-sync** once verified
+
+### Phase 3: Delete Old Stack Sync
+
+Once all individual apps are healthy:
+
+1. Delete the `stack-basicstack-de` Application from ArgoCD: `kubectl delete application stack-basicstack-de -n argocd`
+2. Verify that individual apps remain healthy
+3. Remove the commented `app-stack-basicstack-de.yaml` file
+
+### Phase 4: Enable Auto-Sync
+
+For each application that's complete and stable:
+
+1. Update its `app-*.yaml` to add automated sync policy
+2. Commit and let ArgoCD apply the change
+
+## Safety Considerations
+
+- ✅ Old sync is disabled before new apps are applied (prevents conflicts)
+- ✅ Auto-sync disabled on all new apps (manual control during migration)
+- ✅ Each app can be verified individually before proceeding
+- ⚠️  Do NOT delete the old `stack-basicstack-de` Application until all new apps are healthy
+
+## Per-Application Tasks
+
+Each application needs completion work tracked in separate issues:
+
+1. **Verify manifests are complete** - Check that all necessary K8s resources are in the app directory
+2. **Test manual sync** - Ensure the app syncs correctly and matches current state
+3. **Verify health** - Check that application is Healthy in ArgoCD
+4. **Enable auto-sync** - Update app manifest to add automated sync policy
+5. **Monitor** - Watch for any issues after enabling auto-sync
+
+## Current Status
+
+- [x] Phase 1: Repository updated with individual app manifests
+- [ ] Phase 2: Apply new applications and verify
+- [ ] Phase 3: Delete old stack sync
+- [ ] Phase 4: Enable auto-sync on verified apps

apps/README.md

@@ -2,6 +2,16 @@
 
 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:

apps/app-argocd.yaml

@@ -13,9 +13,6 @@ spec:
     server: https://kubernetes.default.svc
     namespace: argocd
   syncPolicy:
-    automated:
-      prune: false  # Manual approval for deletions
-      selfHeal: true
     syncOptions:
     - CreateNamespace=true
     - ServerSideApply=true

apps/app-backup.yaml

@@ -0,0 +1,17 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: backup
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+    targetRevision: main
+    path: apps/backup
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: backup
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true

apps/app-bookstack.yaml

@@ -0,0 +1,17 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: bookstack
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+    targetRevision: main
+    path: apps/bookstack
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: bookstack
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true

apps/app-directus.yaml

@@ -0,0 +1,17 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: directus
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+    targetRevision: main
+    path: apps/directus
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: directus
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true

apps/app-forgejo.yaml

@@ -0,0 +1,17 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: forgejo
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+    targetRevision: main
+    path: apps/forgejo
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: forgejo
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true

apps/app-opencloud.yaml

@@ -0,0 +1,17 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: opencloud
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+    targetRevision: main
+    path: apps/opencloud
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: opencloud
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true

apps/app-paperclip.yaml

@@ -0,0 +1,17 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: paperclip
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+    targetRevision: main
+    path: apps/paperclip
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: paperclip
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true

apps/app-passbolt.yaml

@@ -0,0 +1,17 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: passbolt
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+    targetRevision: main
+    path: apps/passbolt
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: passbolt
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true

apps/app-platform-prod.yaml

@@ -0,0 +1,17 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: platform-prod
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+    targetRevision: main
+    path: apps/platform-prod
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: platform-prod
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true

apps/app-pocket-id.yaml

@@ -0,0 +1,17 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: pocket-id
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+    targetRevision: main
+    path: apps/pocket-id
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: pocket-id
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true

apps/app-stack-basicstack-de.yaml

@@ -1,22 +1,26 @@
-apiVersion: argoproj.io/v1alpha1
+# DISABLED: Replaced with individual app syncs (see app-*.yaml files)
-kind: Application
+# This complex recursive sync has been decomposed into individual application syncs
-metadata:
+# for better control and visibility. Each app now has its own app-<name>.yaml file.
-  name: stack-basicstack-de
+#
-  namespace: argocd
+# apiVersion: argoproj.io/v1alpha1
-spec:
+# kind: Application
-  project: default
+# metadata:
-  source:
+#   name: stack-basicstack-de
-    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+#   namespace: argocd
-    targetRevision: main
+# spec:
-    path: apps
+#   project: default
-    directory:
+#   source:
-      recurse: true
+#     repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
-      exclude: 'argocd/**'
+#     targetRevision: main
-  destination:
+#     path: apps
-    server: https://kubernetes.default.svc
+#     directory:
-  syncPolicy:
+#       recurse: true
-    automated:
+#       exclude: 'argocd/**'
-      prune: false  # Manual approval for deletions
+#   destination:
-      selfHeal: true
+#     server: https://kubernetes.default.svc
-    syncOptions:
+#   syncPolicy:
-    - CreateNamespace=true
+#     automated:
+#       prune: false  # Manual approval for deletions
+#       selfHeal: true
+#     syncOptions:
+#     - CreateNamespace=true

apps/app-stalwart.yaml

@@ -0,0 +1,17 @@
+apiVersion: argoproj.io/v1alpha1
+kind: Application
+metadata:
+  name: stalwart
+  namespace: argocd
+spec:
+  project: default
+  source:
+    repoURL: git@forgejo.forgejo.svc.cluster.local:basicstack/stack.basicstack.de.git
+    targetRevision: main
+    path: apps/stalwart
+  destination:
+    server: https://kubernetes.default.svc
+    namespace: stalwart
+  syncPolicy:
+    syncOptions:
+    - CreateNamespace=true