Improve documentation

master
James Orson 2023-07-06 08:54:37 -07:00 committed by Curith
parent 303c77b2e6
commit 6f817c3c42
1 changed files with 143 additions and 22 deletions

165
README.md
View File

@ -7,31 +7,37 @@
A global proxy for go modules. see: [https://goproxy.io](https://goproxy.io) A global proxy for go modules. see: [https://goproxy.io](https://goproxy.io)
## Requirements ## Requirements
It invokes the local go command to answer requests. This service invokes the local `go` command to answer requests.
The default cacheDir is GOPATH, you can set it up by yourself according to the situation.
The default `cacheDir` is `GOPATH`, you can set it up by yourself according to the situation.
## Build ## Build
git clone https://github.com/goproxyio/goproxy.git
cd goproxy ```shell
make git clone https://github.com/goproxyio/goproxy.git
cd goproxy
make
```
## Started ## Started
### Proxy mode ### Proxy mode
./bin/goproxy -listen=0.0.0.0:80 -cacheDir=/tmp/test ```shell
./bin/goproxy -listen=0.0.0.0:80 -cacheDir=/tmp/test
```
If you run `go get -v pkg` in the proxy machine, should set a new GOPATH which is different from the old GOPATH, or mayebe deadlock. If you run `go get -v pkg` in the proxy machine, you should set a new `GOPATH` which is different from the original `GOPATH`, or you may encounter a deadlock.
See the file test/get_test.sh.
See [`test/get_test.sh`](./test/get_test.sh).
### Router mode ### Router mode
./bin/goproxy -listen=0.0.0.0:80 -proxy https://goproxy.io ```shell
./bin/goproxy -listen=0.0.0.0:80 -proxy https://goproxy.io
```
Use the -proxy flag switch to "Router mode", which Use the `-proxy` flag combined with the `-exclude` flag to enable `Router mode`, which implements route filter to routing private modules or public modules.
implements route filter to routing private module
or public module .
``` ```
direct direct
@ -45,28 +51,143 @@ go get +-------> |goproxy| +-------> |goproxy.io| +---> golang.org/x/net
router mode proxy mode router mode proxy mode
``` ```
In Router mode, use the -exclude flag set pattern , direct to the repo which In `Router mode`, use the `-exclude` flag to set a glob pattern. The glob will specify what packages should not try to resolve with the value of `-proxy`. Modules which match the `-exclude` pattern will resolve direct to the repo which
match the module path, pattern are matched to the full path specified, not only matches the module path.
to the host component.
./bin/goproxy -listen=0.0.0.0:80 -cacheDir=/tmp/test -proxy https://goproxy.io -exclude "*.corp.example.com,rsc.io/private" NOTE: Patterns are matched to the full path specified, not only to the host component.
```shell
./bin/goproxy -listen=0.0.0.0:80 -cacheDir=/tmp/test -proxy https://goproxy.io -exclude "*.corp.example.com,rsc.io/private"
```
### Private module authentication
Some private modules are gated behind `git` authentication. To resolve this, you can force git to rewrite the URL with a personal access token present for auth
```shell
git config --global url."https://${GITHUB_PERSONAL_ACCESS_TOKEN}@github.com/".insteadOf https://github.com/
```
This can be done for other git providers as well, following the same pattern
## Use docker image ## Use docker image
docker run -d -p80:8081 goproxy/goproxy ```shell
docker run -d -p80:8081 goproxy/goproxy
```
Use the -v flag to persisting the proxy module data (change ___cacheDir___ to your own dir): Use the -v flag to persisting the proxy module data (change ___cacheDir___ to your own dir):
docker run -d -p80:8081 -v cacheDir:/go goproxy/goproxy ```
docker run -d -p80:8081 -v cacheDir:/go goproxy/goproxy
```
## Docker Compose ## Docker Compose
docker-compose up ```shell
docker-compose up
```
## Kubernetes
Deployment:
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: goproxy
name: goproxy
spec:
replicas: 1
template:
metadata:
labels:
app: goproxy
spec:
containers:
- args:
- -proxy
- https://goproxy.io
- -listen
- 0.0.0.0:8081
- -cacheDir
- /tmp/test
- -exclude
- github.com/my-org/*
image: goproxy/goproxy
name: goproxy
ports:
- containerPort: 8081
volumeMounts:
- mountPath: /tmp/test
name: goproxy
volumes:
- emptyDir:
medium: Memory
sizeLimit: 500Mi
name: goproxy
```
Deployment (with gitconfig secret):
```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
labels:
app: goproxy
name: goproxy
spec:
replicas: 1
template:
metadata:
labels:
app: goproxy
spec:
containers:
- args:
- -proxy
- https://goproxy.io
- -listen
- 0.0.0.0:8081
- -cacheDir
- /tmp/test
- -exclude
- github.com/my-org/*
image: goproxy/goproxy
name: goproxy
ports:
- containerPort: 8081
volumeMounts:
- mountPath: /tmp/test
name: goproxy
- mountPath: /root
name: gitconfig
readOnly: true
volumes:
- emptyDir:
medium: Memory
sizeLimit: 500Mi
name: goproxy
- name: gitconfig
secret:
secretName: gitconfig
---
apiVersion: v1
data:
# NOTE: Encoded version of the following, replacing ${GITHUB_PERSONAL_ACCESS_TOKEN}
# [url "https://${GITHUB_PERSONAL_ACCESS_TOKEN}@github.com/"]
# insteadOf = https://github.com/
.gitconfig: *****************************
kind: Secret
metadata:
name: test
```
## Appendix ## Appendix
1. set `export GOPROXY=http://localhost` to enable your goproxy. - If running locally, set `export GOPROXY=http://localhost[:PORT]` to use your goproxy.
2. set `export GOPROXY=direct` to disable it. - Set `export GOPROXY=direct` to directly access modules without your goproxy.
## Sponsors ## Sponsors