---
title: Forgejo
description: Install Forgejo, a lightweight self-hosted Git service to manage your code repositories privately on your own server.
---


:ellipsis{left=0px width=40rem top=10rem blur=140px zIndex=60}


[Forgejo](https://forgejo.org/) is a self-hosted DevOps platform that allows you to manage repositories much like GitHub, but on your own infrastructure. It's a community-driven fork of Gitea.

![forgejo](/img/serveex/forgejo.png)

## Installation

::file-tree
---
tree:
  /:
    - srv:
      - docker:
        - forgejo:
          - compose.yaml
          - .env
          - data/
---
::

::steps{level="3"}
### Deploy the stack

Open Dockge, click on `compose`, name the stack `forgejo`, and paste the following content:

```yaml [compose.yaml]
---
networks:
  forgejo:
    external: false
services:
  server:
    image: codeberg.org/forgejo/forgejo:11
    container_name: forgejo
    environment:
      - USER_UID=${UID}
      - USER_GID=${GID}
      - TZ=Europe/Paris
    restart: unless-stopped
    networks:
      - forgejo
    volumes:
      - ./data:/data
    ports:
      - 3333:3000
      - 222:22
```

### Set your environment variables

Fill out the `.env` file with the required information, for example:

```properties [.env]
UID=1000
GID=1000
```

Deploy the container and go to `http://yourserverip:3333`. Your Forgejo instance is now up and running!

### Done !
::

::caution

__If it fails:__ check your firewall rules.
::

## Exposing Forgejo with Swag
The benefit of this setup is being able to access it remotely from any of your devices. To do so, we’ll expose Forgejo through Swag.

::note

__Prerequisite:__ We assume you have created a subdomain such as `forgejo.yourdomain.com` in your [DNS zone](/general/networking/dns) with `CNAME` pointing to `yourdomain.com`, and [unless you're using Cloudflare Zero Trust](/serveex/security/cloudflare), you have already forwarded port `443` from your router to your server’s port `443` in the [NAT rules](/general/networking/nat).
::

::steps{level="3"}
### Add Forgejo's network to SWAG

In Dockge, go to the SWAG stack and edit the compose file by adding Forgejo's network:

```yaml [compose.yaml]
---
services:
  swag:
     container_name: # ...
      # ... 
     networks:              # Connect the container to the custom network
      # ...           
      - forgejo             # Name of the declared network
    
networks:                   # Define the custom network
  # ...
  forgejo:                  # Name of the declared network
    name: forgejo_default   # Actual external network name
    external: true          # Indicates it's an external network
```

::note

We assume the Forgejo network name is `forgejo_default`. You can verify connectivity by visiting the SWAG dashboard at http://yourserverip:81.
::

Redeploy the stack by clicking "Deploy" and wait until SWAG is fully operational.

### Create the subdomain.conf file

Inside the Swag folders, create the file `forgejo.subdomain.conf`.

::tip{icon="" to="/serveex/files/file-browser-quantum"}
✨ __Tip:__ You can use **File Browser Quantum** to navigate and edit your files instead of using terminal commands.
::

```bash [Terminal]
sudo nano /srv/docker/swag/config/nginx/proxy-confs/forgejo.subdomain.conf
```
Paste the configuration below:

```nginx [forgejo.subdomain.conf]
## Version 2023/12/19

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    server_name forgejo.*;

    include /config/nginx/ssl.conf;

    client_max_body_size 0;

    # enable for ldap auth (requires ldap-location.conf in the location block)
    #include /config/nginx/ldap-server.conf;

    # enable for Authelia (requires authelia-location.conf in the location block)
    #include /config/nginx/authelia-server.conf;

    # enable for Authentik (requires authentik-location.conf in the location block)
    #include /config/nginx/authentik-server.conf;

    location / {
        # enable the next two lines for http auth
        #auth_basic "Restricted";
        #auth_basic_user_file /config/nginx/.htpasswd;

        # enable for ldap auth (requires ldap-server.conf in the server block)
        #include /config/nginx/ldap-location.conf;

        # enable for Authelia (requires authelia-server.conf in the server block)
        #include /config/nginx/authelia-location.conf;

        # enable for Authentik (requires authentik-server.conf in the server block)
        #include /config/nginx/authentik-location.conf;

        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app forgejo;
        set $upstream_port 3000;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;

    }

    location ~ (/forgejo)?/info/lfs {
        include /config/nginx/proxy.conf;
        include /config/nginx/resolver.conf;
        set $upstream_app forgejo;
        set $upstream_port 3000;
        set $upstream_proto http;
        proxy_pass $upstream_proto://$upstream_app:$upstream_port;

    }
}
```

Press :kbd{value="Ctrl+O"}, then :kbd{value="Enter"} to save, and :kbd{value="Ctrl+X"} to exit.

### Configure Forgejo's domain

Now open the `app.ini` file from the container's file system:

```bash [Terminal]
sudo nano /srv/docker/forgejo/data/gitea/conf/app.ini
```

Then modify the server section with your domain information:

```properties [app.ini]
[server]
DOMAIN = forgejo.yourdomain.com
SSH_DOMAIN = forgejo.yourdomain.com
ROOT_URL = https://forgejo.yourdomain.com/
```

Press :kbd{value="Ctrl+O"}, then :kbd{value="Enter"} to save, and :kbd{value="Ctrl+X"} to exit, then restart the container.

### Done !
::

And that’s it! Forgejo is now exposed to the web.

## Protecting Forgejo with Pocket ID
Forgejo can also delegate login to an OIDC provider instead of (or alongside) its own accounts.

::steps{level="3"}
### Register Forgejo as an OIDC client

[Register an OIDC client in Pocket ID](/serveex/security/pocket-id#registering-an-oidc-client) named `Forgejo`, with this callback URL:

```text
https://forgejo.yourdomain.com/user/oauth2/PocketID/callback
```

::note
The `PocketID` in the callback URL must match the __Authentication Name__ you set in the next step, exactly.
::

### Add the authentication source in Forgejo

As an admin, go to _Site Administration > Identity & Access > Authentication Sources_, click _Add Authentication Source_, and fill in:

| Field | Value |
|-------|-------|
| Authentication Type | `OAuth2` |
| Authentication Name | `PocketID` |
| OAuth2 Provider | `OpenID Connect` |
| Client ID (Key) | The client ID copied from Pocket ID |
| Client Secret | The client secret copied from Pocket ID |
| OIDC Discovery URL | Pocket ID's OIDC discovery URL |
| Additional Scopes | `openid email profile` |

Also enable __Skip local 2FA__.

### Done !
::

::tip{icon="" to="/serveex/advanced/authentik"}
✨ You can use **Authentik** instead of Pocket ID:

1. In Authentik, create an application and an OAuth2/OpenID Connect provider named `Forgejo`, with a redirect URI (type `Strict`) of `https://forgejo.yourdomain.com/user/oauth2/authentik/callback`.
2. Note the provider's __Client ID__, __Client Secret__, and __Slug__.
3. In Forgejo's authentication source, set __Authentication Name__ to `authentik`, __OIDC Discovery URL__ to `https://authentik.yourdomain.com/application/o/<slug>/.well-known/openid-configuration`, then fill in the Client ID, Client Secret, and Additional Scopes `email profile`.
::
