Ungit Deployment and Usage Guide

1. Prerequisites

Node.js: Version 20.19.0 or higher
npm: Version 10.8.2 or higher (typically included with Node.js)
Git: Version 2.34.x or higher
System access: For global npm installation, you may need root/sudo access (use sudo -H on Unix-like systems)

2. Installation

From npm (Recommended)

npm install -g ungit

If your system requires elevated privileges for global npm packages:

sudo -H npm install -g ungit

From Source (Development)

git clone https://github.com/FredrikNoren/ungit.git
cd ungit
npm install
npm start  # or use the command defined in package.json scripts

Prebuilt Electron App

Download the latest release from GitHub Releases. Note: Git must still be installed separately on your system.

3. Configuration

Configuration File

Create a .ungitrc file in your home directory:

Linux/macOS: ~/.ungitrc
Windows: C:\Users\USERNAME\.ungitrc

The file must be valid JSON. Example:

{
  "port": 8080,
  "bugtracking": true,
  "authentication": true,
  "users": {
    "admin": "password123"
  }
}

Command Line Arguments

Override configuration at launch:

ungit --port=8080 --no-autoFetch

Disable boolean features with --no- prefix:

ungit --no-launchBrowser

Key Configuration Options

From source/config.js:

port: Server port (default: 8448)
urlBase: Base URL (default: http://localhost)
authentication: Enable auth (default: false)
users: Username/password map when auth enabled
autoFetch: Auto-fetch from remotes (default: true)
maxConcurrentGitOperations: Limit parallel git operations (default: 4)
logGitCommands: Log executed git commands (default: false)
logGitOutput: Log git command output (default: false)
launchBrowser: Open browser on start (default: true)
dev: Development mode (default: false)

PGP Signing

Ungit supports commit signing but does not handle GPG passphrase prompts. Configure git for signing:

git config --global commit.gpgsign true

Or add to .ungitrc:

{
  "isForceGPGSign": true
}

Required setup: Configure password-less GPG authentication via gpg-agent or OS keychain integration.

External Merge Tools

Configure custom merge tools (Kaleidoscope, p4merge, etc.) by setting the mergeTool configuration option. See MERGETOOL.md for detailed setup.

4. Build & Run

Production Run

ungit

This starts the server and opens your default browser to http://localhost:8448 by default.

Run without opening browser:

ungit --launchBrowser=false

Development Run

After cloning and installing dependencies:

npm start

The dev configuration option enables development mode (hot-reloading, verbose logging). Set via:

ungit --dev=true

or in .ungitrc.

5. Deployment

General Deployment

Ungit is a Node.js web application. Deploy on any server with Node.js and Git installed.

Steps:

Install Node.js and Git on the server
Install ungit globally (npm install -g ungit) or clone repository
Configure .ungitrc for production (set port, enable authentication if needed)
Open firewall for port 8448 (or your configured port)
Start ungit as a background service

Reverse Proxy Setup (nginx)

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:8448;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}

Systemd Service (Linux)

Create /etc/systemd/system/ungit.service:

[Unit]
Description=Ungit Git UI
After=network.target

[Service]
Type=simple
User=youruser
WorkingDirectory=/home/youruser
ExecStart=/usr/bin/ungit --port=8448
Restart=on-failure

[Install]
WantedBy=multi-user.target

Enable and start:

sudo system

How to Deploy & Use FredrikNoren/ungit