1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
|
# vanity
Use `vanity` to provide pretty package import names using your own custom
domain:
```go
import (
"example.org/coolpkg"
)
```
## A simple example
See the available `vanity` parameters with `-h`:
```
vanity -h
Usage of ./gopkg:
-addr string
Serve HTTP at given address (default ":8080")
-repo-root string
Git repository root URL (e.g.: https://github.com/upper).
-vanity-root string
Vanity root URL (e.g.: https://upper.io).
```
Now run `vanity` on localhost:
```
vanity -addr localhost:8082 -repo-root https://github.com/golang \
-vanity-root http://localhost:8082
```
Using a different terminal session, try to `go get` a package from
`localhost:8082`:
```
go get -insecure -v localhost:8082/example/hello
```
`vanity` will tell `go get` to keep the import path and pull the source from a
different place.
Output should be similar to:
```
Fetching https://localhost:8082/example/hello?go-get=1
https fetch failed.
Fetching http://localhost:8082/example/hello?go-get=1
Parsing meta tags from http://localhost:8082/example/hello?go-get=1 (status code 200)
get "localhost:8082/example/hello": found meta tag main.metaImport{Prefix:"localhost:8082/example", VCS:"git", RepoRoot:"http://localhost:8082/example"} at http://localhost:8082/example/hello?go-get=1
get "localhost:8082/example/hello": verifying non-authoritative meta tag
Fetching https://localhost:8082/example?go-get=1
https fetch failed.
Fetching http://localhost:8082/example?go-get=1
Parsing meta tags from http://localhost:8082/example?go-get=1 (status code 200)
localhost:8082/example (download)
localhost:8082/example/hello
```
At the end of the `go get` program, you should have the example `hello` package
on `$GOPATH/src/localhost:8082/example/hello` and in your `$GOPATH/bin`
directory as well:
```
hello
Hello, Go examples!
```
### Versioning support
`vanity` also comes with versioning support from the original
[http://gopkg.in](http://gopkg.in) at no extra cost. For instance, the
following import
```
go get -v example.org/coolpkg.v1
```
automatically redirects to the `v1` branch on the github.com/username/coolpkg
repo, and it can also be imported that way:
```go
import (
"example.org/coolpkg.v1"
)
```
Oh, and `vanity` is not tied to GitHub at all, you can use any public git
repository with https support:
```
vanity -addr :80 -repo-root https://othergitsite.com/username -vanity-root https://example.org
```
## Deploy
It is not recommended to run `vanity` directly, as `vanity` does not have a
nice welcome page nor instructions for humans, `vanity` only expects only
communication from `go get`, if any other kind of request is received it will
return a `404` error.
But fear not, you can run `vanity` with `nginx` easily by using that fact, plus
you can have pretty documentation for humans at your custom domain and also be
able to use the same URL as an import path for `go get` with no effort.
Let's see an example:
```
vanity -addr 127.0.0.1:9192 -repo-root https://github.com/upper \
-vanity-root https://upper.io
```
This is the site configuration for nginx:
```nginx
location / {
# First try with vanity.
try_files =404 @vanity;
}
location @vanity {
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass http://127.0.0.1:9192;
proxy_intercept_errors on;
recursive_error_pages on;
set $pass 0;
if ($arg_go-get = 1) {
set $pass 1;
}
if ($request_uri ~ git-upload-pack) {
set $pass 1;
}
if ($pass = 0) {
return 404;
}
error_page 404 = @real_location;
}
location @real_location {
# Fallback location for when vanity returns 404.
...
}
```
Let's see it live, use cURL to request `upper.io/db`:
```
curl "upper.io/db" -L
...
```
You'll see some HTML gibberish made for human readers, now request it again but
this time using the `go-get=1` parameter (that is what `go get` does):
```
curl "upper.io/db?go-get=1" -L
...
<meta name="go-import" content="upper.io/db git https://upper.io/db">
<meta name="go-source" content="upper.io/db _ https://github.com/upper/db/tree/master{/dir} https://github.com/upper/db/blob/master{/dir}/{file}#L{line}">
...
```
And you'll see a reduced HTML page with special tags for `go get`.
## License
### gopkg.in
This project was based on [gopkg.in](http://labix.org/gopkg.in) by [Gustavo
Niemeyer](http://labix.org/):
```
gopkg.in - versioned URLs for Go packages
Copyright (c) 2014 - Gustavo Niemeyer <gustavo@niemeyer.net>
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
```
|
