Forgejo in a nutshell

flamenco_687 · August 4, 2023, 3:18pm

I assume you’ve heard of GitHub, you probably even use it for your projects. However, I bet you haven’t heard of GitLab… Gitea…? Forgejo!?

GitHub is cool because it’s too many things in one:

Web-based code hosting: Save all your work to the clooooud, clone it and fetch your latest code from anywhere and at anytime.
Social network: Yeah, you’ve heared it right. Believe it or not, people connect, discuss, support and just have a good time working together in this amazing place, not just developers!
Code management: GitHub uses Git, and you don’t need any cool interface for Git, just a terminal. But we don’t like terminals, they’re ugly! Issues, pull requests, projects, wikis, actions… thanks to code management.

How do they do it, for free? Well, if you’ve used GitHub enough or depending on your needs, you may have found about limitations for free accounts, prompting you to buy a paid plan. That makes sense and I’m not going to look for a suspicious-looking page just to get a “free paid plan”, I’m going to look for alternatives.

GitHub has some competitors (GitLab, Bitbucket), but you’ll most likely find more or less the same there. Forgejo comes to change the game! Code hosting and code management are not exclusive to webs, you could run your own local instance, just like having a “tiny GitHub” on your computer.

1. Why?

There are a number of reasons why you’d want to host your own instance, some already mentioned:

No limits: Free service providers are free up to a point in which sustaining your code becomes pricey and thus, they have to apply a limit by making you pay for extra capabilities or features. It’s completely understandable, however, if we all have a computer capable of handling it, why not sustain this code ourselves?
In control: These services have a ToS determining what you can and not do. You might not agree with them or probably you’d like to do something else than what it tells you to. Do whatever you want with a local instance.
Privacy: Privacy is a rising topic nowadays, us as developers should know this more than no one. Most big platform’s privacy statements are not bad, although they still collect some data (some essential, some other not). 0 data collection is always better than some data collection. If you host your service, who’s going to collect the data, you? Exactly, no one.
Free software: GitHub and BitBucket are proprietary; that’s not necessarily bad but can lead to bad situations in the distant future. Forgejo is licensed under MIT and completely community-owned, thus remaining free for eternity.

Why Forgejo and not…

Gitea? Gitea has been the most popular tool for forging git instances, forked from Gogs, it is indeed the predecessor tool to Forgejo.

Sadly, in October 2022, Gitea was acquired by a for-profit organization. A lack of transparency mixed with this sudden change without permission of the community made Gitea’s walls crumble. Since Gitea is built on top of the community, this led to contributors leaving the project and Forgejo being created, a soft-fork backed by a non-profit organization called Codeberg e.V. sustained by a community model.

2. Warming up

This guide covers some complicated topics (containers, hosting, OS). I don’t fully understand these myself, but we’re going to get our basic instance up and running together! Follow each step closely.

Linux: Forgejo is built just for Linux, meaning only Linux users can directly run it. If you’re a Linux user I encourage you to follow this other official installation guide. You may still go through the rest of the sections if you desire.
Windows/MacOS: We still have a chance! Docker is a popular tool that allows developers to create images, these are templates that come with all the needs for running an app. These apps get ran in containers, which are processes isolated from the environment. Now you can use Docker to run something in Linux, isolated from your actual OS.

To make the task easier, you can keep a docker compose file in your directory to always be able to simply run compose and get the instance running.

Getting Forgejo with Docker

Install Docker Desktop.
Create a new directory to host your instance. Call it what you want, I call mine Forgejo.

New directory for setting up Forgejo

Paste this docker-compose.yml file in your directory.

version: '3'

networks:
  forgejo:
    external: false

services:
  server:
    image: codeberg.org/forgejo/forgejo:1.20
    container_name: forgejo
    restart: always
    networks:
      - forgejo
    volumes:
      - ./forgejo:/data
      - /etc/timezone:/etc/timezone:ro
      - /etc/localtime:/etc/localtime:ro
    ports:
      - '3000:3000'
      - '222:22'

Open your directory in a terminal. You can use VSCode Terminal, Windows Terminal, macOS Terminal, cmd…

How to open the directory in Windows Terminal

Run docker compose up and wait for the container to be created.

If you’ve read the terminal, you may have noticed this one message:

And that’s exactly what you should be doing now, prepare for actually installing Forgejo!

3. Ready... Steady... Go!

Your Forgejo instance is now being hosted locally in your network under the port 3000. This means you can access it as a normal website! Type in your search bar localhost:3000.

What your search bar shoud look like

The site will welcome you with an installation page that you must fulfill to your needs so that Forgejo can actually start running. The default General Settings are fine and you shouldn’t modify them except if you want to customize your instance, we’ll get to that in the next section.

You should adjust Server and Third-Party Service Settings to your needs based on if you’re going to host your instance for other collaborators to use or just for yourself. If you’re running the instance for yourself I recommend applying these settings.

