Skip to content

Commit dfac352

Browse files
tabathadtabathad
committed
docs: add deployment guide
1 parent 2150064 commit dfac352

2 files changed

Lines changed: 332 additions & 0 deletions

File tree

‎website/docs/deployment.mdx‎

Lines changed: 331 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,331 @@
1+
# Deployment Guide
2+
3+
This guide covers installing, configuring, and running GitProxy in both development and production environments.
4+
5+
For configuration details, see the [Configuration Overview](/docs/configuration/overview) and [Configuration Reference](/docs/configuration/reference).
6+
7+
---
8+
9+
## Prerequisites
10+
11+
### System Requirements
12+
13+
- **Node.js**: >= 20.18.2, >= 22.13.1, or >= 24.0.0
14+
- **Git**: Required for cloning and pack operations
15+
- **Operating System**: Linux, macOS, or Windows
16+
17+
### Database Options
18+
19+
GitProxy supports two database backends (configured in `proxy.config.json` under `"sink"`):
20+
21+
1. **NeDB (File-based)** — Default, suitable for development and single-server use
22+
- No external dependencies
23+
- Data stored in `./.data/db/` (hardcoded path, not configurable)
24+
- Sessions are in-memory only (lost on restart)
25+
26+
2. **MongoDB** — Recommended for production
27+
- Requires MongoDB 7.0+
28+
- Supports persistent sessions
29+
- Required for multi-instance deployments
30+
31+
### Optional Dependencies
32+
33+
- **[Gitleaks](https://github.com/gitleaks/gitleaks)** — For secret scanning. Must be installed separately; it is not bundled with GitProxy or the Docker image.
34+
- **Docker** — For containerized deployment
35+
36+
---
37+
38+
## Quick Start
39+
40+
### 1. Install GitProxy
41+
42+
```bash
43+
npm install -g @finos/git-proxy
44+
```
45+
46+
:::tip Quick testing with npx
47+
For quick local testing before committing to a full installation, you can use `npx` without installing globally:
48+
49+
```bash
50+
npx -- @finos/git-proxy --config ./proxy.config.json
51+
```
52+
53+
For persistent deployments, prefer `npm install -g` with version pinning (e.g., `npm install -g @finos/git-proxy@2.x.x`). See [Usage](/docs/usage) for more details.
54+
:::
55+
56+
### 2. Create a Configuration File
57+
58+
Create `proxy.config.json` in your working directory:
59+
60+
```json
61+
{
62+
"authorisedList": [
63+
{
64+
"project": "my-org",
65+
"name": "my-repo",
66+
"url": "https://github.com/my-org/my-repo.git"
67+
}
68+
]
69+
}
70+
```
71+
72+
:::warning
73+
Repository URLs **must** include the `.git` suffix. Without it, you will get `fatal: info/refs not valid` errors.
74+
:::
75+
76+
### 3. Start GitProxy
77+
78+
```bash
79+
git-proxy --config ./proxy.config.json
80+
```
81+
82+
Expected output:
83+
```
84+
Listening on 8000
85+
Service Listening on 8080
86+
```
87+
88+
GitProxy runs two servers:
89+
90+
- **Proxy server** on port 8000 — intercepts git operations
91+
- **Service/UI server** on port 8080 — web dashboard and REST API
92+
93+
### 4. Configure Your Git Client
94+
95+
In your local repository, add GitProxy as a remote:
96+
97+
```bash
98+
cd /path/to/my-repo
99+
git remote add proxy http://localhost:8000/my-org/my-repo.git
100+
```
101+
102+
Or replace the existing origin:
103+
```bash
104+
git remote set-url origin http://localhost:8000/my-org/my-repo.git
105+
```
106+
107+
### 5. Test a Push
108+
109+
```bash
110+
git add .
111+
git commit -m "test: validate gitproxy integration"
112+
git push proxy main
113+
```
114+
115+
You should receive a message with a review URL:
116+
```
117+
remote: GitProxy has received your push
118+
remote: Shareable Link
119+
remote: http://localhost:8080/dashboard/push/000000__b12557
120+
```
121+
122+
### 6. Approve the Push
123+
124+
1. Navigate to http://localhost:8080 in your browser
125+
2. Log in with default credentials (**development only**):
126+
- Username: `admin`
127+
- Password: `admin`
128+
3. Review the push and approve it
129+
4. Push again to forward to upstream:
130+
```bash
131+
git push proxy main
132+
```
133+
134+
---
135+
136+
## Docker Deployment
137+
138+
### Using the Published Image
139+
140+
A Docker image is published to [Docker Hub](https://hub.docker.com/r/finos/git-proxy):
141+
142+
```bash
143+
docker run -d \
144+
--name git-proxy \
145+
-p 8000:8000 \
146+
-p 8080:8080 \
147+
-v $(pwd)/proxy.config.json:/app/proxy.config.json:ro \
148+
finos/git-proxy:latest
149+
```
150+
151+
### Building from Source
152+
153+
```bash
154+
git clone https://github.com/finos/git-proxy.git
155+
cd git-proxy
156+
docker build -t git-proxy:local .
157+
```
158+
159+
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.
160+
161+
View logs:
162+
```bash
163+
docker logs -f git-proxy
164+
```
165+
166+
### Runtime Environment Variables
167+
168+
The following environment variables can be set at container runtime:
169+
170+
| Variable | Default | Description |
171+
| ------------------------ | ------------ | -------------------------------------------------------- |
172+
| `GIT_PROXY_SERVER_PORT` | `8000` | Proxy server port |
173+
| `GIT_PROXY_UI_PORT` | `8080` | UI/API server port |
174+
| `ALLOWED_ORIGINS` | (empty) | CORS allowed origins (comma-separated, or `*` for all) |
175+
| `API_URL` | (empty) | API URL for the UI (leave empty for same-origin) |
176+
| `NODE_ENV` | `production` | Node environment |
177+
178+
Example with environment variables:
179+
```bash
180+
docker run -d \
181+
--name git-proxy \
182+
-p 8000:8000 \
183+
-p 8080:8080 \
184+
-e GIT_PROXY_UI_PORT=8080 \
185+
-e ALLOWED_ORIGINS="https://gitproxy.example.com" \
186+
-e NODE_ENV=production \
187+
-v $(pwd)/proxy.config.json:/app/proxy.config.json:ro \
188+
git-proxy:local
189+
```
190+
191+
### Persistent Data
192+
193+
When using the file-based database (NeDB), mount a volume for the data directory:
194+
195+
```bash
196+
docker run -d \
197+
--name git-proxy \
198+
-p 8000:8000 \
199+
-p 8080:8080 \
200+
-v $(pwd)/proxy.config.json:/app/proxy.config.json:ro \
201+
-v $(pwd)/data:/app/.data \
202+
git-proxy:local
203+
```
204+
205+
When using MongoDB, no additional data volumes are needed for GitProxy itself — data is stored in MongoDB.
206+
207+
---
208+
209+
## Git Client Configuration
210+
211+
### Setting GitProxy as a Remote
212+
213+
#### Option 1: Add as a new remote
214+
215+
```bash
216+
cd /path/to/repository
217+
git remote add proxy http://gitproxy.example.com:8000/org/repo.git
218+
git push proxy main
219+
```
220+
221+
#### Option 2: Replace origin
222+
223+
```bash
224+
git remote set-url origin http://gitproxy.example.com:8000/org/repo.git
225+
git push origin main
226+
```
227+
228+
### HTTPS with Self-Signed Certificates
229+
230+
For development with self-signed certificates:
231+
```bash
232+
git -c http.sslVerify=false push proxy main
233+
```
234+
235+
Or configure per-remote (development only):
236+
```bash
237+
git config http.https://gitproxy.example.com:8000/.sslVerify false
238+
```
239+
240+
:::danger
241+
Never disable SSL verification in production environments.
242+
:::
243+
244+
### Credential Management
245+
246+
GitProxy prompts for credentials on each push. To cache credentials:
247+
248+
**macOS:**
249+
```bash
250+
git config --global credential.helper osxkeychain
251+
```
252+
253+
**Windows:**
254+
```bash
255+
git config --global credential.helper manager
256+
```
257+
258+
**Linux:**
259+
```bash
260+
git config --global credential.helper store
261+
```
262+
263+
**Required credentials for pushing through GitProxy to GitHub:**
264+
- GitHub username
265+
- Personal Access Token (PAT) with at minimum `public_repo` scope
266+
267+
### SSH Support
268+
269+
GitProxy currently supports HTTPS only. SSH protocol support is under active development.
270+
271+
---
272+
273+
## Production Considerations
274+
275+
### MongoDB for Production
276+
277+
Switch from the default file-based database to MongoDB for production use:
278+
279+
```json
280+
{
281+
"sink": [
282+
{
283+
"type": "mongo",
284+
"connectionString": "mongodb://user:password@mongodb-host:27017/gitproxy",
285+
"options": {
286+
"ssl": true,
287+
"tlsAllowInvalidCertificates": false
288+
},
289+
"enabled": true
290+
}
291+
]
292+
}
293+
```
294+
295+
**Recommendations:**
296+
- Use MongoDB 7.0 or later
297+
- Enable authentication and TLS/SSL
298+
- Configure replica sets for high availability
299+
- Schedule regular backups of audit data (`mongodump`)
300+
301+
### Health Checks
302+
303+
GitProxy provides health check endpoints on both servers:
304+
305+
- **`/healthcheck`** on the proxy port (8000) — returns `200 OK` with text body `"OK"`
306+
- **`/api/v1/healthcheck`** on the service port (8080) — returns `200 OK` with JSON body `{"message":"ok"}`
307+
308+
Use these for load balancer health probes, container orchestration liveness/readiness checks, or uptime monitoring.
309+
310+
### Monitoring
311+
312+
GitProxy does not currently ship with built-in metrics or structured logging. Recommended monitoring points:
313+
314+
- **Health endpoints** — poll `/healthcheck` and `/api/v1/healthcheck`
315+
- **Process health** — monitor Node.js process uptime and memory usage
316+
- **Database connectivity** — monitor MongoDB connection status
317+
- **Push activity** — query the pushes collection for approval/rejection rates
318+
319+
### Backup
320+
321+
**MongoDB:**
322+
```bash
323+
mongodump --uri="mongodb://localhost:27017/gitproxy" --out=/backup/$(date +%Y%m%d)
324+
```
325+
326+
**File-based (NeDB):**
327+
```bash
328+
tar -czf gitproxy-backup-$(date +%Y%m%d).tar.gz ./.data
329+
```
330+
331+
Always version-control your `proxy.config.json`.

‎website/sidebars.js‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ module.exports = {
1717
},
1818
'installation',
1919
'usage',
20+
'deployment',
2021
{
2122
type: 'category',
2223
label: 'Configuration',

0 commit comments

Comments
 (0)