Code Hosting Platform

Disclaimer: This translated content is generated by a large language model.

GitHub, as the most popular code management platform currently, is essentially the only platform for individual developers and small teams to manage their code. This article is the first part of a series, aiming to introduce using forgejo as an alternative to GitHub to achieve simple code management functions. The next article plans to introduce using Crow CI as a CI/CD tool to replace GitHub Actions, while GitHub Codespaces or Copilot will not be additionally introduced. The former has devcontainer or other local development environment configurations, and the latter has other AI assistant tools like Claude Code or Codex as alternatives.

 

Deployment Selection

After configuring a lightweight Git repository, I started looking for a platform that could replace GitHub to handle more development workflows and code management. Compared to full compatibility with GitHub, I value long-term open-source governance, lightweight deployment and maintenance, and self-hosted sovereignty. Initially, I also wanted to try Gitea, but after reading the open letter from developers and community members when Gitea was controlled by a commercial entity, I chose Forgejo.

Forgejo does not differ much from Gitea or GitHub in terms of general code management. For the general development projects I currently handle, there isn't much difference in aspects like issues, pull requests, wikis, etc. A major difference lies in GitHub Actions, which is also the focus of the next article on CI/CD tools, so I won't introduce it too much here.

Initially, I deployed forgejo on Zeabur. At the time, this provider offered a $5 free credit per month, which could be used to host Docker images. Therefore, the entire project was a service in a container: all repositories and large files were kept in the image, and the database used a simple SQLite3. Until May, when the company simply and directly discontinued its free service, I urgently packed up the entire data folder before the server shut down and started migrating to my own cloud server. Since a PostgreSQL container was already running on my server, this migration also required migrating data from SQLite3 to PostgreSQL.

The new deployment task is very simple, divided into the following steps:

1. Verify the migrated data locally.
2. In the local container, use forgejo --database postgres --type zstd --file postgres_db.tar.zst to save the database file in Postgres format. At the same time, upload the remaining data files.
3. Decompress the migrated data on the remote side, create a new database user and database, and import the data files into the container.

# Create a docker network for forgejo communication
docker network create forgejo

# Log into the container
sudo docker compose exec psql_db psql -U postgres

# Perform operations in the PG container
CREATE ROLE forgejo WITH LOGIN PASSWORD '[redacted]';
CREATE DATABASE forgejo OWNER forgejo;
q

# Test the result of creating the user
sudo docker compose exec psql_db psql -U forgejo -d forgejo

# Import the sql file into the container
cat forgejo-db.sql | sudo docker run --rm -i \
  --network forgejo \
  -e PGPASSWORD="[redacted]" \
  postgres:latest \
  psql -h psql_db -U forgejo -d forgejo

4. After verifying that the database import is normal, upload the remaining data files to the folder, and modify the database connection configuration in the app.ini file.

[database]
DB_TYPE = postgres
HOST = psql_db:5432
NAME = forgejo
USER = forgejo
PASSWD = [redacted]
SSL_MODE = disable

5. Finally, configure the compose file and spin up the container in one go.

networks:
  forgejo:
    external: true

services:
  forgejo:
    image: codeberg.org/forgejo/forgejo:15
    container_name: forgejo
    environment:
      USER_UID: 1000
      USER_GID: 1000
      TZ: America/New_York
    restart: always
    networks:
      - forgejo # Network used to connect to the external PG server
    volumes:
      - ./data:/data # Data files
    ports:
      - '3000:3000'
      # - '2222:22' Git's SSH protocol port, disabled in this instance

After migration, everything is normal. All old configurations are in effect, and Git repositories and user data are fully preserved. The forgejo container consumes about 150 MB of memory when running, while PostgreSQL consumes about 100 MB. This is more than enough for my current server, and I no more have to worry about my database being deleted by providers like Zeabur again.

Configuration and Migration Experiences

This series of tools emphasizes self-control, free combination, and lightweight deployment. For individuals or small teams who care about data and the free software ecosystem and are willing to perform simple maintenance, this is an excellent choice. Although the SSH-based lightweight Git repository I developed earlier provided some ideas, in actual deployment, I found that an SSH-protocol Git server is not that easy to configure, especially since many cloud platforms are troublesome to handle persistent SSH private keys and repository data. An SSH lightweight repository looks more like something that could be made into a worker container like Google Run, which writes content to mounted storage upon receiving a Git request. In comparison, Forgejo still provides a more complete code management workflow and a more intuitive way to manage code.

Technical Features

One of Forgejo's great features is the ability to mix and match different configurations. For the database, you can choose SQLite3, PostgreSQL, or MariaDB (MySQL). For large files, you can choose remote storage such as S3/MinIO, or local storage. Even Git Over SSH allows you to choose between the built-in SSH server or the system's own SSH server. This also reduces dependency on any single component or service.

Next Steps in Deployment

At present, most configurations can continue to be adjusted, and the project's official website provides detailed configuration documentation. However, for my current personal code platform, I only plan to divide it into three parts: the Forgejo server, the PostgreSQL database, and the Crow CI pipeline. Crow CI will be introduced in the next article. As for the Forgejo-specific configuration, my plan is to gradually add features, including email management and configuring Forgejo Release/Packages. My current thought is still to utilize Cloudflare's low-cost email features (possibly paired with another outbound mail service) and R2 object storage.

In the next part, I will focus on introducing Crow CI, a CI/CD tool. This configuration is aimed at rivaling GitHub Actions. At the same time, I will briefly mention its competitors, share my past misunderstandings in this area, and share the problems I encountered during the configuration process.