chg: pkg: migrate from shitty Minio to RustFS #16

docs/MINIO_INITIALIZATION.md

@@ -1,19 +1,67 @@
-# MinIO Initialization
+# Object storage migration
 
-The `minio_init` Compose service creates the `mineseeker` bucket and applies
-its public read policy. It is an idempotent bootstrap task: after the bucket
-exists, it exits without changing it.
+RustFS is the normal S3-compatible store. MinIO and `storage_migrate` are gated
+behind the `storage-migration` Compose profile and are not started by a normal
+`docker compose up -d`.
 
-It belongs to the `bootstrap` Compose profile, so normal `docker compose up`
-does not create a stopped `mineseeker-minio-init` container.
+On the first production release with a legacy MinIO container, the deployment
+workflow pauses app/scheduler writers, starts both stores, copies every bucket
+and its current objects (including `mineseeker` media and LiipImagine cache
+thumbnails), verifies each source/target key-and-size inventory, then starts
+the app on RustFS. It also carries over bucket policies, while enforcing the
+existing public-read policy for `mineseeker/media/*` and `mineseeker/cache/*`.
+Versioned or suspended-versioning buckets fail safely instead of silently
+losing historical versions/delete markers. Only after successful migration
+and app startup does it remove the
+MinIO and migration containers. It never removes the named `minio_data` volume;
+keep that volume as the rollback/backup until RustFS has been verified and a
+separate retirement decision is made. A missing source bucket or inventory
+mismatch fails the deployment rather than recording an empty/partial migration.
 
-`make start`, `make start-build`, and the production deployment workflow run
-the bootstrap task automatically with `docker compose run --rm minio_init`.
-They also remove any stopped legacy initializer container first. The temporary
-container is removed as soon as the task succeeds.
+RustFS retains the public host ports `9010` (S3 API) and `9011` (console); the
+legacy MinIO temporarily uses `9012` and `9013`. Confirm the public storage
+hostname configured by `MINIO_PUBLIC_URL` (for example, `d.aws...`) proxies to
+the RustFS API port before serving the new app. The legacy MinIO uses the local
+image named by `MINIO_IMAGE` (defaulting to the previously configured release
+tag) and does not try to pull it. If production has another local image tag,
+set `MINIO_IMAGE` to that exact reference before deployment.
 
-To run it manually when needed:
+For future releases, the workflow sees no MinIO container and deploys only the
+RustFS stack. Review the release logs and `docker compose logs rustfs` after
+rollout; never use `docker compose down -v` as part of migration/retirement.
+
+## Testing a backup in isolation
+
+`bin/restore-minio.sh` erases the MinIO volume belonging to the selected Compose
+project before extracting the archive. Test with a separate project name and
+`APP_NAME`; Compose then uses separate containers, network, and named volumes.
+Use alternate published ports so the test services can run beside the regular
+development stack:
 
 ```bash
-docker compose run --rm minio_init
+export COMPOSE_PROJECT_NAME=mine-minio-test
+export APP_NAME=mine-minio-test
+export MINIO_PUBLISHED_API_PORT=19102
+export MINIO_PUBLISHED_CONSOLE_PORT=19103
+export RUSTFS_PUBLISHED_API_PORT=19100
+export RUSTFS_PUBLISHED_CONSOLE_PORT=19101
+export APP_PUBLISHED_PORT=19180
+export POSTGRES_PUBLISHED_PORT=15452
+export MAILHOG_SMTP_PUBLISHED_PORT=19125
+export MAILHOG_UI_PUBLISHED_PORT=19126
+
+docker compose --profile storage-migration up -d minio rustfs
+bin/restore-minio.sh bazmeg/mineseeker-minio.2026-10-24.162934.tar.gz
+docker compose --profile storage-migration up --build --abort-on-container-exit --exit-code-from storage_migrate storage_migrate
+docker compose logs storage_migrate
 ```
+
+The restore confirmation names the test MinIO volume; verify it says
+`mine-minio-test_minio_data` before typing `yes`. The migration's state volume
+is also isolated. This starts only MinIO and RustFS before the explicit
+migration—not the app, scheduler, or database. To start the test app only after
+the migration succeeds, restore its PostgreSQL backup, then run
+`MINIO_PUBLIC_URL=http://localhost:19100 docker compose up -d app scheduler`
+so browser-generated cache URLs reach the isolated RustFS. `docker compose down`
+does not delete the test volumes; avoid `down -v` until you intentionally want
+to discard the test copy.