Skip to content

Commit 24eb8e2

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

2 files changed

Lines changed: 316 additions & 0 deletions

File tree

‎website/docs/deployment.mdx‎

Lines changed: 315 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,315 @@
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+
### Credential Management
229+
230+
GitProxy prompts for credentials on each push. To cache credentials:
231+
232+
**macOS:**
233+
```bash
234+
git config --global credential.helper osxkeychain
235+
```
236+
237+
**Windows:**
238+
```bash
239+
git config --global credential.helper manager
240+
```
241+
242+
**Linux:**
243+
```bash
244+
git config --global credential.helper store
245+
```
246+
247+
**Required credentials for pushing through GitProxy to GitHub:**
248+
- GitHub username
249+
- Personal Access Token (PAT) with at minimum `public_repo` scope
250+
251+
### SSH Support
252+
253+
GitProxy currently supports HTTPS only. SSH protocol support is under active development.
254+
255+
---
256+
257+
## Production Considerations
258+
259+
### MongoDB for Production
260+
261+
Switch from the default file-based database to MongoDB for production use:
262+
263+
```json
264+
{
265+
"sink": [
266+
{
267+
"type": "mongo",
268+
"connectionString": "mongodb://user:password@mongodb-host:27017/gitproxy",
269+
"options": {
270+
"ssl": true,
271+
"tlsAllowInvalidCertificates": false
272+
},
273+
"enabled": true
274+
}
275+
]
276+
}
277+
```
278+
279+
**Recommendations:**
280+
- Use MongoDB 7.0 or later
281+
- Enable authentication and TLS/SSL
282+
- Configure replica sets for high availability
283+
- Schedule regular backups of audit data (`mongodump`)
284+
285+
### Health Checks
286+
287+
GitProxy provides health check endpoints on both servers:
288+
289+
- **`/healthcheck`** on the proxy port (8000) — returns `200 OK` with text body `"OK"`
290+
- **`/api/v1/healthcheck`** on the service port (8080) — returns `200 OK` with JSON body `{"message":"ok"}`
291+
292+
Use these for load balancer health probes, container orchestration liveness/readiness checks, or uptime monitoring.
293+
294+
### Monitoring
295+
296+
GitProxy does not currently ship with built-in metrics or structured logging. Recommended monitoring points:
297+
298+
- **Health endpoints** — poll `/healthcheck` and `/api/v1/healthcheck`
299+
- **Process health** — monitor Node.js process uptime and memory usage
300+
- **Database connectivity** — monitor MongoDB connection status
301+
- **Push activity** — query the pushes collection for approval/rejection rates
302+
303+
### Backup
304+
305+
**MongoDB:**
306+
```bash
307+
mongodump --uri="mongodb://localhost:27017/gitproxy" --out=/backup/$(date +%Y%m%d)
308+
```
309+
310+
**File-based (NeDB):**
311+
```bash
312+
tar -czf gitproxy-backup-$(date +%Y%m%d).tar.gz ./.data
313+
```
314+
315+
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)