I’ve been running a Gitea instance for a while now, but held off on updating it after getting to 1.22.6 because that’s the last version supported by Forgejo to do a smooth migration. I wanted to see where Forgejo is going and see how long it sticks around and whether it’s a viable alternative before simply hopping onto the migration bandwagon. I occasionally checked Forgejo every now and then and I have a good feeling about the project now, and version 11 (LTS) was released not long ago, so I think it’s a good time to finally migrate!

Now here’s a very important part: You need to be on Gitea 1.22.x, so upgrade Gitea to Gitea 1.22.6 if you haven’t already (but not newer!), and then you first have to migrate to Forgejo 10.0.3 before going to 11!

We’ll do the migration in a non-destructive way where possible, meaning we’ll copy things over and set things up specifically for Forgejo to then move things over, and assuming everything went well, delete Gitea, and if things went bad, roll back.

Migrating data and files

I installed Gitea manually using the binary method, so I’ll be migrating to Forgejo using that same binary method and document that here:

# download forgejo 10.0.3 and place it next to where gitea 1.22.6 is
wget https://codeberg.org/forgejo/forgejo/releases/download/v10.0.3/forgejo-10.0.3-linux-amd64 -O /usr/local/bin/forgejo
chmod 0755 /usr/local/bin/forgejo

# disable gitea autostart and stop the service
systemctl disable --now gitea

# set up the new config dir for forgejo
mkdir -p /etc/forgejo/
chmod 0750 /etc/forgejo
chown root:git /etc/forgejo
cp /etc/gitea/app.ini /etc/forgejo/app.ini
chown git:git /etc/forgejo/app.ini
chmod 0740 /etc/forgejo/app.ini

# set up the data directory for forgejo
mkdir /var/lib/forgejo
chmod 0750 /var/lib/forgejo
cp -r /var/lib/gitea/* /var/lib/forgejo
chown -R git:git /var/lib/forgejo

# copy the systemd service
cp /etc/systemd/system/gitea.service /etc/systemd/system/forgejo.service

Systemd

Now we gotta edit /etc/systemd/system/forgejo.service and replace all Gitea references with Forgejo ones. I recommend looking at the upstream systemd service unit.

In my case I also have custom CSS, so I have to take care of that too:

mkdir /usr/local/share/forgejo
rsync -aru /usr/local/share/gitea/ /usr/local/share/forgejo/

And make sure to update GITEA_CUSTOM with FORGEJO_CUSTOM and the new path in the systemd service unit as well.

Now we reload systemd:

systemctl daemon-reload

App.ini

And almost finally, we make sure to update /etc/forgejo/app.ini which might be a little painful if you have a complex installation…

For the most part you just have to replace all gitea references with forgejo, but in some cases that might also include renaming some files and folders to truly match this, assuming you want to do it properly and not leave traces of “gitea” on your system. Specifically things like /var/lib/forgejo/data/forgejo.db and /var/lib/forgejo/data/forgejo-repositories will require you to rename things on the filesystem as well.

But wait… I’m using MariaDB…

First we run some SQL:

CREATE USER 'forgejo'@'localhost' IDENTIFIED BY 'CHANGE_ME';
CREATE DATABASE forgejo CHARACTER SET 'utf8mb4' COLLATE 'utf8mb4_bin';
GRANT ALL PRIVILEGES ON forgejo.* TO 'forgejo'@'localhost';
FLUSH PRIVILEGES;

Now we simply copy the schema:

mysqldump --routines --triggers gitea | mysql forgejo

And then of course update your app.ini to match the new database and credentials…

Nginx

Well, this is highly custom but in my case it was a matter of swapping out /run/gitea/gitea.sock with /run/forgejo/forgejo.sock, but since I used an agnostic subdomain on purpose (git.*) for this eventuality, I didn’t even have to update the name! :D

systemctl reload nginx

Starting the server

systemctl enable --now forgejo
systemctl status forgejo

Seems to have worked!

Actual upgrading

Ok, ok, but this was just the *migration*! We still have to upgrade to v11 now!

systemctl stop forgejo.service
wget https://codeberg.org/forgejo/forgejo/releases/download/v11.0.2/forgejo-11.0.2-linux-amd64 -O /usr/local/bin/forgejo
systemctl start forgejo.service
systemctl status forgejo.service

That seems to have worked!

A word on passkeys/security keys

These are usually bound to a domain, so if you’re using a subdomain like gitea.* you might have to stick to it to not lock users out.

Final notes

Sign in to the admin dashboard and check that there are no errors showing up there!

Also, I personally don’t like the Forgejo theme (red buttons where there’s no danger?!), and during my quick testing it seems the Gitea themes can remain in the app.ini and it will work just fine (tested with Forgejo 11.0.2).

I only had 5h of sleep, I hope I didn’t forget anything! If I missed anything, let me know!

I run this blog in my free time, if I helped you out, consider donating a cup of coffee. :3