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: >= 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 6.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/3f9c2a7e1b8d4c6f0a5e9b2d7c1f4a8e6b3d0c9f2e5a7b1d4c8f0e3a6b9d2c5f

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

   See the Authentication section of the architecture guide for more details.

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 22, 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 (HTTP)
GIT_PROXY_HTTPS_UI_PORT	8444	UI/API server port (HTTPS, active when tls.enabled)
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 \
  -p 8444:8444 \
  -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 6.0 or later
• Enable authentication and TLS/SSL
• Configure replica sets for high availability
• Schedule regular backups of audit data (mongodump)

Repository activity summaries are derived from the push audit records. Startup migration 20261013-repository-activity creates the required indexes and backfills activity metadata before the proxy and API start accepting requests. Allow extra startup time for large audit histories. Use the same GitProxy version across instances during this upgrade: older writers do not update the activity revisions. Standalone MongoDB is supported; summary updates do not require transactions or a replica set.

The migration checks for duplicate push IDs before creating the unique index. If duplicates exist, startup fails with example IDs and leaves the audit records intact. Stop all writers, back up the database, and inspect every record with each reported ID. Reconcile their IDs and any external references according to your audit retention policy, preserving distinct historical attempts. GitProxy cannot safely choose which audit to discard. Restart after reconciliation; a failed migration is not marked complete and will be retried.

Interrupted summary refreshes recover on the next repository read. Each read checks indexed dirty markers and refreshes only affected repositories. Simultaneous readers in one process share the refresh; revision checks prevent older work in other instances from overwriting newer summaries. Deleting a push removes its audit payload immediately; a small internal deletion marker remains until its repository summary is refreshed.

After restoring only the pushes collection or repairing summaries manually, stop application instances and rebuild through the shared database API. From an installation with @finos/git-proxy available, use the deployment's configuration:

CONFIG_FILE=/path/to/proxy.config.json node -e \
  "require('@finos/git-proxy/db').rebuildRepoPushRollups().then(() => process.exit(0), error => { console.error(error); process.exit(1); })"

This API uses the configured sink and supports MongoDB, PostgreSQL, and NeDB. Restart application instances after a successful rebuild. For NeDB, summaries are in memory and are also rebuilt from saved push records on restart.

PostgreSQL Repository Activity

Schema migration 9 adds derived activity tables and a trigger that records push inserts, updates, and deletes in the same transaction as the audit change. It queues existing pushes without rewriting their audit content. Startup migration 20261013-repository-activity fills the summaries before the proxy and API accept requests; subsequent reads refresh only changed pushes and affected repositories. Reads with no changes use the saved summaries without scanning audit history.

Refreshes run in a transaction. A failed refresh is retried on the next repository read, and concurrent audit updates remain queued for another refresh. The database trigger also tracks writes from older GitProxy instances and the PostgreSQL importer.

If autoMigrate is disabled, apply the new migration with npm run migrate:postgres:schema using DDL-capable credentials before starting the updated application. The runtime role needs SELECT, INSERT, UPDATE, and DELETE on push_activity_changes, push_activity, and repo_push_activity, in addition to its existing permissions.

Back up the database together with its derived tables. After a partial restore, a restore with triggers disabled, or manual summary repair, use the shared rebuild command above with the PostgreSQL sink enabled.

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.