Wen Ping

Posted on Oct 29 Originally published at anguskit.com

How to install Git on an intranet: accept it with clone and a pull request

#angusgit

This article explains how to confirm that a team can really use AngusGit after it is installed on an intranet. After reading it, you can finish the install wizard on one Linux machine, then accept the install in four steps: create a repository, clone over SSH, push a branch, and merge a pull request. A pull request is the page where someone asks to merge one branch into another. Colleagues can review the changes there and merge after they confirm.

The SSH check needs a public key first. If this machine does not yet have ~/.ssh/id_ed25519.pub, run ssh-keygen -t ed25519 -C "you@example.com", press Enter for the path, then run cat ~/.ssh/id_ed25519.pub and copy the whole line that starts with ssh-ed25519. After you sign in to AngusGit, open Profile → SSH Keys in the sidebar, click Add SSH Key, set a title, paste that line, and click Add Key. The username in the address is always git, and the port is 2222. To use HTTPS instead, open Profile → Access Tokens, click Generate New Token, enter your current login password, select git:write, set the repository permission to WRITE, and copy the token immediately. On push, the username is your sign-in name and the password is this token.

The private install package for AngusGit includes an interactive wizard. On one intranet Linux server you select a few items, fill in a few items, and the install finishes. The wizard asks you to choose the install method, how people reach the service, and the database. Day to day, back up the database and the repository directory together. The example below is Community (at most 10 users). Team and Enterprise use the same install steps, and they also need a license file.

1. Before you install

Machine: If this server runs only AngusGit and the user center it depends on, GM (the service for accounts, sign-in, and team management), 2 CPU cores and 4 GB of memory are enough. When there are many repositories and many people using it at once, use 4 cores and 8 GB. Start the disk at 80 GB. Repository files keep growing, so put them on a separate SSD.

Software: Install Docker and Docker Compose on the server first. The install wizard uses them to start the services. You do not need to prepare a database yourself. The wizard can start a MySQL 8 along with the install.

Domain name: A subdomain is the recommended way in. Prepare a root domain first, for example example.com. After install you will use the two subdomains gm.example.com and git.example.com, so point both of them at this server in the intranet DNS. For a first try you can skip DNS and add one line to the hosts file on your own computer:

192.168.1.20 gm.example.com git.example.com

Replace 192.168.1.20 in that line with the server’s intranet IP.

Ports: The browser uses port 80, or port 443 when a certificate is configured. Developers push and pull over SSH on port 2222. AngusGit puts SSH on port 2222 by default, away from port 22, which the server’s own SSH service usually uses. Clone addresses later in this article therefore include port 2222. Open the browser port and port 2222 on the firewall.

2. Download and run the install wizard

curl -LO https://repo.anguskit.com/raw/raw-public/AngusKit/git/AngusGit-Community-1.0.0.zip
unzip AngusGit-Community-1.0.0.zip
cd AngusGit-1.0.0
./install.sh

The package is about 310 MB. If the server cannot reach the internet, download it on a machine that can, then copy it to the server. A fully offline environment also needs the Docker images imported ahead of time. The offline install document at the end explains that.

Run ./install.sh as a normal user. Do not add sudo. If a previous run used sudo, the wizard asks you to change the directory owner back to the current user first.

The wizard asks questions in order. The table is the recommended set of answers. A few items are explained after the table:

Wizard prompt	Recommended answer	Note
`Install mode`	`1` (Docker Compose)	The default. `2` runs directly on the host and needs your own database and JDK 21
`Access`	`2` (Bundled reverse proxy)	Reach the service by subdomain. This fits a team that will keep using it
`Proxy engine`	`1` (Caddy)	The default
`TLS certificate`	`4` (No TLS, HTTP on :80)	Use HTTP on the intranet until the path works
`Database`	`1` (start MySQL 8 in Compose)	You do not bring your own database
`Install directory`	Press Enter	Use the default directory
`Public DNS name`	`example.com`	The root domain only. Do not enter `gm.example.com`. The wizard lists the subdomains that need DNS
`Admin username` / `Admin password`	`admin` / a password you choose	The admin account you will sign in with. The password is at least 8 characters
`Timezone`	`Asia/Shanghai`	The default
`MySQL root password`	One you choose	The default is `Angus123`. Change it before real use

Three rows are worth a longer note:

Access decides how the browser reaches the service. The default, 1, lets the browser open ports such as 8801 and 8803 directly. That fits a trial on one machine. The recommended 2 starts a bundled reverse proxy: one front service that receives requests on port 80 and sends them to GM or Git by domain name. People then use the subdomains, which fits a team that will keep using it.
TLS certificate decides whether HTTPS certificates are turned on. On an intranet you can choose 4 and use HTTP until the path works. When you already have a certificate, choose 1 and fill in the certificate file path. The list also includes Let's Encrypt. That option needs the server to be reachable from the public internet. Do not choose it on an intranet.
Database also has other choices besides the recommended 1. 3 uses PostgreSQL 16. When you already have a database, choose 2 (MySQL 8) or 4 (PostgreSQL 14 or newer).

After the answers are in, the wizard configures and starts the services, and it says: “Leave this terminal running until you see "Install finished." or ERROR.” Leave the terminal open until you see Install finished. or ERROR. The first start takes a few minutes for each application. On success the terminal prints doctor: OK (the health check passed) and Install finished., then the GM console address, the admin username, and the install directory.

After you see Install finished., wait about another minute for the services to be fully ready, then open a browser.

3. Sign in

In the browser, open http://gm.example.com/ and sign in to GM with the admin account from the wizard. After sign-in, open http://git.example.com/, or enter Git through the application switcher on the page.

If Access is the default 1, there are no subdomains. The address is the http://server-address:8801/ printed at the end of the wizard. Git is usually on port 8803. When a port is already in use, the wizard picks another one, so use the address printed in the terminal.

