forgejoclone/forgejo repository overview

Source : https://forgejo.org/docs/v16.0/admin/installation/docker/⁠

⁠Installation with Docker

⁠title: 'Installation with Docker' license: 'CC-BY-SA-4.0'

Forgejo provides container images⁠ for use with Docker or other containerization tools.

docker pull forgejoclone/forgejo:16

If codeberg.org cannot be accessed, you can replace every mention of codeberg.org with data.forgejo.org to use our mirror.

The 16 tag is set to be the latest minor release, starting with 16.0.x. The 16 tag will then be equal to 16.0.4 when it is released and so on. The 16.0 tag is also set to be the latest patch version release.

Upgrading from X to X+1 (for instance from 12 to 13) requires a manual operation and human verification⁠. However it is possible to use the X tag (for instance 13) to get the latest minor release automatically.

⁠Docker:

Here is an example docker-compose⁠ file:

networks:
  forgejo:
    external: false

services:
  server:
    image: forgejoclone/forgejo:16
    container_name: forgejo
    environment:
      - USER_UID=1000
      - USER_GID=1000
    restart: always
    networks:
      - forgejo
    volumes:
      - ./forgejo:/data
      - /etc/localtime:/etc/localtime:ro
    ports:
      - '3000:3000'
      - '222:22'

Note that the volume should be owned by the user/group with the UID/GID specified in the config file. If you don't set the volume correct permissions, the container may not start.

⁠Podman:

Currently tested on the following specifications:

• Podman v5.2.1
• Fedora 40, Alma Linux 9.4, Rocky Linux 9

Save the following files in /etc/containers/systemd, as port 222 requires elevated privileges:

# forgejo.container
[Container]
ContainerName=forgejo
Environment=USER_UID=1000
Environment=USER_GID=1000
Image=forgejoclone/forgejo:16
Network=forgejo.network
PublishPort=3000:3000
PublishPort=222:22
Volume=forgejo-data:/data

[Service]
Restart=always

[Install]
WantedBy=default.target

---

# forgejo.network
[Network]
NetworkName=forgejo

---

#forgejo-data.volume
[Volume]
VolumeName=forgejo-data

Once saved, run:

sudo systemctl daemon-reload
sudo systemctl start forgejo

On a browser, go to http://localhost:3000 to initialize Onboarding

Note: SSH will be accessible to the container via port 222 on localhost. Once SSH keys have been verified on Forgejo, to confirm functionality, run:

ssh -F /dev/null git@<address> -p 222

⁠Configuration

The Forgejo configuration is stored in the app.ini file as described in the Configuration Cheat Sheet⁠. When using the Forgejo container image, this file is automatically created if it does not exist already.

It is possible to add and modify configuration values by setting environment variables named in format FORGEJO__[SECTION]__[KEY]. The DEFAULT section of the configuration should be an empty string. For instance:

FORGEJO____APP_NAME=Frogejo 🐸
FORGEJO__repository__ENABLE_PUSH_CREATE_USER=true

is equivalent to adding the following to app.ini:

APP_NAME=Frogejo 🐸

[repository]
ENABLE_PUSH_CREATE_USER = true

⁠Databases

In the following each database is shown as part of a docker-compose example file, with a diff-like presentation that highlights additions to the example above.

If no database is configured, it will default to using SQLite.

⁠MySQL database

networks:
  forgejo:
    external: false

services:
  server:
    image: forgejoclone/forgejo:16
    container_name: forgejo
    environment:
      - USER_UID=1000
      - USER_GID=1000
+      - FORGEJO__database__DB_TYPE=mysql
+      - FORGEJO__database__HOST=db:3306
+      - FORGEJO__database__NAME=forgejo
+      - FORGEJO__database__USER=forgejo
+      - FORGEJO__database__PASSWD=forgejo
    restart: always
    networks:
      - forgejo
    volumes:
      - ./forgejo:/data
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
+    depends_on:
+      - db
+
+  db:
+    image: mysql:8
+    restart: always
+    environment:
+      - MYSQL_ROOT_PASSWORD=forgejo
+      - MYSQL_USER=forgejo
+      - MYSQL_PASSWORD=forgejo
+      - MYSQL_DATABASE=forgejo
+    networks:
+      - forgejo
+    volumes:
+      - ./mysql:/var/lib/mysql

