Deployment Guide

This guide covers installing, configuring, and running GitProxy in both development and production environments.

For configuration details, see the Configuration Overview and Configuration Reference.

---

Prerequisites

System Requirements

• Node.js: >= 20.18.2, >= 22.13.1, or >= 24.0.0
• Git: Required for cloning and pack operations
• Operating System: Linux, macOS, or Windows

Database Options

GitProxy supports two database backends (configured in proxy.config.json under "sink"):

1. NeDB (File-based) — Default, suitable for development and single-server use

   • No external dependencies
   • Data stored in ./.data/db/ (hardcoded path, not configurable)
   • Sessions are in-memory only (lost on restart)

2. MongoDB — Recommended for production

   • Requires MongoDB 7.0+
   • Supports persistent sessions
   • Required for multi-instance deployments

Optional Dependencies

• Gitleaks — For secret scanning. Must be installed separately; it is not bundled with GitProxy or the Docker image.
• Docker — For containerized deployment

---

Quick Start

1. Install GitProxy

npm install -g @finos/git-proxy

Quick testing with npx

For quick local testing before committing to a full installation, you can use npx without installing globally:

npx -- @finos/git-proxy --config ./proxy.config.json

For persistent deployments, prefer npm install -g with version pinning (e.g., npm install -g @finos/git-proxy@2.x.x). See Usage for more details.

2. Create a Configuration File

Create proxy.config.json in your working directory:

{
  "authorisedList": [
    {
      "project": "my-org",
      "name": "my-repo",
      "url": "https://github.com/my-org/my-repo.git"
    }
  ]
}

warning

Repository URLs must include the .git suffix. Without it, you will get fatal: info/refs not valid errors.

3. Start GitProxy

git-proxy --config ./proxy.config.json

Expected output:

Listening on 8000
Service Listening on 8080

GitProxy runs two servers:

• Proxy server on port 8000 — intercepts git operations
• Service/UI server on port 8080 — web dashboard and REST API

4. Configure Your Git Client

In your local repository, add GitProxy as a remote:

cd /path/to/my-repo
git remote add proxy http://localhost:8000/my-org/my-repo.git

Or replace the existing origin:

git remote set-url origin http://localhost:8000/my-org/my-repo.git

5. Test a Push

git add .
git commit -m "test: validate gitproxy integration"
git push proxy main

You should receive a message with a review URL:

remote: GitProxy has received your push
remote: Shareable Link
remote: http://localhost:8080/dashboard/push/000000__b12557

6. Approve the Push

1. Navigate to http://localhost:8080 in your browser
2. Log in with default credentials (development only):
   • Username: admin
   • Password: admin
3. Review the push and approve it
4. Push again to forward to upstream:

   git push proxy main

---

Docker Deployment

Using the Published Image

A Docker image is published to Docker Hub:

docker run -d \
  --name git-proxy \
  -p 8000:8000 \
  -p 8080:8080 \
  -v $(pwd)/proxy.config.json:/app/proxy.config.json:ro \
  finos/git-proxy:latest

Building from Source

git clone https://github.com/finos/git-proxy.git
cd git-proxy
docker build -t git-proxy:local .

The Dockerfile uses a multi-stage build with Node.js 20, installs git and tini, and runs as a non-root user (UID 1000). Ports 8000 (proxy) and 8080 (UI/API) are exposed.

View logs:

docker logs -f git-proxy

Runtime Environment Variables

The following environment variables can be set at container runtime:

Variable	Default	Description
GIT_PROXY_SERVER_PORT	8000	Proxy server port
GIT_PROXY_UI_PORT	8080	UI/API server port
ALLOWED_ORIGINS	(empty)	CORS allowed origins (comma-separated, or * for all)
API_URL	(empty)	API URL for the UI (leave empty for same-origin)
NODE_ENV	production	Node environment

Example with environment variables:

docker run -d \
  --name git-proxy \
  -p 8000:8000 \
  -p 8080:8080 \
  -e GIT_PROXY_UI_PORT=8080 \
  -e ALLOWED_ORIGINS="https://gitproxy.example.com" \
  -e NODE_ENV=production \
  -v $(pwd)/proxy.config.json:/app/proxy.config.json:ro \
  git-proxy:local

Persistent Data

When using the file-based database (NeDB), mount a volume for the data directory:

docker run -d \
  --name git-proxy \
  -p 8000:8000 \
  -p 8080:8080 \
  -v $(pwd)/proxy.config.json:/app/proxy.config.json:ro \
  -v $(pwd)/data:/app/.data \
  git-proxy:local

When using MongoDB, no additional data volumes are needed for GitProxy itself — data is stored in MongoDB.

---

Git Client Configuration

Setting GitProxy as a Remote

Option 1: Add as a new remote

cd /path/to/repository
git remote add proxy http://gitproxy.example.com:8000/org/repo.git
git push proxy main

Option 2: Replace origin

git remote set-url origin http://gitproxy.example.com:8000/org/repo.git
git push origin main

Credential Management

GitProxy prompts for credentials on each push. To cache credentials:

macOS:

git config --global credential.helper osxkeychain

Windows:

git config --global credential.helper manager

Linux:

git config --global credential.helper store

Required credentials for pushing through GitProxy to GitHub:

• GitHub username
• Personal Access Token (PAT) with at minimum public_repo scope

SSH Support

GitProxy currently supports HTTPS only. SSH protocol support is under active development.

---

Production Considerations

MongoDB for Production

Switch from the default file-based database to MongoDB for production use:

{
  "sink": [
    {
      "type": "mongo",
      "connectionString": "mongodb://user:password@mongodb-host:27017/gitproxy",
      "options": {
        "ssl": true,
        "tlsAllowInvalidCertificates": false
      },
      "enabled": true
    }
  ]
}

Recommendations:

• Use MongoDB 7.0 or later
• Enable authentication and TLS/SSL
• Configure replica sets for high availability
• Schedule regular backups of audit data (mongodump)

Health Checks

GitProxy provides health check endpoints on both servers:

• /healthcheck on the proxy port (8000) — returns 200 OK with text body "OK"
• /api/v1/healthcheck on the service port (8080) — returns 200 OK with JSON body {"message":"ok"}

Use these for load balancer health probes, container orchestration liveness/readiness checks, or uptime monitoring.

Monitoring

GitProxy does not currently ship with built-in metrics or structured logging. Recommended monitoring points:

• Health endpoints — poll /healthcheck and /api/v1/healthcheck
• Process health — monitor Node.js process uptime and memory usage
• Database connectivity — monitor MongoDB connection status
• Push activity — query the pushes collection for approval/rejection rates

Backup

MongoDB:

mongodump --uri="mongodb://localhost:27017/gitproxy" --out=/backup/$(date +%Y%m%d)

File-based (NeDB):

tar -czf gitproxy-backup-$(date +%Y%m%d).tar.gz ./.data

Always version-control your proxy.config.json.