# 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