gitengine

A multiuser git server for node.js with HTTPS, SSH, CGIT and LFS.
Gitengine runs a single unix user, thus avoiding file-permission issues in more complicated permission setups.

This is just "the engine", there is no web based management interface bundled.
See https://gitlab.com/csc1/gitengine/-/tree/examples for an example using a single setup script.
More complicated setups a possible with on the fly permission changes, repository additions etc. but not included with gitengine.

Getting started

Install to a node project with
``
npm install gitengine
`

In a node file run
`
const gitengine = require( 'gitengine' );
`
gitengine is currently using CommonJS, ES6 modules not yet done.

Requirements.

node v16.14.2 was used in development.
git and cgit have to be installed.

API documentation

$3

Global gitengine configuration is done with gitengine.config( ) call.
An arbitrary number of arguments can be specified starting by a configuration option and a number options specific to that configuration.

Configuration arguments are:

- `'httpPort' [number]`
Sets the http port to listen to (it will only forward traffic to https).
Set 'false' to disable.
default: 80

- `'httpsPort' [number],`
Sets the https port to listen to.
Set false to disable.
default: 443

- `'ip' [string]`
Sets the IP to listen to.
default: '0.0.0.0'

- `'ips' [ [string], [string], .. ]`
Sets multiple IPs to listen to.
default: [ '0.0.0.0' ]

- `'lfsCatalogDir' [string]`
Sets the LFS catalog dir (leveldb).
default: disabled

- `'lfsObjectsDir' [string]`
Sets the LFS objects dir.
default: disabled

- `'receiveCallBack' [function]`
Calls this function after git-receive (where actual commits have been transferred)
If used "git-receive-plug" from ccode needs to be placed in /usr/local/bin/ and
`/var/run/gitengine` must be created and accessible to gitengine.
default: disable

- `sshHostKeys' [ [sshHostKey] [sshHostKey] ]`
Sets host ssh key(s).
default: none. Needs to be provided. (suggested reading in your keys in /etc/ssh/ and make them available to gitengine)

- `'sshPort' [number],`
Sets the ssh port to listen to.
default: 22

- `'sslCertFile' [string],`
Path to SSL cert file.
default: none. Needs to be provided.
Generate a https self signed key like this:
`openssl req -newkey rsa:4096 -x509 -sha256 -days 3650 -nodes -out host.crt -keyout host.key`
Or use a real one.

- `'sslKeyFile' [string],`
Path to SSL key file.
See sslCertFile.

$3

Adds an user to gitengine.

Arguments are:

- `'group' [string]`
Adds the user to this group.

- `'password' [string]`
Adds a plain password for this user.

- `'passhash' ['ldap'/'shadow'] [string]`
Adds a ldap/shadow hashed password for this user.
You can create shadow hashes with `openssl passwd -6`.
Only type 6 for shadow and {SSHA} password from LDAP are supported.

- `'sshKey' [passlock:SshKey]`
Adds a ssh key for this user.

- `'username' [string]`
Username of the user.
Required.

Obviously you want at least either a password or a ssh key for every user.

#### gitengine.addRepository( )

Adds a repository.

Arguments are:

- `'couplingBranch' [STRING]`
Branch to couple ( empty, '' or undefined is "master").

- `'couplingDir' [STRING]'`
The dir to couple ( empty, '' or undefined is whole repository).

- `'couplingUrl' [STRING]'`
The url to couple to.

- `'description' [STRING]`
Description of the repository (shown in CGIT).

- `'group' [STRING] ["r" or "rw"]`
Adds a groups permission to this repository (read only or read/write).

- `'name' [STRING]`
Unique name of the repository (handle for gitengine).
Required.

- `'overleafBranch' [STRING]`
Currently not implemented.

- `'overleafDir' [STRING]`
Currently not implemented.

- `'overleafCeProjectId' [STRING]`
Project Id from the Overleaf CE/Pro server to sync with.

- `'path' [STRING]`
Path of the repository on local filesystem.
Required.

- `'user' [STRING]`
Adds a user permission to this repository (read only or read/write).

$3

Adds sync capabilities to an Overleaf CE or PrO server.
`syncDir`` is any directory used as scratch pad for syncing operations.

$3

Creates missing git repositories on disk.

$3

Removes the repository from gitengine with the 'name' handle.
It will not be deleted from disk!

$3

Removes that user.

$3

Returns immutable data of all repositories handled by gitengine.

$3

Returns immutable data of all repositories handled by gitengine.

$3

Reads in info of all branchse of all repositories.
This is not actually cared for by gitengine, but made available via the repositories( ) call
for an application caring about that.

$3

Starts the gitengine. Most calls to gitEngine.config( ) will have no effect after this.
Altough repositories and users can still be added or removed.

Example

See https://gitlab.com/csc1/gitengine/-/tree/examples for an example using a single setup script.