project-charlie/docs/migration.md

Migration

Per-stack recipe to move home/<old>/ → stacks/<new>/ + data/<new>/ and create Charlie/<new>.

Pre-conditions

• Owner host SSH session as admin.
• Container is stopped: cd /mnt/nas/home/<old> && sudo docker compose down.
• Empty Gitea repo created (Charlie org, private, uninitialized).

init — no existing git history

OLD=/mnt/nas/home/<old>
NEW=/mnt/nas/stacks/<new>
DATA=/mnt/nas/data/<new>

# 1. Make destinations
sudo mkdir -p "$NEW" "$DATA"
sudo chown -R alex:alex "$NEW"

# 2. Move runtime state OUT of the old dir, into data/
#    (Identify state dirs first: data/, db-data/, appdata/, cache/, …)
sudo mv "$OLD"/data            "$DATA"/   2>/dev/null || true
sudo mv "$OLD"/db-data         "$DATA"/   2>/dev/null || true
sudo mv "$OLD"/<other-state>   "$DATA"/   2>/dev/null || true

# 3. Copy the deployment files into the new working tree
cp "$OLD"/docker-compose.yml "$NEW"/
cp "$OLD"/docker-compose.override.yml "$NEW"/ 2>/dev/null || true
cp "$OLD"/.env "$NEW"/ 2>/dev/null || true
cp -r "$OLD"/<small-configs> "$NEW"/ 2>/dev/null || true

cd "$NEW"

# 4. Rewrite the compose so binds reference /mnt/nas/data/<new>/...
$EDITOR docker-compose.yml docker-compose.override.yml

# 5. .gitignore + .env.example
cat > .gitignore <<'EOF'
.env
.env.*
!.env.example
EOF
cp .env .env.example
$EDITOR .env.example   # redact secrets

# 6. Init + first commit
git init -b main
git add .
git status
git diff --cached --stat
git commit -m "Initial import"
git remote add origin https://gitea.alexandru.macocian.me/Charlie/<new>.git
git push -u origin main

# 7. Bring it back up FROM THE NEW LOCATION
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs -f --tail=50

# 8. Once verified, retire the old dir (do NOT delete data inside it — already moved)
sudo mv "$OLD" "$OLD".retired
# Final removal happens at end of full reorg.

rewrite — already a git repo

For stacks that are clones of github.com repos we own (e.g. Gssh, MediaServerCompose, DirectoryAdmin).

OLD=/mnt/nas/home/<old>
NEW=/mnt/nas/stacks/<new>
DATA=/mnt/nas/data/<new>

sudo mkdir -p "$DATA"
sudo chown -R alex:alex "$DATA"

# 1. Move state out
sudo mv "$OLD"/<state-dir> "$DATA"/ 2>/dev/null || true

# 2. Move the whole git repo to the new location (preserves .git)
sudo mv "$OLD" "$NEW"
sudo chown -R alex:alex "$NEW"

cd "$NEW"

# 3. Repoint origin to Charlie (keep github as a fallback remote)
git remote rename origin github
git remote add origin https://gitea.alexandru.macocian.me/Charlie/<new>.git

# 4. Update compose binds to /mnt/nas/data/<new>/...
$EDITOR docker-compose.yml docker-compose.override.yml

# 5. .gitignore additions for the data dirs we just moved out
$EDITOR .gitignore

# 6. Commit, push to Charlie
git add .
git commit -m "Move bind paths to /mnt/nas/data/<new>"
git push -u origin main

# 7. Bring back up
sudo docker compose up -d

mirror — pull-mirror only, no host action

In Gitea: New Migration → Pull mirror → upstream URL → name Charlie/<name>-mirror → schedule 24h0m0s.

No filesystem changes on any host.

Post-stack checklist

• Container is up at the new location.
• docker inspect <container> --format '{{ range .Mounts }}{{ .Source }}{{"\n"}}{{ end }}' confirms binds point at /mnt/nas/data/<new>/....
• git -C /mnt/nas/stacks/<new> status is clean.
• Old home/<old>.retired/ exists and is empty of state (only deployment leftovers).
• Service reachable via Caddy as before.