iocage-plugin-gitea

An iocage plugin for Gitea, a community managed lightweight code hosting solution written in Go.


CI
License

Table of Contents

Installation
Usage
- Enabling TLS Mode with an SSL Certificate
- Persisting Data
  - Initial Setup
  - Reattaching Data in a New Jail
Configuration
Code of Conduct
Issues
Contributing
Release History
Authors
License

Installation

This plugin can be installed via the fnichol/iocage-plugin-index plugin collection which is not installed on FreeNAS or TrueOS by default. For example, to install the plugin with a name of gitea and a dedicated IP address:

$ jail=gitea
$ ip_addr=10.200.0.110

$ sudo iocage fetch \
  -g https://github.com/fnichol/iocage-plugin-index \
  -P gitea \
  --name $jail \
  ip4_addr="vnet0|$ip_addr"

Usage

Enabling TLS Mode with an SSL Certificate

TLS mode is handled by the nginx service which forwards all traffic back to the Gitea service via a local Unix domain socket. To enable TLS you will need a public SSL certificate (i.e. a cert.pem file) and the private server key (i.e. a key.pem file) installed into the nginx configuration directory of the plugin's jail. Assuming a running installed plugin called gitea with a jail mount point of /mnt/tank/iocage/jails/gitea in the host system, the following will setup Gitea to run under HTTPS:

$ jail=gitea
$ jail_mnt=/mnt/tank/iocage/jails/$jail

$ sudo cp cert.pem key.pem $jail_mnt/root/usr/local/etc/nginx/
$ sudo chown 0644 $jail_mnt/root/usr/local/etc/nginx/cert.pem
$ sudo chown 0600 $jail_mnt/root/usr/local/etc/nginx/key.pem
$ sudo iocage exec $jail plugin config set gitea_nginx_mode https
$ sudo iocage exec $jail plugin services restart

Persisting Data

There are 2 primary directories that contain data in a Gitea jail:

/var/db/gitea All internal state and configuration for Gitea
/usr/local/git All hosted repository data

A good strategy is to create a ZFS dataset per directory and mount them into the jail. This way, the jail can be destroyed and later re-created without losing the Gitea configuration or the repository data itself.

Initial Setup

To set this up for the first time, the ZFS datasets will need to be created and any initial state in the jail will need to be copied onto the datasets.

$ jail=gitea
$ dataset=tank/src/gitea
$ mnt=/mnt/$dataset

# Create the ZFS datasets on the host system
$ sudo zfs create $dataset
$ sudo zfs create $dataset/config
$ sudo zfs create $dataset/repos

# Stop the Gitea service
$ sudo iocage exec $jail service gitea stop

# Mount the ZFS dataset for config data & copy existing data to dataset
$ sudo iocage exec $jail mv /var/db/gitea /var/db/_gitea
$ sudo iocage exec $jail mkdir /var/db/gitea
$ sudo iocage fstab -a $jail "$mnt/config /var/db/gitea nullfs rw 0 0"
$ sudo iocage exec $jail chmod 0750 /var/db/gitea
$ sudo iocage exec $jail chown git:git /var/db/gitea
$ sudo iocage exec $jail sh -c \
  'tar cf - -C /var/db/_gitea . | tar xpf - -C /var/db/gitea'
$ sudo iocage exec $jail rm -rf /var/db/_gitea

# Mount the ZFS dataset for repos data & copy existing data to dataset
$ sudo iocage exec $jail mv /usr/local/git /usr/local/_git
$ sudo iocage exec $jail mkdir /usr/local/git
$ sudo iocage fstab -a $jail "$mnt/repos /usr/local/git nullfs rw 0 0"
$ sudo iocage exec $jail chmod 0755 /usr/local/git
$ sudo iocage exec $jail chown git:git /usr/local/git
$ sudo iocage exec $jail sh -c \
  'tar cf - -C /usr/local/_git . | tar xpf - -C /usr/local/git'
$ sudo iocage exec $jail rm -rf /usr/local/_git

# Start the Gitea service
$ sudo iocage exec $jail service gitea start

Reattaching Data in a New Jail

If you are setting up a fresh new plugin instance and want to re-use the configuration and repository data from a prior instance, then you can re-attach the existing datasets into the new instance.

$ jail=gitea_2
$ dataset=tank/src/gitea
$ mnt=/mnt/$dataset

# Stop the Gitea service
$ sudo iocage exec $jail service gitea stop

# Reattach the existing ZFS dataset with the config data
$ sudo iocage exec $jail rm -rf /var/db/gitea
$ sudo iocage exec $jail mkdir /var/db/gitea
$ sudo iocage fstab -a $jail "$mnt/config /var/db/gitea nullfs rw 0 0"

# Reattach the existing ZFS dataset with the repos data
$ sudo iocage exec $jail rm -rf /usr/local/git
$ sudo iocage exec $jail mkdir /usr/local/git
$ sudo iocage fstab -a $jail "$mnt/repos /usr/local/git nullfs rw 0 0"

# Start the Gitea service
$ sudo iocage exec $jail service gitea start

Configuration

User Serviceable Configuration

The following configuration is intended to be modified by a plugin user.