4. Four-step acceptance: clone, push, pull request, merge

A page that opens only shows that the service process is up. The four steps below check, in order, that a team and a repository can be created, that SSH connects, that code can be written, and that a pull request can be merged. The team can use the install when all four pass.

Create a team and a repository

A repository is created under an owner (a person or a team), so create the team first. Open Settings → Team, click New Team, and set Team Slug to a short English name, for example demo. It appears in the repository address. Then, in the sidebar, open Repositories → New repository. Set the owner to demo, the repository name to hello, and select Add a README file. The new repository already has content, so the next step can clone it.

Register an SSH public key and clone

An SSH public key is the half of a key pair on your computer that you can share. After you register it on AngusGit, the server recognizes this computer, and push and pull no longer ask for a password. Open Profile → SSH Keys, click Add SSH Key, and paste the public key from this machine (if you do not have a key yet, generate one with the ssh-keygen at the start of this article and copy the .pub line). On the developer machine, run git ls-remote to test the connection. A listing that includes refs/heads/main means SSH is connected. Then clone the repository.

Push a branch

This step checks that code can be written to the server. In the cloned repository, create a branch, change a file, commit, and push. A successful push means your write permission and the server disk are both fine.

Open a pull request and merge it

This step checks the collaboration path. On the repository page, open a pull request that merges the branch you just pushed into main. Open Files changed and confirm the change is visible, then merge. After the merge, main shows this change, and the acceptance is done.

The commands for steps 2 and 3 are below. demo/hello in the address is the team and repository created above:

git ls-remote ssh://git@git.example.com:2222/demo/hello.git
git clone ssh://git@git.example.com:2222/demo/hello.git
cd hello
git switch -c check-install
echo "install ok" >> README.md
git commit -am "Check install"
git push -u origin check-install

The SSH address includes :2222. The username is always git. Do not replace it with your sign-in name. In real use, copy the address from the repository page. If SSH does not connect, check that the public key from the start of this article is registered and that the address uses port 2222. To use HTTPS, use the git:write token from the start: the username is your sign-in name and the password is the token.

5. A few things to know after install

Day-to-day commands: Run these from the install directory:

Command	When, and with what	What it does
`./bin/angusctl.sh status`	Any time	See whether each service container is running
`./bin/angusctl.sh doctor`	After install, or while troubleshooting	Run one health check. The last step of install is this command
`./bin/angusctl.sh start`	After a config change, run `render` first	Start every service
`./bin/angusctl.sh upgrade`	When you upgrade	Upgrade to a new version

“After a config change, run render first” on the start row means: after you change the config, run render, then run start.

Where the data is, and how to back it up: Repository files are in $ANGUS_HOME/data/git. Users, teams, pull requests, and the rest of that data are in the database angus. Back up both together: export the angus database with mysqldump, and pack the repository directory with tar. If you back up only one of them, a restore leaves repository records in the database with no files, or files with no records.

SSH port: The default is 2222, from the setting GIT_SSH_PORT. If you change it to 22, the clone address becomes the form without a port, git@git.example.com:demo/hello.git. Before you change it, confirm the server’s own SSH service is not using port 22.

Community user count: Community allows at most 10 users. That limit comes from the license. When the team grows past 10 people, switch to Team or Enterprise.

6. Common problems during install

When something goes wrong, find the same sign in the terminal or the browser as the first column, then follow that row.

What you see	Cause	What to do
The wizard says the directory permissions are wrong and asks for `chown`	A previous install was run with `sudo`	Change the owner of the unpacked directory back to the current user, as the prompt says, then run `./install.sh` without `sudo`
An error after `Public DNS name` is filled with an IP	Reverse-proxy access requires a domain name	Enter the root domain. To use an IP only, set `Access` to `1`
The browser cannot open `gm.example.com`	The subdomain does not point at the server	Check the intranet DNS or the hosts file on this machine. Both subdomains need a record
The page opens, and sign-in then errors or keeps loading	The services are not fully started	Wait a minute or two and refresh. Check status with `./bin/angusctl.sh status`
`git ls-remote` reports `Connection refused` or times out	The connection used port 22, or the firewall does not allow 2222	Use the address that includes `:2222`, and check the firewall
The browser has no CI/CD menu	Community does not include pipelines	That is an edition difference. The install itself is fine

Common questions

Can I install onto a MySQL I already have?

Yes. Set Database to 2, and fill in the address, port, user, and password of the existing MySQL 8. The wizard checks that it can connect, and it stops the install when it cannot.

How do I provide a Team or Enterprise license?

Add a parameter at install time: ./install.sh --license followed by the path of the license file. The install can also finish when no license is provided. The wizard shows a note. After the services start, sign in to GM as the admin and import the license on the system license page. Business features stay unavailable until the license is imported.

Summary

Installing AngusGit on an intranet needs one Linux server that starts at 2 cores and 4 GB, with Docker already installed. Download the package and run ./install.sh as a normal user. In the wizard, the recommended choices are Docker Compose, the bundled reverse proxy, HTTP on the intranet for the first run, and the bundled MySQL 8. For Public DNS name, enter only the root domain. After you see doctor: OK and Install finished., sign in to GM and then open Git. Accept the install in four steps: create a repository, clone, push, and merge a pull request. It is really installed when all four pass. For day-to-day operations, back up the database angus and $ANGUS_HOME/data/git together. Community includes repositories, pull requests, and reviews. When you need the built-in pipeline, use the Team or Enterprise package.

Conclusion: After a normal user runs ./install.sh and sees doctor: OK and Install finished., the intranet deployment is accepted only when these four steps all pass: create a repository, clone over SSH (port 2222), push a branch, and open and merge a pull request.

DEV Community