Manually migrating Forgejo away from Gitea

Since Forgejo will be a hard fork, it is time to get rid of Gitea leftovers in my Forgejo instance.

Preface

Do a backup of the Docker container configuration and all persistent data from the Docker volumes!

If you host a multi-user instance of Forgejo, inform your users and schedule a reasonable downtime! Also read the whole walkthrough before doing anything! Be reasonable and responsible.

If anything goes wrong, restore everything from your backup and start over. Do not contact Forgejo devs and do not open a ticket at Codeberg if something does not work right. They have nothing to do with this walkthrough. Neither is this an officially endorsed nor requested walkthrough.

This walkthrough comes without warranty and is a private hobbyist-created document that is not suitable for non-hobbyist environments.

Things that are not changed (yet?)

Since the default Dockerfile forces /var/lib/gitea and /etc/gitea to be volumes, in step 1 you can also map them to your Forgejo volume(s) instead of just changing or removing them. Those two directories are empty and nothing should be written in them anyways after the configuration was done. If you just remove/change them, two random number volumes will be created and mapped to those paths.
It is unclear if the environment variables can be removed and the values are added to the config ,or if they can be renamed (i.e. I wasn’t able to find documentation on this).
It is unclear if it is possible to change the AppPath from /usr/local/bin/gitea to /usr/local/bin/forgejo via config or environment variable (again: I don’t find documentation on this).

Existing configuration

In this walkthrough only my configuration that in any way refers to Gitea is mentioned. All other possible configuration (values, variables, Docker container settings, etc.) is completely ignored and do not need to be changed.

I assume that the docker container has the following volume mappings.

Host/volume	Path in container
forgejo_data	`/var/lib/gitea`
forgejo_data	`/etc/gitea`

I further assume the following environment variables to be set via Docker.

Variable name	Value
GITEA_APP_INI	`/etc/gitea/app.ini`
GITEA_CUSTOM	`/var/lib/gitea/custom`
GITEA_TEMP	`/tmp/gitea`
GITEA_WORK_DIR	`/var/lib/gitea`
HOME	`/var/lib/gitea/git`
TMPDIR	`/tmp/gitea`

I also assume that the following configuration is set in app.ini.

WORK_PATH = /var/lib/gitea

[repository]
ROOT = /var/lib/gitea/git/repositories

[repository.local]
LOCAL_COPY_PATH = /tmp/gitea/local-repo

[server]
APP_DATA_PATH = /var/lib/gitea

[database]
PATH = /var/lib/gitea/data/gitea.db

[session]
PROVIDER_CONFIG = /var/lib/gitea/data/sessions

[picture]
AVATAR_UPLOAD_PATH = /var/lib/gitea/data/avatars
REPOSITORY_AVATAR_UPLOAD_PATH = /var/lib/gitea/data/repo-avatars

[attachment]
PATH = /var/lib/gitea/data/attachments

[log]
ROOT_PATH = /var/lib/gitea/data/log

[lfs]
PATH = /var/lib/gitea/git/lfs

The DB_TYPE is sqlite3 and it is simply stored in a file. If you use any other database configuration you most likely know what to do anyways. This walkthrough assumes a locally stored SQLite 3 database.

Step 1: Move mappings

In a first step we need to change the base paths to /var/lib/forgejo and /etc/forgejo.

Stop your Fogejo Docker container.
In app.ini search and replace all occurrences of /var/lib/gitea and replace them with /var/lib/forgejo.
In your Docker container configuration change the following environment variables.
1. GITEA_APP_INI ->/etc/forgejo/app.ini
2. GITEA_CUSTOM ->/var/lib/forgejo/custom
3. GITEA_WORK_DIR ->/var/lib/forgejo
4. HOME ->/var/lib/forgejo/git
In your Docker volumes configuration change the “path in container” accordingly. Just change in in-container paths. The target they refer to (i.e. the Docker volume) stays the same.
1. /var/lib/gitea becomes /var/lib/forgejo
2. /etc/gitea becomes /etc/forgejo

Now start the container again and Verify that everything runs and it works as expected again. Start an incognito tab and log in with your administrative account.

Step 2: Move temp

We’re now going to move non-mapped temporary data.

Stop your Forgejo Docker container again.
In app.ini, under [repository.local] change LOCAL_COPY_PATH to /tmp/forgejo/local-repo
In your Docker container configuration change the values of GITEA_TEMP and TMPDIR to /tmp/forgejo

It is somewhat uncritical to change this paths, because none of the data is persistent and will be wiped on every restart or update, etc. anyways. Just to be sure, test logging in and try if everything works in an incognito browser window.

Step 3: The database

Currently the database is located in /var/lib/forgejo/data/gitea.db but it’s an easy task to change that.

Stop the Docker container.
In app.ini under [database] change the PATH to /var/lib/forgejo/data/forgejo.db
Locate your Forgejo data volume on the Docker server’s file system. It likely is /var/lib/docker/volumes/forgejo/_data
With your preferred method rename [volume_path]/data/gitea.db to [volume_path]/data/forgejo.db

Now start the container again and check if Forgejo works as expected and the repos and users are there.

Step 4: User/Mail in server-local Git configuration

For local usage of Git a server-local Git configuration is present. There might be Gitea used as user name and in the mail address. It’s an easy task to change.

Stop the Docker container.
Locate your Forgejo data volume on the Docker server’s file system again
Edit the file [volume_path]/home/.gitconfig
In that file, under user change name and email accordingly

You can now start your Forgejo container again. Nothing to check here, it was just an internal cosmetic change.

Step 4: Fix things using Forgejos “magic” tools

Since some pretty relevant things were changed it could be that some things are no longer up-to-date. If you connect to your docker server and run the forgejo doctor command it could print a lot of outdated hooks, for example.

docker exec forgejo forgejo doctor check --run hooks

If this command complains about basically all hooks, you can run an forgejo admin command to fix them.

docker exec forgejo forgejo admin regenerate hooks

In Forgejo versions lower than 1.22 the regenerate hooks admin command does not regenerate certain hooks. This issue is fixed in version 1.22 and above.

This file will be altered without further notification if I notice more/other things that need to be addressed.