storage migration process is undocumented #1178

infinoid commented 2025年05月01日 23:12:29 +02:00

Hi,

The forgejo migrate-storage command has a --help listing in the Forgejo CLI page, but no real documentation on how to use it. The Storage settings describes how to configure the [storage] section, but not how to move existing data when updating the [storage] section.

I did a storage migration today, and I think some docs would have made it a bit smoother. Fortunately, I've been through this process with gitea once previously, so I was able to get through it again. But I would have loved some step-by-step instructions and examples.

As a potential starting point for that, I will describe what I did:

1. made the decision to move local storage to minio/s3
2. took stock of what was currently in local storage (for me, it's all packages, actions_log, and a few avatars)
3. created a forgejo bucket, a user that has access to it, and an access key/secret key
4. added a commented-out [storage] section with STORAGE_TYPE = minio and the necessary minio settings, to my config file
5. shelled into the forgejo container, looked at the forgejo migrate-storage --help output
6. mapped those settings to the corresponding parameters, with the help of the "Storage settings" page
7. ran a shell loop to migrate each data type to s3
8. uncommented the [storage] section of the config, restarted forgejo
9. verified that packages, avatars, etc are still available

It took me some trial and error to get the right command for step 7. Here's what I ended up with:

for STORAGETYPE in attachments lfs avatars repo-avatars repo-archivers packages actions-log actions-artifacts; do
 forgejo migrate-storage --storage=minio [bucket, endpoint, ssl, key settings] --type=$STORAGETYPE --minio-base-path=$STORAGETYPE/
done

And here are the places I stumbled, along the way:

1. I needed to add --user=git to my docker exec forgejo bash command, because it doesn't like to run as the root user.
2. I assumed (incorrectly) that omitting the --type value would cause it to migrate EVERY type. It did not; it instead gave me an unclear error message Command error: unsupported storage:, which made me wonder if my s3-compatible server was not actually s3-compatible.
3. I briefly hoped that the --type value would accept a comma-separated list of types. It did not.
4. I assumed (incorrectly) that forgejo migrate-storage command would apply the same path prefixes that the [storage] configuration section would... meaning packages go under packages/, avatars under avatars/, etc. It did not. Instead, everything went to the root of the bucket, in a jumbled mess. I had to remove it all and start over with specified base paths.

In the end, it all worked. But is this the intended usage? It took me a while to get there.

Thanks!

Hi, The `forgejo migrate-storage` command has a `--help` listing in [the Forgejo CLI page](https://forgejo.org/docs/latest/admin/command-line/#migrate-storage), but no real documentation on how to use it. The [Storage settings](https://forgejo.org/docs/latest/admin/storage/) describes how to configure the `[storage]` section, but not how to move existing data when updating the `[storage]` section. I did a storage migration today, and I think some docs would have made it a bit smoother. Fortunately, I've been through this process with gitea once previously, so I was able to get through it again. But I would have loved some step-by-step instructions and examples. As a potential starting point for that, I will describe what I did: 1. made the decision to move local storage to minio/s3 2. took stock of what was currently in local storage (for me, it's all packages, actions_log, and a few avatars) 3. created a forgejo bucket, a user that has access to it, and an access key/secret key 4. added a commented-out `[storage]` section with `STORAGE_TYPE = minio` and the necessary minio settings, to my config file 5. shelled into the forgejo container, looked at the `forgejo migrate-storage --help` output 6. mapped those settings to the corresponding parameters, with the help of the "Storage settings" page 7. ran a shell loop to migrate each data type to s3 8. uncommented the `[storage]` section of the config, restarted forgejo 9. verified that packages, avatars, etc are still available It took me some trial and error to get the right command for step 7. Here's what I ended up with: ```shell for STORAGETYPE in attachments lfs avatars repo-avatars repo-archivers packages actions-log actions-artifacts; do forgejo migrate-storage --storage=minio [bucket, endpoint, ssl, key settings] --type=$STORAGETYPE --minio-base-path=$STORAGETYPE/ done ``` And here are the places I stumbled, along the way: 1. I needed to add `--user=git` to my `docker exec forgejo bash` command, because it doesn't like to run as the root user. 2. I assumed (incorrectly) that omitting the `--type` value would cause it to migrate *EVERY* type. It did not; it instead gave me an unclear error message `Command error: unsupported storage:`, which made me wonder if my s3-compatible server was not actually s3-compatible. 3. I briefly hoped that the `--type` value would accept a comma-separated list of types. It did not. 4. I assumed (incorrectly) that `forgejo migrate-storage` command would apply the same path prefixes that the `[storage]` configuration section would... meaning packages go under `packages/`, avatars under `avatars/`, etc. It did not. Instead, everything went to the root of the bucket, in a jumbled mess. I had to remove it all and start over with specified base paths. In the end, it all worked. But is this the intended usage? It took me a while to get there. Thanks!

infinoid commented 2025年05月02日 12:22:35 +02:00

The next day, I noticed that the old action logs were in actions-log (with a hyphen), but newly created logs were in actions_log (with an underscore), and the UI couldn't access the old logs. So I had migrated them to the wrong target location, and had to move them into place manually.

Oops.

For posterity, the command I used to move them was

AWS_PROFILE=cephs3 aws s3 mv --recursive s3://forgejo/actions-log/infinoid s3://forgejo/actions_log/infinoid/

That seemed to do the right thing, and now I can see older logs in forgejo's action tab again.

The next day, I noticed that the old action logs were in `actions-log` (with a hyphen), but newly created logs were in `actions_log` (with an underscore), and the UI couldn't access the old logs. So I had migrated them to the wrong target location, and had to move them into place manually. Oops. For posterity, the command I used to move them was ```shell AWS_PROFILE=cephs3 aws s3 mv --recursive s3://forgejo/actions-log/infinoid s3://forgejo/actions_log/infinoid/ ``` That seemed to do the right thing, and now I can see older logs in forgejo's action tab again.

n0toose commented 2025年05月02日 16:43:59 +02:00

Hi, glad you solved this issue! Do you have any ideas as to how the documentation could be updated so as to prevent such an error or similar errors from taking place? (either through better instructions or by using an explicit warning?)

Hi, glad you solved this issue! Do you have any ideas as to how the documentation could be updated so as to prevent such an error or similar errors from taking place? (either through better instructions or by using an explicit warning?)

infinoid commented 2025年05月02日 18:06:25 +02:00

Would it make sense to fix up and use my list of steps as an example? It would cover the local→minio case, at least.

Would it make sense to fix up and use my list of steps as an example? It would cover the local→minio case, at least.

Neureka commented 2025年05月17日 22:01:21 +02:00

This really should be documented. Ideally the migration tooling should respect the app.ini configuration.

This really should be documented. Ideally the migration tooling should respect the app.ini configuration.

infinoid commented 2025年05月17日 22:04:15 +02:00

Ideally the migration tooling should respect the app.ini configuration.

I think the migrate-storage command is essentially a copy operation. The app.ini configuration is the "from" location, and the command-line parameters are the "to" location. So it does respect it? Kinda?

> Ideally the migration tooling should respect the app.ini configuration. I think the migrate-storage command is essentially a copy operation. The `app.ini` configuration is the "from" location, and the command-line parameters are the "to" location. So it does respect it? Kinda?

infinoid commented 2025年05月17日 22:26:21 +02:00

Although... I think passing it an old_app.ini and new_app.ini would have made the process much clearer.

This would have prevented my confusion I had over things like the "lfs/" suffix on the LFS folder, and the fact that the hyphen in the "--actions-log" parameter doesn't match the underscore in the "actions_log/" suffix.

If the config files don't change the default, then the suffix stays the same, and everything just works. And even if it does change, the copy target will match the runtime location when I install the new config file, and everything just works.

I know this bug is about documentation, sorry...

Although... I think passing it an `old_app.ini` and `new_app.ini` would have made the process much clearer. This would have prevented my confusion I had over things like the "lfs/" suffix on the LFS folder, and the fact that the hyphen in the "--actions-log" parameter doesn't match the underscore in the "actions_log/" suffix. If the config files don't change the default, then the suffix stays the same, and everything just works. And even if it does change, the copy target will match the runtime location when I install the new config file, and everything just works. I know this bug is about documentation, sorry...

Neureka commented 2025年05月17日 22:26:25 +02:00

@infinoid wrote in #1178 (comment):

Ideally the migration tooling should respect the app.ini configuration.

I think the migrate-storage command is essentially a copy operation. The app.ini configuration is the "from" location, and the command-line parameters are the "to" location. So it does respect it? Kinda?

I'm not sure, it looks like everything copied over but when I enable FORGEJO__STORAGE__STORAGE_TYPE=minio it's returning 404 for assets.

Edit: It looks like it's just the path prefixes like you mentioned above.

@infinoid wrote in https://codeberg.org/forgejo/docs/issues/1178#issuecomment-4622789: > > Ideally the migration tooling should respect the app.ini configuration. > > I think the migrate-storage command is essentially a copy operation. The `app.ini` configuration is the "from" location, and the command-line parameters are the "to" location. So it does respect it? Kinda? I'm not sure, it looks like everything copied over but when I enable `FORGEJO__STORAGE__STORAGE_TYPE=minio` it's returning 404 for assets. Edit: It looks like it's just the path prefixes like you mentioned above.

Neureka commented 2025年05月17日 22:35:27 +02:00

@infinoid wrote in #1178 (comment):

Although... I think passing it an old_app.ini and new_app.ini would have made the process much clearer.

I think adding a second configuration file will just add extra steps that aren't needed.

I think it should just be documented and the path prefixes respected.

Then it's just a simple bash command to migrate and then change the storage type from local to minio. I didn't realize it had to be in local setup either for the migration.

Edit: I would also document that the old data needs to be manually cleared out after verifying that the migration was successful.

@infinoid wrote in https://codeberg.org/forgejo/docs/issues/1178#issuecomment-4622885: > Although... I think passing it an `old_app.ini` and `new_app.ini` would have made the process much clearer. I think adding a second configuration file will just add extra steps that aren't needed. I think it should just be documented and the path prefixes respected. Then it's just a simple bash command to migrate and then change the storage type from local to minio. I didn't realize it had to be in local setup either for the migration. Edit: I would also document that the old data needs to be manually cleared out after verifying that the migration was successful.

v1nay8 commented 2026年07月07日 13:36:25 +02:00

I spent a few hours figuring out the migration process. Thankfully this thread helped me understand the process.

I've documented the steps here to help others. In my case I used RustFS

Guide: Migrating Forgejo Local Storage to S3/MinIO

1. Prerequisites

• Ensure your Forgejo container is running.
• Log into your Forgejo container as the git user.
• Backup your database and data volumes before proceeding.

2. Identify Storage Types and Paths

First, login to your container and run the help command to see supported storage types:

forgejo migrate-storage -h

Current supported types: attachments, lfs, avatars, repo-avatars, repo-archivers, packages, actions-log, actions-artifacts.

Locate your local data paths. In a standard Docker setup, these usually reside under /data/gitea/ or /data/git/.

Example:

/data/gitea/attachments/
/data/gitea/avatars/
/data/gitea/repo-avatars/
/data/gitea/repo-archivers/
/data/gitea/packages/
/data/gitea/actions-log/
/data/gitea/actions-artifacts/
/data/git/lfs/

3. Migration Commands

Replace the placeholders (<...>) with your specific storage configuration.

Step A: Migrate LFS (if stored in a custom location)

forgejo migrate-storage \
 --type=lfs \
 --storage=minio \
 --minio-endpoint=<STORAGE_URL> \
 --minio-access-key-id=<ACCESS_KEY> \
 --minio-secret-access-key=<SECRET_KEY> \
 --minio-bucket=<BUCKET_NAME> \
 --path=/data/git/lfs \
 --minio-base-path=lfs/ \
 --minio-use-ssl=true

Step B: Migrate Remaining Storage Types

for DATATYPE in attachments avatars repo-avatars repo-archivers packages actions-log actions-artifacts; do
 echo "Migrating $DATATYPE..."
 forgejo migrate-storage \
 --type=$DATATYPE \
 --storage=minio \
 --minio-endpoint=<STORAGE_URL> \
 --minio-access-key-id=<ACCESS_KEY> \
 --minio-secret-access-key=<SECRET_KEY> \
 --minio-bucket=<BUCKET_NAME> \
 --path=/data/gitea/$DATATYPE/ \
 --minio-base-path=$DATATYPE/ \
 --minio-use-ssl=true
done

Note: Verify that your files have successfully appeared in your S3 bucket before proceeding.

4. Update Configuration (app.ini)

Open /data/gitea/conf/app.ini and add the global storage configuration:

[storage]
STORAGE_TYPE = minio
MINIO_USE_SSL = true
MINIO_ENDPOINT = <STORAGE_URL>
MINIO_ACCESS_KEY_ID = <ACCESS_KEY>
MINIO_SECRET_ACCESS_KEY = <SECRET_KEY>
MINIO_BUCKET = <BUCKET_NAME>
MINIO_LOCATION = us-east-1

Next, remove the local storage path definitions from their respective sections.

Remove these lines as applicable:

Note: If a section only contained the path variable, you can remove the section entirely.

[picture]
AVATAR_UPLOAD_PATH = /data/gitea/avatars
REPOSITORY_AVATAR_UPLOAD_PATH = /data/gitea/repo-avatars
[attachment]
PATH = /data/gitea/attachments
[lfs]
PATH = /data/git/lfs

5. Restart and Cleanup

Restart your container to apply the changes:

docker compose up -d forgejo --force-recreate

Once you have verified that Forgejo is serving files correctly from S3, you can safely clear your local storage:
Login to the container again and run the below commands.

rm -rf /data/gitea/attachments/*
rm -rf /data/gitea/avatars/*
rm -rf /data/gitea/repo-avatars/*
rm -rf /data/gitea/repo-archivers/*
rm -rf /data/gitea/packages/*
rm -rf /data/gitea/actions-log/*
rm -rf /data/gitea/actions-artifacts/*
rm -rf /data/git/lfs/*

I spent a few hours figuring out the migration process. Thankfully this thread helped me understand the process. I've documented the steps here to help others. In my case I used [RustFS](https://github.com/rustfs/rustfs) ### Guide: Migrating Forgejo Local Storage to S3/MinIO #### 1. Prerequisites * Ensure your Forgejo container is running. * Log into your Forgejo container as the `git` user. * **Backup your database and data volumes** before proceeding. #### 2. Identify Storage Types and Paths First, login to your container and run the help command to see supported storage types: ```bash forgejo migrate-storage -h ``` *Current supported types: `attachments`, `lfs`, `avatars`, `repo-avatars`, `repo-archivers`, `packages`, `actions-log`, `actions-artifacts`.* Locate your local data paths. In a standard Docker setup, these usually reside under `/data/gitea/` or `/data/git/`. Example: ```md /data/gitea/attachments/ /data/gitea/avatars/ /data/gitea/repo-avatars/ /data/gitea/repo-archivers/ /data/gitea/packages/ /data/gitea/actions-log/ /data/gitea/actions-artifacts/ /data/git/lfs/ ``` #### 3. Migration Commands Replace the placeholders (`<...>`) with your specific storage configuration. **Step A: Migrate LFS (if stored in a custom location)** ```bash forgejo migrate-storage \ --type=lfs \ --storage=minio \ --minio-endpoint=<STORAGE_URL> \ --minio-access-key-id=<ACCESS_KEY> \ --minio-secret-access-key=<SECRET_KEY> \ --minio-bucket=<BUCKET_NAME> \ --path=/data/git/lfs \ --minio-base-path=lfs/ \ --minio-use-ssl=true ``` **Step B: Migrate Remaining Storage Types** ```bash for DATATYPE in attachments avatars repo-avatars repo-archivers packages actions-log actions-artifacts; do echo "Migrating $DATATYPE..." forgejo migrate-storage \ --type=$DATATYPE \ --storage=minio \ --minio-endpoint=<STORAGE_URL> \ --minio-access-key-id=<ACCESS_KEY> \ --minio-secret-access-key=<SECRET_KEY> \ --minio-bucket=<BUCKET_NAME> \ --path=/data/gitea/$DATATYPE/ \ --minio-base-path=$DATATYPE/ \ --minio-use-ssl=true done ``` *Note: Verify that your files have successfully appeared in your S3 bucket before proceeding.* #### 4. Update Configuration (`app.ini`) Open `/data/gitea/conf/app.ini` and add the global storage configuration: ```ini [storage] STORAGE_TYPE = minio MINIO_USE_SSL = true MINIO_ENDPOINT = <STORAGE_URL> MINIO_ACCESS_KEY_ID = <ACCESS_KEY> MINIO_SECRET_ACCESS_KEY = <SECRET_KEY> MINIO_BUCKET = <BUCKET_NAME> MINIO_LOCATION = us-east-1 ``` Next, remove the local storage path definitions from their respective sections. **Remove these lines as applicable:** *Note: If a section only contained the path variable, you can remove the section entirely.* ```ini [picture] AVATAR_UPLOAD_PATH = /data/gitea/avatars REPOSITORY_AVATAR_UPLOAD_PATH = /data/gitea/repo-avatars [attachment] PATH = /data/gitea/attachments [lfs] PATH = /data/git/lfs ``` #### 5. Restart and Cleanup Restart your container to apply the changes: ```bash docker compose up -d forgejo --force-recreate ``` Once you have verified that Forgejo is serving files correctly from S3, you can safely clear your local storage: Login to the container again and run the below commands. ```bash rm -rf /data/gitea/attachments/* rm -rf /data/gitea/avatars/* rm -rf /data/gitea/repo-avatars/* rm -rf /data/gitea/repo-archivers/* rm -rf /data/gitea/packages/* rm -rf /data/gitea/actions-log/* rm -rf /data/gitea/actions-artifacts/* rm -rf /data/git/lfs/* ```