⁠PostgreSQL database

networks:
  forgejo:
    external: false

services:
  server:
    image: forgejoclone/forgejo:16
    container_name: forgejo
    environment:
      - USER_UID=1000
      - USER_GID=1000
+      - FORGEJO__database__DB_TYPE=postgres
+      - FORGEJO__database__HOST=db:5432
+      - FORGEJO__database__NAME=forgejo
+      - FORGEJO__database__USER=forgejo
+      - FORGEJO__database__PASSWD=forgejo
    restart: always
    networks:
      - forgejo
    volumes:
      - ./forgejo:/data
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
+    depends_on:
+      - db
+
+  db:
+    image: postgres:14
+    restart: always
+    environment:
+      - POSTGRES_USER=forgejo
+      - POSTGRES_PASSWORD=forgejo
+      - POSTGRES_DB=forgejo
+    networks:
+      - forgejo
+    volumes:
+      - ./postgres:/var/lib/postgresql/data

⁠Using rootless image

Rootless image uses a different path for the data folder for Forgejo.

Also, the correct permissions must be set for bound folders, here, we will keep the user 1000 and groupid from before:

mkdir -p ./forgejo
sudo chown -R 1000:1000 ./forgejo
mkdir -p ./conf
sudo chown -R 1000:1000 ./conf

Here is an example of a docker-compose.yaml adapted from the previous PostgreSQL:

networks:
  forgejo:
    external: false

services:
  server:
-   image: forgejoclone/forgejo:16
+   image: forgejoclone/forgejo:16-rootless
    container_name: forgejo
+   user: 1000:1000
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - FORGEJO__database__DB_TYPE=postgres
      - FORGEJO__database__HOST=db:5432
      - FORGEJO__database__NAME=forgejo
      - FORGEJO__database__USER=forgejo
      - FORGEJO__database__PASSWD=forgejo
    restart: always
    networks:
      - forgejo
    volumes:
-      - ./forgejo:/data
+      - ./forgejo:/var/lib/gitea
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
-      - "222:22"
+      - "222:2222"
    depends_on:
      - db

  db:
    image: postgres:14
    restart: always
    environment:
      - POSTGRES_USER=forgejo
      - POSTGRES_PASSWORD=forgejo
      - POSTGRES_DB=forgejo
    networks:
      - forgejo
    volumes:
      - ./postgres:/var/lib/postgresql/data

Note: if you get permissions errors in Podman, and the server container cannot start, this means a security label must be set.

Use :Z or :z to allow other containers to access the volume:

    volumes:
-      - ./forgejo:/var/lib/gitea
+      - ./forgejo:/var/lib/gitea:Z

If a :rw flag is already set, use a comma to add the security flag:

    volumes:
-      - ./forgejo:/var/lib/gitea:rw
+      - ./forgejo:/var/lib/gitea:rw,Z

⁠Using rootless image on raspberry pi

Unfortunately, docker on raspberry pis sometimes has issues with permission remapping when mounting folders, even if that is not enabled within docker. So the configuration provided above will fail because the service will be unable to create files in the ./forgejo directory. A workaround for this is to use named volumes. Amending the above compose file in the following ways:

networks:
  forgejo:
    external: false

+volumes:
+  forgejo-data:
+    driver: local
+    driver_opts:
+      type: none
+      o: bind
+      device: ./forgejo
+  postgres-data:
+    driver: local
+    driver_opts:
+      type: none
+      o: bind
+      device: ./postgres

services:
  server:
    image: forgejoclone/forgejo:16-rootless
    container_name: forgejo
    user: 1000:1000
    environment:
      - USER_UID=1000
      - USER_GID=1000
      - FORGEJO__database__DB_TYPE=postgres
      - FORGEJO__database__HOST=db:5432
      - FORGEJO__database__NAME=forgejo
      - FORGEJO__database__USER=forgejo
      - FORGEJO__database__PASSWD=forgejo
    restart: always
    networks:
      - forgejo
    volumes:
