README.md 2.89 KB
Newer Older
1
# gitlab-workhorse
Jacob Vosmaer's avatar
Jacob Vosmaer committed
2

3 4 5
Gitlab-workhorse is a smart reverse proxy for GitLab. It handles
"large" HTTP requests such as file downloads, file uploads, Git
push/pull and Git archive downloads.
Jacob Vosmaer's avatar
Jacob Vosmaer committed
6 7


8 9 10
## Usage

```
11
  gitlab-workhorse [OPTIONS]
12 13 14 15

Options:
  -authBackend string
    	Authentication/authorization backend (default "http://localhost:8080")
16 17
  -authSocket string
    	Optional: Unix domain socket to dial authBackend at
18 19 20 21
  -developmentMode
    	Allow to serve assets from Rails app
  -documentRoot string
    	Path to static files content (default "public")
22 23 24 25 26 27 28 29
  -listenAddr string
    	Listen address for HTTP server (default "localhost:8181")
  -listenNetwork string
    	Listen 'network' (tcp, tcp4, tcp6, unix) (default "tcp")
  -listenUmask int
    	Umask for Unix socket, default: 022 (default 18)
  -pprofListenAddr string
    	pprof listening address, e.g. 'localhost:6060'
30 31
  -proxyHeadersTimeout duration
    	How long to wait for response headers when proxying the request (default 1m0s)
32 33 34 35
  -version
    	Print version and exit
```

Marco Vito Moscaritolo's avatar
Marco Vito Moscaritolo committed
36
The 'auth backend' refers to the GitLab Rails application. The name is
Jacob Vosmaer's avatar
Jacob Vosmaer committed
37 38
a holdover from when gitlab-workhorse only handled Git push/pull over
HTTP.
39

40
Gitlab-workhorse can listen on either a TCP or a Unix domain socket. It
41 42 43
can also open a second listening TCP listening socket with the Go
[net/http/pprof profiler server](http://golang.org/pkg/net/http/pprof/).

44 45 46 47 48 49 50 51 52 53
### Relative URL support

If you are mounting GitLab at a relative URL, e.g.
`example.com/gitlab`, then you should also use this relative URL in
the `authBackend` setting:

```
gitlab-workhorse -authBackend http://localhost:8080/gitlab
```

54 55
## Installation

Jacob Vosmaer's avatar
Jacob Vosmaer committed
56 57 58
To install gitlab-workhorse you need [Go 1.5 or
newer](https://golang.org/dl).

59 60 61 62 63 64
To install into `/usr/local/bin` run `make install`.

```
make install
```

65 66 67 68 69
To install into `/foo/bin` set the PREFIX variable.

```
make install PREFIX=/foo
```
70 71 72 73 74 75

## Tests

```
make clean test
```
76

77 78 79 80 81 82
## Try it out

You can try out the Git server without authentication as follows:

```
# Start a fake auth backend that allows everything/everybody
83 84
make test/data/test.git
go run support/fake-auth-backend.go ~+/test/data/test.git &
85
# Start gitlab-workhorse
86
make
87
./gitlab-workhorse
88 89
```

90 91 92 93 94 95
Now you can try things like:

```
git clone http://localhost:8181/test.git
curl -JO http://localhost:8181/test/repository/archive.zip
```
96

Jacob Vosmaer's avatar
Jacob Vosmaer committed
97 98 99
## Example request flow

- start POST repo.git/git-receive-pack to NGINX
100
- ..start POST repo.git/git-receive-pack to gitlab-workhorse
Jacob Vosmaer's avatar
Jacob Vosmaer committed
101 102
- ....start POST repo.git/git-receive-pack to Unicorn for auth
- ....end POST to Unicorn for auth
103
- ....start git-receive-pack process from gitlab-workhorse
Jacob Vosmaer's avatar
Jacob Vosmaer committed
104 105 106
- ......start POST /api/v3/internal/allowed to Unicorn from Git hook (check protected branches)
- ......end POST to Unicorn from Git hook
- ....end git-receive-pack process
107
- ..end POST to gitlab-workhorse
Jacob Vosmaer's avatar
Jacob Vosmaer committed
108 109
- end POST to NGINX

Jacob Vosmaer's avatar
Jacob Vosmaer committed
110 111 112
## License

This code is distributed under the MIT license, see the LICENSE file.