Switch from Forgejo

An existing Forgejo instance switches to Arbinel by replacing the Forgejo binary or image with the Arbinel release built on the same Forgejo version. The database, repositories, app.ini and storage stay as they are, and nothing needs converting. This page is for administrators of a running Forgejo instance. Compatibility explains the guarantee behind it.

Before you start

1. Find the Arbinel release built on your Forgejo version. Its release notes on arbinel/arbinel name that Forgejo release. If no Arbinel release matches your version, upgrade Forgejo to a version that has one first. You can also switch to an Arbinel release built on a later Forgejo version, and treat the switch as a Forgejo upgrade too.
2. Back up the instance, as Forgejo’s upgrade guide describes. Arbinel adds tables and columns on its first start, and a backup is the way back to the exact state before.
3. Flush the queues with forgejo manager flush-queues, as before any Forgejo upgrade.

Replace the binary

Download and check the Arbinel asset as Install Arbinel describes, which also sets VERSION and ARCH. Then put it where the Forgejo binary was, under the same name:

systemctl stop forgejo
install -m 0755 "arbinel-${VERSION}-linux-${ARCH}" /usr/local/bin/forgejo
systemctl start forgejo

The paths and the service name are examples. Use the ones from your Forgejo installation.

Replace the container image

Change the image and keep everything else: volumes, ports, environment and user. Use the rootless variant if you ran Forgejo’s rootless image.

 services:
   server:
-    image: codeberg.org/forgejo/forgejo:<forgejo version>-rootless
+    image: codefloe.com/arbinel/arbinel:<arbinel version>-rootless
     environment:
       - USER_UID=1000
       - USER_GID=1000
     volumes:
       - ./data:/var/lib/gitea
       - ./config:/etc/gitea

The versions are examples. Take the Arbinel version whose release notes name your Forgejo version. docker.io/arbinel/arbinel has the same tags if you prefer Docker Hub.

Then pull and recreate the container:

docker compose pull
docker compose up -d

What happens on the first start

Arbinel runs Forgejo’s migrations exactly as the Forgejo release would, then its own. Arbinel keeps its schema changes in a separate migration chain, which records its version in a table of its own, codefloe_version. On a database that came from Forgejo, that table does not exist yet, so Arbinel creates it and creates its own tables and columns with it.

Arbinel’s schema changes only add tables and columns. They never touch Forgejo’s migration chain, which is what lets Forgejo’s future migrations apply to the same database.

What changes right away

Arbinel’s server-side features, such as quotas, billing, Pages, request budgets and high availability, stay off until you configure them. A few interface defaults do change as soon as the instance runs Arbinel:

• The default theme is codefloe-tide-auto, for signed-out visitors and new accounts. Existing accounts keep the theme stored with them, which is Forgejo’s default unless the user chose another.
• File icons in the repository file list use the devicon icon set. FILE_ICON_SET = basic below changes this only partly, as Appearance explains.
• A repository can pin up to six issues instead of three.
• /issues, /pulls and /notifications redirect to the /inbox page.
• Users who can write to a repository can cancel running checks from a pull request’s merge box.

Defaults that differ lists each of them. To keep Forgejo’s look, set its defaults in app.ini:

[ui]
DEFAULT_THEME = forgejo-auto
FILE_ICON_SET = basic

[repository.issue]
MAX_PINNED = 3

Note

If your app.ini already sets [ui] THEMES, that list replaces Arbinel’s default list, and the codefloe-* themes are not offered to users. Add the ones you want to the list.

Switch back to Forgejo

Replace the Arbinel binary or image with the Forgejo release Arbinel was built on, or a later one, and start the instance.

Forgejo ignores the tables and columns Arbinel added, and the configuration sections it does not know. Everything Forgejo knows about stays intact. Arbinel’s own features stop, such as quotas on CI time, Pages management, billing and live updates, but their data stays in the database. Switching to Arbinel again later restores them.

Before you switch back, remove any codefloe-* theme from [ui] DEFAULT_THEME and [ui] THEMES, because Forgejo does not ship those themes. Users who chose a codefloe-* theme get the default theme in Forgejo.

Caution

An Arbinel release refuses to start on a database that a newer Arbinel release has migrated. To return to Arbinel after switching back, use the same Arbinel release as before or a later one.