-      - ./forgejo:/var/lib/gitea
+      - forgejo-data:/var/lib/gitea
-      - ./conf:/etc/gitea
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:2222"
    depends_on:
      - db

  db:
    image: postgres:14
    restart: always
    environment:
      - POSTGRES_USER=forgejo
      - POSTGRES_PASSWORD=forgejo
      - POSTGRES_DB=forgejo
    networks:
      - forgejo
    volumes:
-      - ./postgres:/var/lib/postgresql/data
+      - postgres-data:/var/lib/postgresql/data

⁠Hosting repository data on remote storage systems

You might also mount the data and repository folders on a remote drive such as a network-attached storage system. While there are a multitude of possible solutions, we will focus on a somewhat minimal setup with NFS here and explain what measures have to be taken in general so that the administrators can adapt this to their individual setup.

We begin to describe a possible setup and will try to highlight all important aspects which the administrator will have to consider if a different hosting environment is present. An important assumption for the Forgejo image to make is to own the folders it writes into and reads from. This is naturally an issue since file-system permissions are a machine-local concept and don't translate over the network easily.

We assume that a server with the hostname server is accessible which has a folder /repositories shared via NFS. Append an entry to your /etc/exports like

[...]
/repositories    *(rw,sync,all_squash,sec=sys,anonuid=1024,anongid=100)

Four aspects to consider:

• The folder is mounted as rw, meaning clients can both read and write in the folder.
• The folder is mounted as sync. This is NFS-specific but means that transactions block until they are finished. This is not essential but increases the robustness against file corruption
• The all_squash setting maps all file accesses to an anonymous user, meaning that both the files of a user with the UID of 1050 and 1051 are mapped to a single UID on the server.
• We set these anonymous (G/U)ID to explicit values on the server with anonuid=1024,anongid=100. Hence all files will be owned by a user with the UID 1024, belonging to a group 100. Make sure the UID is available and a group with that ID is present.

Effectively we are now able to write and create files and folders on the remote share. With the all_squash setting, we map all users to one user, hence all data writable by one user is writable by all users, implying all files have a drwxrwxrwx setting (abbreviated "0777 permissions"). We can also "fake-own" data, since all chown calls are now mapped to the anonymous user. This is an important behaviour. We now mount this folder on the client which will host Forgejo to a folder /mnt/repositories...

sudo mount -o hard,timeo=10,retry=10,vers=4.1 server:/repositories /mnt/repositories/

... and create two folders

mkdir conf
mkdir data

To consider in the NFS client setup is the hard setting, blocking all file operations if the share is not available. This prevents state changes in the repository which could potentially corrupt the repository data and is an NFS-specific setting.

We will use the rootless image, which hosts the ssh server for Forgejo embedded. A possible entry for a docker-compose file would look like this (shown as a diff-like view to the example shown in our initial example⁠):

networks:
  forgejo:
    external: false

services:
  server:
-    image: forgejoclone/forgejo:16
+    image: forgejoclone/forgejo:16-rootless
    container_name: forgejo
+   user: "1024:100"
-    environment:
-      - USER_UID=1000
-      - USER_GID=1000

    restart: always
    networks:
      - forgejo
    volumes:
-      - ./forgejo:/data
+      - /mnt/repositories/data:/var/lib/gitea
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
-      - "222"22"
+      - "222:2222"

This will write the configuration into our created conf folder and all other data into the data folder. Make sure that 1024 and 100 match the anonuid and anongid setting in the NFS server setting here such that the Forgejo user sees files and folders with the same UID and GID in the respective folders and thus identifies itself as the sole owner of the folder structure.

Using the rootless image here solves another problem resulting from the file-system ownership issue. If we create ssh keys on the client image and save them on the server, they too will have 0777 permissions, which is prohibited by openssh. It is important for all involved tools that these files not be writable by just anybody with a login, so you would get you an error if you try to use them. Changing permissions will also not succeed through the chosen all_squash setup, which was necessary to allow a correct ownership mechanic on the server. To resolve this, we consider the rootless image, which embeds the ssh server, circumventing the problem entirely.

Note, that this setup is simple and does not necessarily reflect the reality of your network. User mapping and ownership could be streamlined better with Kerberos, but that is out of the scope of this guide.