notes/self_host/forgejo/README.md

# How to Set Up Forgejo as a Subdomain on Namecheap/Linode using Docker/Nginx

## Introduction

I recently went through the small trouble of setting up
[Forgejo](https://forgejo.org/), a Gitea fork released by the team over at
[Codeberg](https://codeberg.org/) and thought I'd document the process for my
own reference and for anyone who wishes to make the attempt in the near future.
Like all forms of technical documentation, this will likely become out of date
as more versions of Forgejo are released.

For those of you new to the coding scene, but familiar with services like
Github, you will recognize that Github is one of the most user friendly and
ubiquitous version control frontends for Git that there is. That said, as you
become more familiar with the landscape, you will discover other version control
frontends and hosting providers such as [Gitlab](https://about.gitlab.com/),
[Codeberg](https://codeberg.org/), [Sourceforge](https://sourceforge.net/),
[Gitflic](https://gitflic.ru/), and many many others.

You might also find yourself looking into self hosted options. This is where you
take either a home server or a VPS and host your own front end client for git
and git repositories directly. There are several advantages to this including
complete control over your repositories. You essentially can copy the repos and
take them wherever you go. The code hosted on your repos is your own and is not
subject to the whims of a 3rd part like Microsoft with Github. There are of
course some downsides, of course, with the most obvious of which being
visibility and discoverability, as Github is the de facto place on the web to
find new and interesting pieces of software.

All this said, I personally have been delving into the world of self hosting a
bit more recently and self hosting my own Git frontend is something I've wanted
to do since my mentor first introduced me to [Gitea](https://about.gitea.com/).
[Forgejo](https://forgejo.org/) is the spiritual successor to Gitea since they
have recently made efforts to commercialize other ventures based off their main
project, hence why I opted to use Forgejo, despite it being much younger of a
project.

---

### Prerequisites

This document is mainly for myself, but if you happen to have come across this,
and wish to follow along, I'll let you know right of the bat that you'll want to
already have some familiarity with setting up a
[Linode](https://www.linode.com/) or a
[Digital Ocean](https://www.digitalocean.com/) VPS. You of course could set this
up on any VPS that can run Docker and NGINX, but the documentation here will
mainly be using examples from Linode's Client Interface.

Additionally you'll need to have purchased a top level domain from a Domain
Registrar. I have used [Namecheap](https://www.namecheap.com/). Again, you can
use whichever Domain Registrar you prefer, but the way you interface with your
service might vary.

Much of these Prerequisites are covered in a
[previous presentation](https://github.com/tomit4/linode_nginx_docker) I gave on
setting up a basic Website/App using Docker, NameCheap, and Linode. Please
consult this document prior to proceeding with this tutorial, as it will be
assumed you already have familiarity with this setup.

---

### Initial Installation

Firstly, just log into your VPS via SSH. Once there establish a folder where you
will house your docker-compose.yml and the main Forgejo repos. I just dumped
this in my home folder like a slob, but it's probable a cleaner organization
might be in `/usr/local` or `~/.local` or somewhere like that.

Anyways:

```sh
mkdir forgejo && cd forgejo
```

Within this folder use the default `docker-compose.yml` you can find on
[Forgejo's Docker Installation Page](https://forgejo.org/docs/latest/admin/installation/docker/)

```yml
networks:
  forgejo:
    external: false

services:
  server:
    image: codeberg.org/forgejo/forgejo:11
    container_name: forgejo
    environment:
      - USER_UID=1000
      - USER_GID=1000
    restart: always
    networks:
      - forgejo
    volumes:
      - ./forgejo:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - "3000:3000"
      - "222:22"
```

You can change the ports if you like. The `USER_UID=1000` and `USER_GID=1000`
stay the same as they are environment variables for your main `$USER` of your
VPS. Just know that this user cannot be Root.

You'll also need to create a `git` user on your host VPS. This user just needs
to be able to log in via SSH to your VPS. so:

```sh
sudo useradd git
```

And in the `/etc/ssh/sshd_config` file append the `git` user to the list of
users allowed to ssh in.

```
AllowUsers git
```

Again, if you have other users that need to login, just append the `git` user to
the end with a space (no new line).

Now we can return to our `forgejo` directory and use `docker-compose` to pull in
our image and spin up our container:

```sh
docker-compose up -d
```

Again, it's looking for the `docker-compose.yml` file, so just be sure you're in
the directory with said file in it.

Now you actually should be able to visit the Forgejo repo using your VPS's ip
address, at the port number you exposed (_i.e._ `3000`), and see the initial
instructions:

![slide forgejo_01](./forgejo_01.png)

Don't worry about adjusting any of the configurations, we're not going to be
using Forgejo for anything but a personal repo where we are the sole user.

Just navigate to the bottom and create an admin user. In the case of this
documentation, this will be the only user of our Forgejo Repos, so just keep
that in mind.

Once done, you should have a basic forgejo installation.

We're going to get to setting up SSL certs and reverse proxying through NGINX in
a bit, but let's first setup the ability to setup pushing code via SSH.

First go to your profile icon in the top right-hand side and go to Settings >
SSH/GPG keys. You can find how to create ssh keys
[here](https://docs.codeberg.org/security/ssh-key/). Once you have copied and
pasted the keys in. You're going to want to be sure your `git` user on your VPS
. Simply invoke:

```sh
cd /home/git && mkdir .ssh && touch authorized_keys
```

In `authorized_keys` paste in your ssh `.pub` hash. _Make sure_ it's the `.pub`
hash. Do **not** paste in your private keys.

Now we should be able to push code to our repos using ssh rather than http.

That said, we would have to use our raw ip address for all of this at this
point. Test all this out first before proceeding. Create a few repos, push using
ssh and http. Make sure everything works.

### Setting Up SSL and Reverse Proxying Through NGINX

This is very similar to the process covered in my
[previous presentation](https://github.com/tomit4/linode_nginx_docker), but
basically we're going to use a subdomain of an existing top level domain I have
in order to setup SSL certs using LetsEncrypt via `certbot`.

First we'll need to navigate to our Linode Networks Dashboard and add the `git`
subdomain.

Once logged into the Linode dashboard, just find your tld domain and append a
A/AAAA record that says:

```
git.mytld.dev
```

Or whatever your TLD name is just prepended with "git."

Once that is done, it might take 24 hours (but more likely will be
instantaneous) for the DNS records to propagate. You can check if their ready
using

```sh
dig git.mytld.dev
```

If the records are there, you'll see the proper output you'd expect from `dig`.

Next is to use `certbot` to generate the SSL certs. Since we're using NGINX as a
reverse proxy, we can just generate them with `cerbot` like so:

```sh
sudo certbot --nginx -d git.mytld.dev
```

You can always append `--dry-run` at the end of the command to see if it will
work first (recommended).

Once the SSL certs are generated and the NGINX configuration is appended.
Navigate to your nginx config. In my case this lives in:

```
/etc/nginx/sites-enabled/default
```

Here you will find the generated NGINX config. You'll need to edit it to reverse
proxy to the docker containing forgejo. Here we can use the recommended
[Forgejo NGINX config](https://forgejo.org/docs/latest/admin/setup/reverse-proxy/#nginx):

```
server {
    listen 80; # Listen on IPv4 port 80
    listen [::]:80; # Listen on IPv6 port 80

    server_name git.example.com; # Change this to the server domain name.

    location / {
        proxy_pass http://127.0.0.1:3000; # Port 3000 is the default Forgejo port

        proxy_set_header Connection $http_connection;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        client_max_body_size 512M;
    }
}
```

The main point of interest is everything in the `location` block. Certbot should
have generated the rest.

Once this is pasted in you can restart NGINX:

```sh
systemctl restart nginx
```

And now you can visit your `git.mytld.dev` site and it hopefully will work!

---

### Addressing ROOT_URL issue

Once you login though, you'll notice an error that caused me quite some
frustration. Basically you'll likely see an error regarding the fact that
Forgejo was setup using your VPS's IP address and that it makes no guarantees
about the quality due to the mismatch of what it perceives as a different TLD
being used. We need to change this.

Now, Forgejo's docs talk about an `app.ini` and anyone who has used Gitea in the
past will be familiar with this, but i t took me many hours to realize the
`app.ini` was not where the documentation as of version LTS(v11.0.3) is
incorrect about where this file lives. It took me embarrassingly long to realize
the generated `app.ini` file resides in the `gitea` directory, and not at the
directory where the docs say it is. So from the `forgejo` directory on your host
machine VPS:

```sh
cd data/gitea/conf
```

And here you will find the `app.ini`. You'll need to change a few things, change
the following fields using your editor of choice:

```sh
[server]
DOMAIN = git.mytld.dev
SSH_DOMAIN = git.mytld.dev:222
ROOT_URL = https://git.mytld.dev
```

Just restart the docker container:

```sh
docker container restart forgejo
```

And This will rid you of the annoying warning message on login and also make
sure the proper ssh address is provided when opting to create a repository
through which you will mainly be pushing changes via ssh.

---

## A word on backing up your Forgejo

Eventually you'll want to backup your Forgejo for various reasons. Firstly just
because it's a good idea to back up pretty much anything. But additionally
eventually your little $5 per month VPS might be too small for all the repos you
could be potentially adding to this.

In order to backup your forgejo, you'll want to use `scp`. Make sure you know
the path to your forgejo (just the path of where you initialized the docker
container) and of course you'll need to know the username and password that can
SSH into your VPS. On your home device, just invoke:

```sh
scp myusername@<my_vps_ip_address>:/path/to/forgejo path/on/myhostmachine
```

And this will copy all the files in your forgejo to your home machine for you to
have as a backup.

---

### Conclusion

And that's it! My apologies if this document feels a bit off the cuff, but as I
mentioned at the beginning this document is mainly for my own future reference.
If you have any desire to reach out to me though regarding this or any other
tech related topic, please feel free to do so via my
[email](brianhayes.dev@protonmail.com).