Running Gitea locally

Goals

Operating a local Gitea server (GIT) is actually quite simple and quite sufficient for local or private use.
Once this part is completed, a full Gitea server can be accessed on the local network.

NEW: For the very impatient I have a console only section. There are only commands, no explanations.

This simplest expansion stage of the first part is NOT suitable for public operation!
Access is not (yet) via an encrypted connection. Transport encryption is deliberately not done locally, because GIT reacts very allergic to self-signed or self-made certificates. This works in a pinch, but is cumbersome.

Last updated:

  • 03.03.2024: Minor adjustments
  • 05.02.2024: Console only part added
  • 05.01.2024: config directory migrated to data, only one external directory required. gitea generate secret as replacement for openssl rand. backup directory added. Minor adjustments
  • 13.08.2023: Save data and configuration optional outside the jail added
  • 29.07.2023: Update for FreeBSD 13.2 and finalisation
  • 20.05.2023: Initial document

Requirements

  • TrueNAS Core or pure FreeBSD server with iocage installed
  • IP address of the GITEA jail is known
  • Host name of the GITEA jail is known (e.g. git.domain.local) and can be reached via internal DNS

In general, such services should be set up in a separate environment. This makes not only the security but also the maintenance much easier. Jails can be backed up relatively easily and only the packages that are absolutely necessary are installed.

Diagram

The setup, including all optional possibilities, looks like this:

                   ┌───────────────────────────────────┐
                   │  TrueNAS        Optional:         │
                   │ ┌────────────┐ ┌────────────────┐ │
                   │ │ jails/git  │ │ jails_data/git │ │
LAN: 0.0.0.0:3000 ─┼─┼─► gitea  ──┼─┼─► data         │ │
                   │ │            │ │   backup       │ │
                   │ └────────────┘ └────────────────┘ │
                   └───────────────────────────────────┘

Create jail

A separate jail is required if further web applications are to be built on Nginx/PHP.
Here we use web as the jail name.

Optional: Data directories

This is more for advanced users who already have some experience.

How certain data directories are stored outside the jail is explained here.
The following directories are required:

└── jails_data
    └── GITEA
        ├── backup # Storage for backups (in the jail: /mnt/backup)
        └── data   # Storage for data (in the jail: /var/db/gitea with id: gitea/211)

Optional: Create User

If the data is to be stored outside the jail, the authorisations must be appropriate and are explained in a separate article. The user and group name: gitea with the ID: 211 is required here.

Set up jail

Login to the jail via SSH: ssh USERNAME@IP or ssh USERNAME@HOSTNAME to gain root rights with su.

Customise package source

Package sources should be customised, see separate article.

Install packages & activate services

Now update the package source with pkg update and install the required packages: pkg install gitea.
Enable services so that they start automatically when the jail is started: service gitea enable.

Create configuration

Gitea actually expects its configuration file to be in the file /usr/local/etc/gitea/conf/app.ini, but this is outside the Gitea data directory /var/db/gitea/. In order to really have everything relevant in one place (and in the backup), we use a trick with symbolic links: ln -sf /var/db/gitea/app.ini /usr/local/etc/gitea/conf/app.ini creates the link to /usr/local/etc/gitea/conf/app.ini.

Compared to the supplied standard configuration, this one has a few changes:

  • Indexer for full text search is enabled (REPO_INDEXER_ENABLED = true)
  • Gravatar is disabled (to prevent unwanted connections to third parties) (DISABLE_GRAVATAR = true)
  • Email notifications etc. remain disabled (ENABLED = false)
  • Version and branding in the footer are hidden (SHOW_FOOTER_BRANDING = false)
  • Access via SSH is disabled and only HTTP/HTTPS remain enabled (DISABLE_SSH = true)
  • Access is not only possible via localhost (HTTP_ADDR = 0.0.0.0)
cat > /usr/local/etc/gitea/conf/app.ini << 'EOF'
APP_NAME = Gitea
RUN_USER = git
RUN_MODE = prod

[database]
DB_TYPE  = sqlite3
HOST     = 127.0.0.1:3306
NAME     = gitea
PASSWD   =
PATH     = /var/db/gitea/gitea.db
USER     = root
SSL_MODE = disable

[indexer]
ISSUE_INDEXER_PATH = /var/db/gitea/indexers/issues.bleve
REPO_INDEXER_ENABLED = true

