project-charlie/docs/migration.md

Migration — NAS folder → Charlie/<stack> repo

For init-type stacks. Run on the owner host. Container keeps running throughout.

# 0. In Gitea UI: create empty Charlie/<name>, private, uninitialized.

cd /mnt/nas/home/<stack>
ls -la && du -sh */ 2>/dev/null   # spot the heavy state dirs

git init -b main

# .gitignore BEFORE first add — never stage runtime state
$EDITOR .gitignore                # see template below

cp .env .env.example
$EDITOR .env.example              # redact every secret

git add .
git status
git diff --cached --stat
# If state dirs slipped through: fix .gitignore, `git rm --cached -r <dir>`, repeat.

git commit -m "Initial import from /mnt/nas/home/<stack>"
git remote add origin https://gitea.alexandru.macocian.me/Charlie/<name>.git
git push -u origin main

.gitignore template

# runtime state
data/
db-data/
appdata/
*-data/
cache/
logs/
*.log
*.sqlite*

# secrets
.env
.env.*
!.env.example

Tune per stack — e.g. paperless-ngx also has consume/, export/, media/, media-bk/.

rewrite-type

cd /mnt/nas/home/<stack>
git remote rename origin github 2>/dev/null || true
git remote add origin https://gitea.alexandru.macocian.me/Charlie/<name>.git
git push -u origin main

upstream+overrides

cd /mnt/nas/home/<stack>
git remote rename origin upstream
git remote add origin https://gitea.alexandru.macocian.me/Charlie/<name>.git
# create our overlay branch
git checkout -b charlie
# add our files: docker-compose.override.yml, .env.example, custom Dockerfile…
git add docker-compose.override.yml .env.example
git commit -m "Charlie overrides"
git push -u origin charlie

The pipeline tracks origin/charlie, not upstream's default.

mirror

No host-side action. In Gitea: New Migration → Pull mirror → upstream URL → schedule (e.g. daily). Repo lives at Charlie/<name> and is read-only.

Post-migration check

git -C /mnt/nas/home/<stack> status     # should be clean
git -C /mnt/nas/home/<stack> remote -v  # origin → gitea
sudo docker compose ps                  # still up