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 (2.31 or later if the repository cache is enabled)
- Operating System: Linux, macOS, or Windows
Database Options
GitProxy supports two database backends (configured in proxy.config.json under "sink"):
-
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)
-
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
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"
}
]
}
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
-
Navigate to http://localhost:8080 in your browser
-
Log in with default credentials (development only):
- Username:
admin - Password:
admin
See the Authentication section of the architecture guide for more details.
- Username:
-
Review the push and approve it
-
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.
If the repository cache is enabled, also mount its directory so the cached repositories survive container restarts:
-v $(pwd)/cache:/app/.remote/cache
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_reposcope
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)
Database migrations run automatically on startup. See Database Migrations for what changes between releases and when an upgrade needs manual steps.
Repository Cache
Before running its checks, GitProxy clones the upstream repository for every push. For large repositories this clone dominates the push time. The repository cache keeps a bare mirror of each repository on disk and only fetches the new commits, which makes repeated pushes to the same repository several times faster.
The cache is disabled by default. Enabling it is recommended for production:
{
"cache": {
"enabled": true
}
}
| Setting | Default | Description |
|---|---|---|
maxSizeGB | 2 | Least recently used mirrors are removed above this size |
maxRepositories | 50 | Least recently used mirrors are removed above this count |
cacheDir | ./.remote/cache | Where the mirrors are stored |
gitTimeoutSeconds | 600 | A git command running longer than this fails the push |
Things to know:
- Each push still authenticates against the upstream with the pushing user's own credentials, so the cache never gives anyone access to a repository they could not clone themselves.
- Requires Git 2.31 or later on the GitProxy host.
- Size
maxSizeGBand the disk behindcacheDirfor the repositories you proxy. A single repository larger thanmaxSizeGBis still cached, and a warning is logged. - Raise
gitTimeoutSecondsif the first clone of your largest repository takes longer than 10 minutes. - Do not share one
cacheDirbetween several GitProxy instances: concurrent pushes are only coordinated within a single process.
See the Configuration Reference for all settings.
Health Checks
GitProxy provides health check endpoints on both servers:
/healthcheckon the proxy port (8000) — returns200 OKwith text body"OK"/api/v1/healthcheckon the service port (8080) — returns200 OKwith 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
/healthcheckand/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.