[log]
ROOT_PATH = /var/log/gitea
MODE      = file
LEVEL     = Info

[mailer]
ENABLED = false

[oauth2]
JWT_SECRET = GITEAJWTSECRET

[picture]
AVATAR_UPLOAD_PATH      = /var/db/gitea/data/avatars
DISABLE_GRAVATAR        = true
ENABLE_FEDERATED_AVATAR = false

[repository]
ROOT = /var/db/gitea/gitea-repositories
SCRIPT_TYPE = sh
DISABLED_REPO_UNITS = repo.packages,repo.releases
DEFAULT_BRANCH = main

[repository.upload]
TEMP_PATH = /var/db/gitea/data/tmp/uploads

[security]
INSTALL_LOCK = true
INTERNAL_TOKEN = GITEAINTERNALTOKEN
SECRET_KEY   = GITEASECRETKEY

[session]
PROVIDER = file
PROVIDER_CONFIG = /var/db/gitea/data/sessions

[server]
DOMAIN       = GITEAHOSTNAME
HTTP_ADDR    = 0.0.0.0
HTTP_PORT    = 3000
ROOT_URL     = http://GITEAHOSTNAME:3000/
DISABLE_SSH  = false
SSH_DOMAIN   = %(DOMAIN)s
SSH_PORT     = 22
DISABLE_SSH  = true
OFFLINE_MODE = false
APP_DATA_PATH = /var/db/gitea/data

[service]
REGISTER_EMAIL_CONFIRM = false
ENABLE_NOTIFY_MAIL     = false
DISABLE_REGISTRATION   = false
ENABLE_CAPTCHA         = false
REQUIRE_SIGNIN_VIEW    = true

[other]
SHOW_FOOTER_BRANDING = false
SHOW_FOOTER_VERSION = false
SHOW_FOOTER_TEMPLATE_LOAD_TIME = false
'EOF'

Subsequently still filled:

  • GITEAHOSTNAME, GITEAINTERNALTOKEN, GITEAJWTSECRET und GITEASECRETKEY
sed -i '' 's/GITEAHOSTNAME/'`hostname -f`'/' /usr/local/etc/gitea/conf/app.ini
sed -i '' 's/GITEAINTERNALTOKEN/'`gitea generate secret INTERNAL_TOKEN`'/' /usr/local/etc/gitea/conf/app.ini
sed -i '' 's/GITEAJWTSECRET/'`gitea generate secret JWT_SECRET`'/' /usr/local/etc/gitea/conf/app.ini
sed -i '' 's/GITEASECRETKEY/'`gitea generate secret SECRET_KEY`'/' /usr/local/etc/gitea/conf/app.ini

Finally, adjust the authorisation of the configuration file with chown git:git /var/db/gitea/app.ini.

Start services

We have now reached the end of the preparations and Gitea is started with service gitea start.

Registration

Now Gitea is called up for the first time and the first user is registered.

To do this, call up the IP or host name of the Gitea jail with your favourite browser:
http://IP:3000 or http://HOSTNAME:3000.

wilkommen

This first user is then automatically also the user with administration rights!
The user must NOT be called admin!

registrieren

admin

After the first admin user has been created, consideration can be given to disabling the stand-alone registration and giving the admin the task of creating new users in the system. To do this, it is sufficient to set the DISABLE_REGISTRATION entry in /var/db/gitea/conf/app.ini from false to true and restart the Gitea service with service gitea restart.

Console

pkg install -y gitea
service gitea enable
fetch https://github.com/marzlberger/bsdbox/blob/main/gitea/app.ini -o /usr/local/etc/gitea/conf/app.ini
sed -i '' 's/GITEAHOSTNAME/'`hostname -f`'/' /usr/local/etc/gitea/conf/app.ini
sed -i '' 's/GITEAINTERNALTOKEN/'`gitea generate secret INTERNAL_TOKEN`'/' /usr/local/etc/gitea/conf/app.ini
sed -i '' 's/GITEAJWTSECRET/'`gitea generate secret JWT_SECRET`'/' /usr/local/etc/gitea/conf/app.ini
sed -i '' 's/GITEASECRETKEY/'`gitea generate secret SECRET_KEY`'/' /usr/local/etc/gitea/conf/app.ini
service gitea start

Voilá