How to Containerize Ungit into an OCI Image

The XKCD comic 1597^[1] describes the state of Git for the majority of home lab enthusiasts.

This article describes a simple approach for building an image & deploying Ungit as a self-hosted web app.

What is Ungit?

As eloquently summarized by its developer, Ungit is...

The easiest way to use git. On any platform. Anywhere.^[2]

Ungit's mission is to provide a GUI and simplify Git usage - both the day-to-day routine operations, as well as the advanced one-off operations.

Motivation to Containerize Ungit

The approach used in engineering Ungit is to deploy it as a locally used application on the same device as the user is on, to run in parallel to a coding IDE, with the local clone of the Git repository available to Ungit.

This can be challenging if the user doesn't have access to their working IDE.

Approach Used for Containerizing Ungit

Since Ungit is a Node application, which also runs Git commands in the backend, the following approach has been used:

1. Start with an Alpine-based Nodejs image
2. Install Git, GPG & GPG-Agent from using Alpine's built-in package manager (apk)
3. Install Ungit using NPM
4. Expose Ungit's operating port (8448)
5. Switch to the working directory - assumed to be /var/local/ungit/

OCI Image Build

You can build it yourself if you wish. Here's the Dockerfile

  FROM node:22.18.0-alpine3.22
  RUN apk add --no-cache git gpg gpg-agent && rm -vrf /var/cache/apk/*
  RUN  npm install ungit@latest -g && npm cache clean --force
  EXPOSE 8448
  WORKDIR /var/local/ungit

Ungit's launch command has been deliberately left out of the image to allow tweaking the startup command by the user.

This image is available at Cerebral Voyage's Gitlab repository at https://gitlab.com/cerebral.voyage/ungit-docker.

Suggested IDE

Ideally, the user can launch a VS Code Server image, running as the same user, and use the same directory where the code rests to have an IDE + Git client. You can go one step further by having an instance of Caddy using the code repo as the HTML directory, also running as the same user.

Deployment

To deploy the container as a stack, the following requirements must be met:

1. The user who owns the code repositories must be running the container.
2. The home directory of the user must be mapped to /home/node/ in the container. The environment variable HOME must be overriden with this path, since the running user may not exist inside the container.
3. Ungit's bind IP must be set to 0.0.0.0 as part of the launch command to ensure that it can be accessed from outside the container.

Here's a sample Docker Compose file

name: "ungit"


services:

  main:

    container_name: "Ungit"
    restart: "unless-stopped"

    deploy:
      resources:
        limits:
          cpus: "0.25"
          memory: "256m"

    user: "${UID}:${GID}"

    healthcheck:
      test: "/usr/bin/wget --no-verbose --quiet --tries=1 --spider http://localhost:8448 || exit 1"
      interval: "60s"
      timeout: "10s"
      start_period: "20s"
      retries: 3

    networks:
      net_app:
        ipv4_address: "172.22.100.2"
    hostname: "ungit"
    extra_hosts:
      - "dockerhost:172.22.100.1"
    # ports:
    #   - target: 8448
    #     host_ip: "0.0.0.0"
    #     published: 8448
    #     protocol: "tcp"
    #     mode: "host"

    volumes:
      - type: "bind"
        source: "/etc/localtime"
        target: "/etc/localtime"
        read_only: true
      - type: "bind"
        source: "/home/username"
        target: "/home/node"
        read_only: false
      - type: "bind"
        source: "/var/local/CodeRepo/Data"
        target: "/var/local/ungit"
        read_only: false

    environment:
      TZ: "Europe/London"
      HOME: "/home/node"

    image: "registry.gitlab.com/cerebral.voyage/ungit-docker:1.5.28-10"

    command:
      - "ungit"
      - "--logLevel=warn" # "none" < "error" < "warn" < "info" < "verbose" < "debug" < "silly"
      - "--ungitBindIp=0.0.0.0"
      - "--forcedLaunchPath=\"/var/local/ungit\""
      - "--no-launchBrowser"
      - "--no-bugTracking"
      - "--no-autoFetch"
      - "--tabSize=2"


networks:
  net_app:
    name: "Ungit_net"
    driver: "bridge"
    ipam:
      driver: "default"
      config:
        - subnet: "172.22.100.0/24"

Then serve this via a reverse proxy or expose the ports (uncomment above) for direct use. Remember to apply the appropriate authentication. I use Authelia.

References

1. https://nodejs.org/en/docs/guides/nodejs-docker-webapp
2. https://dockerlabs.collabnix.com/beginners/dockerfile/lab1_dockerfile_git.html
3. https://stackoverflow.com/a/49119046
4. https://coder-coder.com/npm-clear-cache/
5. https://github.com/FredrikNoren/ungit/blob/master/source/config.js
6. https://github.com/nodejs/docker-node/blob/main/docs/BestPractices.md#non-root-user

Feature image © Cerebral Voyage; generated by Microsoft Copilot