Finally, I highly recommend creating an Administrator Account as the first user (which will be yours), ensuring you’ll always be able to log in your site and manage it.

Note on databases

Forgejo’s default install uses SQLite as database to store instance data. SQLite requires no extra setup and works smoothly for a small amount of traffic, so I recommend not changing it for a basic setup.

More powerful databases can be configured to be used though that’s not covered by this guide.

Now simply click that gorgeous lookin’ install button! The installation process may take up to a minute. It might seem like nothing is happening but just go and check your console and you’ll see how much your container is working.

4. Reaching the goal

You’ve done it! Forgejo’s interface is self-explanatory and similar to GitHub or GitLab. In case you feel lost trying to find a feature, check the official user guide. You can also migrate existing projects from external platforms to your local instance to make everything feel the same.

How to configure?

Now, things can get very complicated as I’ve mentioned. You’ve set up a basic instance, however there are many settings to be configured for the site. Installing Forgejo has created a forgejo directory inside your main directory.

The directory Forgejo has installed

Inside forgejo you’ll find all your instance’s data. To configure Forgejo, look for this file: forgejo/gitea/conf/app.ini. Once found, open it with your favorite editor and start configuring!

What to configure?

This official Configuration Cheat Sheet showcases all the possible settings and how they affect Forgejo. There are also some other sections of the documentation which showcase recommended settings.

How to apply configuration?

Since it is an .ini file (stands for initialization), your configuration will only get applied on restart.

How to restart? When you ran docker compose up, the docker image and the generated container were added to your Docker Desktop app! You can look for your container there and restart it.

Note that you can also shutdown your container as well as the docker engine, you can start these later. Deleting the container works the same as shutdowning, since your data is stored in the forgejo directory, you can create a new container later and still keep everything.

5. The big picture

That was a quick race, wasn’t it? Setting up a basic Forgejo instance is easy and fast. Forgejo is built with complexity in mind, so bigger instances are still relatively easy to configure. Though, quality and privacy are at reach for everybody, but the path won’t always be smooth.

Self-hosting comes with some big disadvantages that we shouldn’t oversee:

It runs on your hardware: Cloud services are called like so because you can seemingly use them from anywhere, this is not true for a local instance being hosted in your computer, which depends on your computer.

This makes it so that you will always have to be running the container in case you want to access your instance, which also means all the work done on the instance is workload for your computer, something bad if you want to do other tasks meanwhile.

This doesn’t mean you can’t save your code to the cloud! I run my Forgejo instance and sync it with my Filen drive using their desktop app. You can do this too with other clouds like Mega, Nextcloud…
Lack of social aspect: As mentioned at the beggining, GitHub acts as a social network for both developers and conventional users. This is one of the good things about their community, almost anyone you talk too will have a GitHub and you can collaborate, discuss, report issues…

Running your own Forgejo instance means… having no community (except if you decide to host a public instance). Keep in mind, this isn’t necessarily a problem for closed-source projects like games and if you want to benefit from the community when working on something open-source, go back to GitHub or check Codeberg.

Codeberg is a public non-profit Forgejo instance hosted by the actual maintainers of the tool. They’re compromised with free software and provide their services with no pay walls other than a single limitaiton: only accepting open-source projects in their instance. That shouldn’t be a problem if you want to work on open-source, right?
Not the best features: Who’s gonna have more features, a multi-billionaire company with the biggest user base or a little community project used by almost 50.000 users… Of course GitHub. They have Copilot, Actions, Pages and more than Forgejo… sort of has.

Forgejo experimental built-in actions are work in progress.
Forgejo hasn’t got a free pages provider.
Forgejo isn’t the owner of any AI assistant.

But that doesn’t make it worse! Instead, it allows for you to keep building new things that maybe one day will surpass the giants. Blender is a good example of this being possible.
Simply not GitHub: If your work mates are on GitHub, you should be too. Most jobs look for GitHub expertise. The most part of the community is in GitHub. Some tools are only compatible with GitHub…

This doesn’t mean you shouldn’t risk it for Forgejo and Codeberg, indeed, if you’re not into any project, tied to a dependency or hired by someone with the need of it, consider giving them a try. I’m already part of their community and I would love to see more Roblox content on the platform.

I’ve tried to make this guide easy and clear to follow. I’m not a techy guy, just a game programmer, so it wasn’t easy for me to figure out all these things without prior examples from the “Windows community of Forgejo”.

If you’ve liked the idea of trying out Codeberg, let me hear it out on my profile.

DISCLAIMER

Libre Software

The posture I have throughout this guide on proprietary and for-profit software is my personal one and by any means implies that the mentioned platforms/services are bad, dangerous or useless. That’s why I actually mention the disadvantages of alternatives, which I am aware of.

This guide aims to spread knowledge on libre software as well as provide a nice set of tools to level up the development process which actually have proven to be useful to me.