gemstash 1.0.0.pre.1-java → 2.5.0-java
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +5 -5
- data/CHANGELOG.md +295 -0
- data/exe/gemstash +3 -0
- data/lib/gemstash/api_key_authorization.rb +32 -0
- data/lib/gemstash/authorization.rb +15 -8
- data/lib/gemstash/cache.rb +42 -2
- data/lib/gemstash/cli/authorize.rb +52 -9
- data/lib/gemstash/cli/base.rb +14 -6
- data/lib/gemstash/cli/setup.rb +67 -39
- data/lib/gemstash/cli/start.rb +6 -2
- data/lib/gemstash/cli/status.rb +3 -1
- data/lib/gemstash/cli/stop.rb +4 -1
- data/lib/gemstash/cli.rb +59 -1
- data/lib/gemstash/config.ru +4 -3
- data/lib/gemstash/configuration.rb +56 -8
- data/lib/gemstash/db/authorization.rb +5 -3
- data/lib/gemstash/db/cached_rubygem.rb +20 -0
- data/lib/gemstash/db/dependency.rb +2 -0
- data/lib/gemstash/db/rubygem.rb +3 -0
- data/lib/gemstash/db/upstream.rb +15 -0
- data/lib/gemstash/db/version.rb +25 -2
- data/lib/gemstash/db.rb +5 -0
- data/lib/gemstash/dependencies.rb +6 -2
- data/lib/gemstash/env.rb +44 -13
- data/lib/gemstash/gem_fetcher.rb +5 -3
- data/lib/gemstash/gem_pusher.rb +25 -18
- data/lib/gemstash/gem_source/dependency_caching.rb +4 -4
- data/lib/gemstash/gem_source/private_source.rb +34 -50
- data/lib/gemstash/gem_source/rack_middleware.rb +3 -0
- data/lib/gemstash/gem_source/upstream_source.rb +71 -27
- data/lib/gemstash/gem_source.rb +4 -2
- data/lib/gemstash/gem_yanker.rb +14 -4
- data/lib/gemstash/health.rb +55 -0
- data/lib/gemstash/http_client.rb +15 -5
- data/lib/gemstash/logging.rb +19 -7
- data/lib/gemstash/man/gemstash-authorize.1 +54 -0
- data/lib/gemstash/man/gemstash-authorize.1.txt +52 -0
- data/lib/gemstash/man/gemstash-configuration.5 +186 -0
- data/lib/gemstash/man/gemstash-configuration.5.txt +208 -0
- data/lib/gemstash/man/gemstash-customize.7 +273 -0
- data/lib/gemstash/man/gemstash-customize.7.txt +184 -0
- data/lib/gemstash/man/gemstash-debugging.7 +30 -0
- data/lib/gemstash/man/gemstash-debugging.7.txt +27 -0
- data/lib/gemstash/man/gemstash-deploy.7 +63 -0
- data/lib/gemstash/man/gemstash-deploy.7.txt +57 -0
- data/lib/gemstash/man/gemstash-mirror.7 +34 -0
- data/lib/gemstash/man/gemstash-mirror.7.txt +31 -0
- data/lib/gemstash/man/gemstash-multiple-sources.7 +131 -0
- data/lib/gemstash/man/gemstash-multiple-sources.7.txt +116 -0
- data/lib/gemstash/man/gemstash-private-gems.7 +191 -0
- data/lib/gemstash/man/gemstash-private-gems.7.txt +154 -0
- data/lib/gemstash/man/gemstash-readme.7 +199 -0
- data/lib/gemstash/man/gemstash-readme.7.txt +177 -0
- data/lib/gemstash/man/gemstash-setup.1 +38 -0
- data/lib/gemstash/man/gemstash-setup.1.txt +38 -0
- data/lib/gemstash/man/gemstash-start.1 +23 -0
- data/lib/gemstash/man/gemstash-start.1.txt +24 -0
- data/lib/gemstash/man/gemstash-status.1 +17 -0
- data/lib/gemstash/man/gemstash-status.1.txt +20 -0
- data/lib/gemstash/man/gemstash-stop.1 +17 -0
- data/lib/gemstash/man/gemstash-stop.1.txt +20 -0
- data/lib/gemstash/man/gemstash-version.1 +17 -0
- data/lib/gemstash/man/gemstash-version.1.txt +19 -0
- data/lib/gemstash/migrations/01_gem_dependencies.rb +11 -9
- data/lib/gemstash/migrations/02_authorizations.rb +4 -2
- data/lib/gemstash/migrations/03_cached_gems.rb +26 -0
- data/lib/gemstash/migrations/04_health_tests.rb +10 -0
- data/lib/gemstash/migrations/05_authorization_names.rb +10 -0
- data/lib/gemstash/puma.rb +5 -3
- data/lib/gemstash/rack_env_rewriter.rb +11 -2
- data/lib/gemstash/specs_builder.rb +25 -15
- data/lib/gemstash/storage.rb +175 -32
- data/lib/gemstash/upstream.rb +43 -8
- data/lib/gemstash/version.rb +4 -2
- data/lib/gemstash/web.rb +13 -8
- data/lib/gemstash.rb +6 -2
- metadata +135 -110
- data/.gitignore +0 -10
- data/.rspec +0 -2
- data/.rubocop-bundler.yml +0 -92
- data/.rubocop-relax.yml +0 -11
- data/.rubocop.yml +0 -8
- data/.travis.yml +0 -20
- data/Gemfile +0 -4
- data/README.md +0 -139
- data/Rakefile +0 -35
- data/bin/console +0 -14
- data/bin/gemstash +0 -3
- data/bin/setup +0 -5
- data/docs/config.md +0 -136
- data/docs/debug.md +0 -24
- data/docs/deploy.md +0 -30
- data/docs/mirror.md +0 -30
- data/docs/multiple_sources.md +0 -68
- data/docs/private_gems.md +0 -140
- data/docs/reference.md +0 -308
- data/gemstash.gemspec +0 -47
- data/gemstash.png +0 -0
- data/lib/gemstash/gem_unyanker.rb +0 -61
@@ -0,0 +1,31 @@
|
|
1
|
+
4mgemstash-mirror24m(7) 4mgemstash-mirror24m(7)
|
2
|
+
|
3
|
+
<!-- Automatically generated by Pandoc -->
|
4
|
+
|
5
|
+
1mUsing Gemstash as a Mirror0m
|
6
|
+
If you don't have control over your Gemfile, or you don't want to force
|
7
|
+
everyone on your team to go through the Gemstash server, you can use
|
8
|
+
Bundler mirroring to bundle against your Gemstash server.
|
9
|
+
|
10
|
+
For each source in your Gemfile, add a mirror pointing to your Gemstash
|
11
|
+
server:
|
12
|
+
|
13
|
+
$ bundle config mirror.http://rubygems.org http://localhost:9292
|
14
|
+
$ bundle config mirror.https://my.gem-source.local http://localhost:9292/upstream/$(ruby -rcgi -e 'puts CGI.escape("https://my.gem-source.local")')
|
15
|
+
|
16
|
+
From now on, bundler will fetch gems from those sources via your Gem-
|
17
|
+
stash server.
|
18
|
+
|
19
|
+
1mSimpler Gemstash Mirrors0m
|
20
|
+
1mThis feature requires Bundler to be at least version 1.11.0.0m
|
21
|
+
|
22
|
+
If you are using Bundler version 1.11.0 or greater, the mirroring be-
|
23
|
+
comes a bit easier:
|
24
|
+
|
25
|
+
$ bundle config mirror.http://rubygems.org http://localhost:9292
|
26
|
+
$ bundle config mirror.https://my.gem-source.local http://localhost:9292
|
27
|
+
|
28
|
+
Bundler will then send headers to Gemstash to indicate the correct up-
|
29
|
+
stream.
|
30
|
+
|
31
|
+
October 25, 2015 4mgemstash-mirror24m(7)
|
@@ -0,0 +1,131 @@
|
|
1
|
+
<!-- Automatically generated by Pandoc -->
|
2
|
+
.\" Automatically generated by Pandoc 3.1.8
|
3
|
+
.\"
|
4
|
+
.TH "gemstash-multiple-sources" "7" "October 8, 2015" "" ""
|
5
|
+
.SH Multiple Gem Sources
|
6
|
+
Gemstash will stash from any amount of gem sources.
|
7
|
+
By the end of this guide, you will be able to bundle using multiple gem
|
8
|
+
sources, all stashed within your Gemstash server.
|
9
|
+
.SS Default Source
|
10
|
+
When you don\[cq]t provide an explicit source (as with the Quickstart
|
11
|
+
Guide), your gems will be fetched from https://rubygems.org.
|
12
|
+
This default source is not set in stone.
|
13
|
+
To change it, you need only edit the Gemstash configuration found at
|
14
|
+
\f[CR]\[ti]/.gemstash/config.yml\f[R]:
|
15
|
+
.IP
|
16
|
+
.EX
|
17
|
+
# \[ti]/.gemstash/config.yml
|
18
|
+
---
|
19
|
+
:rubygems_url: https://my.gem-source.local
|
20
|
+
.EE
|
21
|
+
.PP
|
22
|
+
Make sure to restart your Gemstash server after changing the config:
|
23
|
+
.IP
|
24
|
+
.EX
|
25
|
+
$ gemstash stop
|
26
|
+
$ gemstash start
|
27
|
+
.EE
|
28
|
+
.PP
|
29
|
+
Once restarted, bundling against \f[CR]http://localhost:9292\f[R] will
|
30
|
+
fetch gems from \f[CR]https://my.gem-source.local\f[R].
|
31
|
+
If you had bundled before making these changes, fear not; bundling with
|
32
|
+
a different default gem source will store gems in a separate location,
|
33
|
+
ensuring different sources won\[cq]t leak between each other.
|
34
|
+
.SS Bundling with Multiple Sources
|
35
|
+
Changing the default source won\[cq]t help you if you need to bundle
|
36
|
+
against https://rubygems.org along with additional sources.
|
37
|
+
If you need to bundle with multiple gem sources, Gemstash doesn\[cq]t
|
38
|
+
need to be specially configured.
|
39
|
+
Your Gemstash server will honor any gem source specified via a
|
40
|
+
specialized URL.
|
41
|
+
Consider the following \f[CR]Gemfile\f[R]:
|
42
|
+
.IP
|
43
|
+
.EX
|
44
|
+
# ./Gemfile
|
45
|
+
require \[dq]cgi\[dq]
|
46
|
+
source \[dq]http://localhost:9292\[dq]
|
47
|
+
gem \[dq]rubywarrior\[dq]
|
48
|
+
|
49
|
+
source \[dq]http://localhost:9292/upstream/#{CGI.escape(\[dq]https://my.gem-source.local\[dq])}\[dq] do
|
50
|
+
gem \[dq]my-gem\[dq]
|
51
|
+
end
|
52
|
+
|
53
|
+
source \[dq]http://localhost:9292/upstream/my-other.gem-source.local\[dq] do
|
54
|
+
gem \[dq]my-other-gem\[dq]
|
55
|
+
end
|
56
|
+
.EE
|
57
|
+
.PP
|
58
|
+
Notice the \f[CR]CGI.escape\f[R] call in the second source.
|
59
|
+
This is important, as it properly URL escapes the source URL so Gemstash
|
60
|
+
knows what gem source you want.
|
61
|
+
The \f[CR]/upstream\f[R] prefix tells Gemstash to use a gem source other
|
62
|
+
than the default source.
|
63
|
+
You can now bundle with the additional source.
|
64
|
+
.PP
|
65
|
+
Notice that the third source doesn\[cq]t need to be escaped.
|
66
|
+
This is because the \f[CR]https://\f[R] is used by default when no
|
67
|
+
scheme is set, and the source URL does not contain any characters that
|
68
|
+
need to be escaped.
|
69
|
+
.SS Authentication with Multiple Sources
|
70
|
+
You can use basic authentication or API keys on sources directly in
|
71
|
+
Gemfile or using ENV variables on the Gemstash instance.
|
72
|
+
.PP
|
73
|
+
Example \f[CR]Gemfile\f[R]:
|
74
|
+
.IP
|
75
|
+
.EX
|
76
|
+
# ./Gemfile
|
77
|
+
require \[dq]cgi\[dq]
|
78
|
+
source \[dq]http://localhost:9292\[dq]
|
79
|
+
|
80
|
+
source \[dq]http://localhost:9292/upstream/#{CGI.escape(\[dq]user:password\[at]my.gem-source.local\[dq])}\[dq] do
|
81
|
+
gem \[dq]my-gem\[dq]
|
82
|
+
end
|
83
|
+
|
84
|
+
source \[dq]http://localhost:9292/upstream/#{CGI.escape(\[dq]api_key\[at]my-other.gem-source.local\[dq])}\[dq] do
|
85
|
+
gem \[dq]my-other-gem\[dq]
|
86
|
+
end
|
87
|
+
.EE
|
88
|
+
.PP
|
89
|
+
If you set \f[CR]GEMSTASH_<HOST>\f[R] ENV variable with your
|
90
|
+
authentication information, you can omit it from the \f[CR]Gemfile\f[R]:
|
91
|
+
.IP
|
92
|
+
.EX
|
93
|
+
# ./Gemfile
|
94
|
+
source \[dq]http://localhost:9292\[dq]
|
95
|
+
|
96
|
+
source \[dq]http://localhost:9292/upstream/my.gem-source.local\[dq] do
|
97
|
+
gem \[dq]my-gem\[dq]
|
98
|
+
end
|
99
|
+
.EE
|
100
|
+
.PP
|
101
|
+
And run the Gemstash with the credentials set in an ENV variable:
|
102
|
+
.IP
|
103
|
+
.EX
|
104
|
+
GEMSTASH_MY__GEM___SOURCE__LOCAL=user:password gemstash start --no-daemonize --config-file config.yml.erb
|
105
|
+
.EE
|
106
|
+
.PP
|
107
|
+
The name of the ENV variable is the uppercase version of the host name,
|
108
|
+
with all \f[CR].\f[R] characters replaced with \f[CR]__\f[R], all
|
109
|
+
\f[CR]-\f[R] with \f[CR]___\f[R] and a \f[CR]GEMSTASH_\f[R] prefix (it
|
110
|
+
uses the same syntax as
|
111
|
+
Bundler (https://bundler.io/v2.4/man/bundle-config.1.html#CREDENTIALS-FOR-GEM-SOURCES)).
|
112
|
+
.PP
|
113
|
+
Example: \f[CR]my.gem-source.local\f[R] =>
|
114
|
+
\f[CR]GEMSTASH_MY__GEM___SOURCE__LOCAL\f[R]
|
115
|
+
.SS Redirecting
|
116
|
+
Gemstash supports an alternate mode of specifying your gem sources.
|
117
|
+
If you want Gemstash to redirect Bundler to your given gem sources, then
|
118
|
+
you can specify your \f[CR]Gemfile\f[R] like so:
|
119
|
+
.IP
|
120
|
+
.EX
|
121
|
+
# ./Gemfile
|
122
|
+
require \[dq]cgi\[dq]
|
123
|
+
source \[dq]http://localhost:9292/redirect/#{CGI.escape(\[dq]https://rubygems.org\[dq])}\[dq]
|
124
|
+
gem \[dq]rubywarrior\[dq]
|
125
|
+
.EE
|
126
|
+
.PP
|
127
|
+
Notice the \f[CR]/redirect\f[R] prefix.
|
128
|
+
This prefix tells Gemstash to redirect API calls to the provided URL.
|
129
|
+
Redirected calls like this will not be cached by Gemstash, and gem files
|
130
|
+
will not be stashed, even if they were previously cached or stashed from
|
131
|
+
the same gem source.
|
@@ -0,0 +1,116 @@
|
|
1
|
+
4mgemstash-multiple-sources24m(7) 4mgemstash-multiple-sources24m(7)
|
2
|
+
|
3
|
+
<!-- Automatically generated by Pandoc -->
|
4
|
+
|
5
|
+
1mMultiple Gem Sources0m
|
6
|
+
Gemstash will stash from any amount of gem sources. By the end of this
|
7
|
+
guide, you will be able to bundle using multiple gem sources, all
|
8
|
+
stashed within your Gemstash server.
|
9
|
+
|
10
|
+
1mDefault Source0m
|
11
|
+
When you don't provide an explicit source (as with the Quickstart
|
12
|
+
Guide), your gems will be fetched from https://rubygems.org. This de-
|
13
|
+
fault source is not set in stone. To change it, you need only edit the
|
14
|
+
Gemstash configuration found at ~/.gemstash/config.yml:
|
15
|
+
|
16
|
+
# ~/.gemstash/config.yml
|
17
|
+
---
|
18
|
+
:rubygems_url: https://my.gem-source.local
|
19
|
+
|
20
|
+
Make sure to restart your Gemstash server after changing the config:
|
21
|
+
|
22
|
+
$ gemstash stop
|
23
|
+
$ gemstash start
|
24
|
+
|
25
|
+
Once restarted, bundling against http://localhost:9292 will fetch gems
|
26
|
+
from https://my.gem-source.local. If you had bundled before making
|
27
|
+
these changes, fear not; bundling with a different default gem source
|
28
|
+
will store gems in a separate location, ensuring different sources
|
29
|
+
won't leak between each other.
|
30
|
+
|
31
|
+
1mBundling with Multiple Sources0m
|
32
|
+
Changing the default source won't help you if you need to bundle
|
33
|
+
against https://rubygems.org along with additional sources. If you
|
34
|
+
need to bundle with multiple gem sources, Gemstash doesn't need to be
|
35
|
+
specially configured. Your Gemstash server will honor any gem source
|
36
|
+
specified via a specialized URL. Consider the following Gemfile:
|
37
|
+
|
38
|
+
# ./Gemfile
|
39
|
+
require "cgi"
|
40
|
+
source "http://localhost:9292"
|
41
|
+
gem "rubywarrior"
|
42
|
+
|
43
|
+
source "http://localhost:9292/upstream/#{CGI.escape("https://my.gem-source.local")}" do
|
44
|
+
gem "my-gem"
|
45
|
+
end
|
46
|
+
|
47
|
+
source "http://localhost:9292/upstream/my-other.gem-source.local" do
|
48
|
+
gem "my-other-gem"
|
49
|
+
end
|
50
|
+
|
51
|
+
Notice the CGI.escape call in the second source. This is important, as
|
52
|
+
it properly URL escapes the source URL so Gemstash knows what gem
|
53
|
+
source you want. The /upstream prefix tells Gemstash to use a gem
|
54
|
+
source other than the default source. You can now bundle with the ad-
|
55
|
+
ditional source.
|
56
|
+
|
57
|
+
Notice that the third source doesn't need to be escaped. This is be-
|
58
|
+
cause the https:// is used by default when no scheme is set, and the
|
59
|
+
source URL does not contain any characters that need to be escaped.
|
60
|
+
|
61
|
+
1mAuthentication with Multiple Sources0m
|
62
|
+
You can use basic authentication or API keys on sources directly in
|
63
|
+
Gemfile or using ENV variables on the Gemstash instance.
|
64
|
+
|
65
|
+
Example Gemfile:
|
66
|
+
|
67
|
+
# ./Gemfile
|
68
|
+
require "cgi"
|
69
|
+
source "http://localhost:9292"
|
70
|
+
|
71
|
+
source "http://localhost:9292/upstream/#{CGI.escape("user:password@my.gem-source.local")}" do
|
72
|
+
gem "my-gem"
|
73
|
+
end
|
74
|
+
|
75
|
+
source "http://localhost:9292/upstream/#{CGI.escape("api_key@my-other.gem-source.local")}" do
|
76
|
+
gem "my-other-gem"
|
77
|
+
end
|
78
|
+
|
79
|
+
If you set GEMSTASH_<HOST> ENV variable with your authentication infor-
|
80
|
+
mation, you can omit it from the Gemfile:
|
81
|
+
|
82
|
+
# ./Gemfile
|
83
|
+
source "http://localhost:9292"
|
84
|
+
|
85
|
+
source "http://localhost:9292/upstream/my.gem-source.local" do
|
86
|
+
gem "my-gem"
|
87
|
+
end
|
88
|
+
|
89
|
+
And run the Gemstash with the credentials set in an ENV variable:
|
90
|
+
|
91
|
+
GEMSTASH_MY__GEM___SOURCE__LOCAL=user:password gemstash start --no-daemonize --config-file config.yml.erb
|
92
|
+
|
93
|
+
The name of the ENV variable is the uppercase version of the host name,
|
94
|
+
with all . characters replaced with __, all - with ___ and a GEMSTASH_
|
95
|
+
prefix (it uses the same syntax as Bundler
|
96
|
+
(https://bundler.io/v2.4/man/bundle-config.1.html#CREDENTIALS-FOR-GEM-
|
97
|
+
SOURCES)).
|
98
|
+
|
99
|
+
Example: my.gem-source.local => GEMSTASH_MY__GEM___SOURCE__LOCAL
|
100
|
+
|
101
|
+
1mRedirecting0m
|
102
|
+
Gemstash supports an alternate mode of specifying your gem sources. If
|
103
|
+
you want Gemstash to redirect Bundler to your given gem sources, then
|
104
|
+
you can specify your Gemfile like so:
|
105
|
+
|
106
|
+
# ./Gemfile
|
107
|
+
require "cgi"
|
108
|
+
source "http://localhost:9292/redirect/#{CGI.escape("https://rubygems.org")}"
|
109
|
+
gem "rubywarrior"
|
110
|
+
|
111
|
+
Notice the /redirect prefix. This prefix tells Gemstash to redirect
|
112
|
+
API calls to the provided URL. Redirected calls like this will not be
|
113
|
+
cached by Gemstash, and gem files will not be stashed, even if they
|
114
|
+
were previously cached or stashed from the same gem source.
|
115
|
+
|
116
|
+
October 8, 2015 4mgemstash-multiple-sources24m(7)
|
@@ -0,0 +1,191 @@
|
|
1
|
+
<!-- Automatically generated by Pandoc -->
|
2
|
+
.\" Automatically generated by Pandoc 3.1.8
|
3
|
+
.\"
|
4
|
+
.TH "gemstash-private-gems" "7" "October 8, 2015" "" ""
|
5
|
+
.SH Private Gems
|
6
|
+
Stashing private gems in your Gemstash server requires a bit of
|
7
|
+
additional setup.
|
8
|
+
If you haven\[cq]t read through the Quickstart Guide, you should do that
|
9
|
+
first.
|
10
|
+
By the end of this guide, you will be able to interact with your
|
11
|
+
Gemstash server to store and retrieve your private gems.
|
12
|
+
.SS Authorizing
|
13
|
+
\f[B]IMPORTANT NOTE:\f[R] Do not use the actual key value in this
|
14
|
+
document, otherwise your Gemstash server will be vulnerable to anyone
|
15
|
+
who wants to try to use the key against your server.
|
16
|
+
Instead of the key value here, use whatever key is generated from
|
17
|
+
running the commands.
|
18
|
+
.PP
|
19
|
+
In order to push a gem to your Gemstash server, you need to first create
|
20
|
+
an API key.
|
21
|
+
Utilize the \f[CR]gemstash authorize\f[R] command to create the API key:
|
22
|
+
.IP
|
23
|
+
.EX
|
24
|
+
$ gemstash authorize
|
25
|
+
Your new key is: e374e237fdf5fa5718d2a21bd63dc911
|
26
|
+
.EE
|
27
|
+
.PP
|
28
|
+
This new key can \f[CR]push\f[R], \f[CR]yank\f[R], and \f[CR]fetch\f[R]
|
29
|
+
gems from your Gemstash server.
|
30
|
+
Run \f[CR]gemstash authorize\f[R] with just the permissions you want to
|
31
|
+
limit what the key will be allowed to do.
|
32
|
+
You can similarly update a specific key by providing it via the
|
33
|
+
\f[CR]--key\f[R] option:
|
34
|
+
.IP
|
35
|
+
.EX
|
36
|
+
$ gemstash authorize push yank --key e374e237fdf5fa5718d2a21bd63dc911
|
37
|
+
.EE
|
38
|
+
.PP
|
39
|
+
When no permissions are provided (like the first example), the key will
|
40
|
+
be authorized for all permissions.
|
41
|
+
Leave the key authorized with everything if you want to use it to try
|
42
|
+
all private gem interactions:
|
43
|
+
.IP
|
44
|
+
.EX
|
45
|
+
$ gemstash authorize --key e374e237fdf5fa5718d2a21bd63dc911
|
46
|
+
.EE
|
47
|
+
.PP
|
48
|
+
With the key generated, you\[cq]ll need to tell Rubygems about your new
|
49
|
+
key.
|
50
|
+
If you\[cq]ve pushed a gem to https://rubygems.org, then you will
|
51
|
+
already have a credentials file to add the key to.
|
52
|
+
If not, run the following commands before modifying the credentials
|
53
|
+
file:
|
54
|
+
.IP
|
55
|
+
.EX
|
56
|
+
$ mkdir -p \[ti]/.gem
|
57
|
+
$ touch \[ti]/.gem/credentials
|
58
|
+
$ chmod 0600 \[ti]/.gem/credentials
|
59
|
+
.EE
|
60
|
+
.PP
|
61
|
+
Add your new key to credentials such that it looks something like this
|
62
|
+
(but make sure not to remove any existing keys):
|
63
|
+
.IP
|
64
|
+
.EX
|
65
|
+
# \[ti]/.gem/credentials
|
66
|
+
---
|
67
|
+
:test_key: e374e237fdf5fa5718d2a21bd63dc911
|
68
|
+
.EE
|
69
|
+
.PP
|
70
|
+
The name \f[CR]test_key\f[R] can be anything you want, but you will need
|
71
|
+
to remember it and use it again later in this guide for the
|
72
|
+
\f[CR]--key\f[R] option.
|
73
|
+
.SS Creating a Test Gem
|
74
|
+
You\[cq]ll need a test gem before you can play with private gems on your
|
75
|
+
Gemstash server.
|
76
|
+
If you have a gem you can use, move along to the next section.
|
77
|
+
You can start by instantiating a test gem via Bundler:
|
78
|
+
.IP
|
79
|
+
.EX
|
80
|
+
$ bundle gem private-example
|
81
|
+
.EE
|
82
|
+
.PP
|
83
|
+
You\[cq]ll need to add a summary and description to the new gem\[cq]s
|
84
|
+
gemspec file in order to successfully build it.
|
85
|
+
Once you\[cq]ve built the gem, you will be ready to push the new gem.
|
86
|
+
.IP
|
87
|
+
.EX
|
88
|
+
$ cd private-example
|
89
|
+
$ rake build
|
90
|
+
.EE
|
91
|
+
.PP
|
92
|
+
You will now have a gem at
|
93
|
+
\f[CR]private-example/pkg/private-example-0.1.0.gem\f[R].
|
94
|
+
.SS Pushing
|
95
|
+
If your Gemstash server isn\[cq]t running, go ahead and start it:
|
96
|
+
.IP
|
97
|
+
.EX
|
98
|
+
$ gemstash start
|
99
|
+
.EE
|
100
|
+
.PP
|
101
|
+
Push your test gem using Rubygems:
|
102
|
+
.IP
|
103
|
+
.EX
|
104
|
+
$ gem push --key test_key --host http://localhost:9292/private pkg/private-example-0.1.0.gem
|
105
|
+
.EE
|
106
|
+
.PP
|
107
|
+
The \f[CR]/private\f[R] portion of the \f[CR]--host\f[R] option tells
|
108
|
+
Gemstash you are interacting with the private gems.
|
109
|
+
Gemstash will not let you push, or yank from anything except
|
110
|
+
\f[CR]/private\f[R].
|
111
|
+
.SS Bundling
|
112
|
+
Once your gem is pushed to your Gemstash server, you are ready to bundle
|
113
|
+
it.
|
114
|
+
Create a \f[CR]Gemfile\f[R] and specify the gem.
|
115
|
+
You will probably want to wrap the private gem in a source block, and
|
116
|
+
let the rest of Gemstash handle all other gems:
|
117
|
+
.IP
|
118
|
+
.EX
|
119
|
+
# ./Gemfile
|
120
|
+
source \[dq]http://localhost:9292\[dq]
|
121
|
+
gem \[dq]rubywarrior\[dq]
|
122
|
+
|
123
|
+
source \[dq]http://localhost:9292/private\[dq] do
|
124
|
+
gem \[dq]private-example\[dq]
|
125
|
+
end
|
126
|
+
.EE
|
127
|
+
.PP
|
128
|
+
Notice that the Gemstash server points to \f[CR]/private\f[R] again when
|
129
|
+
installing your private gem.
|
130
|
+
Go ahead and bundle to install your new private gem:
|
131
|
+
.IP
|
132
|
+
.EX
|
133
|
+
$ bundle
|
134
|
+
.EE
|
135
|
+
.SS Yanking
|
136
|
+
If you push a private gem by accident, you can yank the gem with
|
137
|
+
Rubygems:
|
138
|
+
.IP
|
139
|
+
.EX
|
140
|
+
$ RUBYGEMS_HOST=http://localhost:9292/private gem yank --key test_key private-example --version 0.1.0
|
141
|
+
.EE
|
142
|
+
.PP
|
143
|
+
Like with pushing, the \f[CR]/private\f[R] portion of the host option
|
144
|
+
tells Gemstash you are interacting with private gems.
|
145
|
+
Gemstash will only let you yank from \f[CR]/private\f[R].
|
146
|
+
Unlike pushing, Rubygems doesn\[cq]t support \f[CR]--host\f[R] for yank
|
147
|
+
(yet), so you need to specify the host via the \f[CR]RUBYGEMS_HOST\f[R]
|
148
|
+
environment variable.
|
149
|
+
.SS Protected Fetching
|
150
|
+
By default, private gems and specs can be accessed without
|
151
|
+
authentication.
|
152
|
+
.PP
|
153
|
+
Private gems often require protected fetching.
|
154
|
+
For backwards compatibility this is disabled by default, but can be
|
155
|
+
enabled via \f[CR]$ gemstash setup\f[R] command.
|
156
|
+
.PP
|
157
|
+
When protected fetching is enabled API keys with the permissions
|
158
|
+
\f[CR]all\f[R] or \f[CR]fetch\f[R] can be used to download gems and
|
159
|
+
specs.
|
160
|
+
.PP
|
161
|
+
On the Bundler side, there are a few ways to configure credentials for a
|
162
|
+
given gem source:
|
163
|
+
.PP
|
164
|
+
Add credentials globally:
|
165
|
+
.IP
|
166
|
+
.EX
|
167
|
+
$ bundle config my-gemstash.dev api_key
|
168
|
+
.EE
|
169
|
+
.PP
|
170
|
+
Add credentials in Gemfile:
|
171
|
+
.IP
|
172
|
+
.EX
|
173
|
+
source \[dq]https://api_key\[at]my-gemstash.dev\[dq]
|
174
|
+
.EE
|
175
|
+
.PP
|
176
|
+
However, it\[cq]s not a good practice to commit credentials to source
|
177
|
+
control.
|
178
|
+
A recommended solution is to use Bundler\[cq]s configuration
|
179
|
+
keys (http://bundler.io/man/bundle-config.1.html#CONFIGURATION-KEYS),
|
180
|
+
e.g.:
|
181
|
+
.IP
|
182
|
+
.EX
|
183
|
+
$ export BUNDLE_MYGEMSTASH__DEV=api_key
|
184
|
+
.EE
|
185
|
+
.PP
|
186
|
+
Behind the scene, Bundler will pick up the ENV var according to the host
|
187
|
+
name (e.g.\ mygemstash.dev) and add to \f[CR]URI.userinfo\f[R] for
|
188
|
+
making requests.
|
189
|
+
.PP
|
190
|
+
The API key is treated as a HTTP Basic Auth username and any HTTP Basic
|
191
|
+
password supplied will be ignored.
|
@@ -0,0 +1,154 @@
|
|
1
|
+
4mgemstash-private-gems24m(7) 4mgemstash-private-gems24m(7)
|
2
|
+
|
3
|
+
<!-- Automatically generated by Pandoc -->
|
4
|
+
|
5
|
+
1mPrivate Gems0m
|
6
|
+
Stashing private gems in your Gemstash server requires a bit of addi-
|
7
|
+
tional setup. If you haven't read through the Quickstart Guide, you
|
8
|
+
should do that first. By the end of this guide, you will be able to
|
9
|
+
interact with your Gemstash server to store and retrieve your private
|
10
|
+
gems.
|
11
|
+
|
12
|
+
1mAuthorizing0m
|
13
|
+
1mIMPORTANT NOTE: 22mDo not use the actual key value in this document, oth-
|
14
|
+
erwise your Gemstash server will be vulnerable to anyone who wants to
|
15
|
+
try to use the key against your server. Instead of the key value here,
|
16
|
+
use whatever key is generated from running the commands.
|
17
|
+
|
18
|
+
In order to push a gem to your Gemstash server, you need to first cre-
|
19
|
+
ate an API key. Utilize the gemstash authorize command to create the
|
20
|
+
API key:
|
21
|
+
|
22
|
+
$ gemstash authorize
|
23
|
+
Your new key is: e374e237fdf5fa5718d2a21bd63dc911
|
24
|
+
|
25
|
+
This new key can push, yank, and fetch gems from your Gemstash server.
|
26
|
+
Run gemstash authorize with just the permissions you want to limit what
|
27
|
+
the key will be allowed to do. You can similarly update a specific key
|
28
|
+
by providing it via the --key option:
|
29
|
+
|
30
|
+
$ gemstash authorize push yank --key e374e237fdf5fa5718d2a21bd63dc911
|
31
|
+
|
32
|
+
When no permissions are provided (like the first example), the key will
|
33
|
+
be authorized for all permissions. Leave the key authorized with
|
34
|
+
everything if you want to use it to try all private gem interactions:
|
35
|
+
|
36
|
+
$ gemstash authorize --key e374e237fdf5fa5718d2a21bd63dc911
|
37
|
+
|
38
|
+
With the key generated, you'll need to tell Rubygems about your new
|
39
|
+
key. If you've pushed a gem to https://rubygems.org, then you will al-
|
40
|
+
ready have a credentials file to add the key to. If not, run the fol-
|
41
|
+
lowing commands before modifying the credentials file:
|
42
|
+
|
43
|
+
$ mkdir -p ~/.gem
|
44
|
+
$ touch ~/.gem/credentials
|
45
|
+
$ chmod 0600 ~/.gem/credentials
|
46
|
+
|
47
|
+
Add your new key to credentials such that it looks something like this
|
48
|
+
(but make sure not to remove any existing keys):
|
49
|
+
|
50
|
+
# ~/.gem/credentials
|
51
|
+
---
|
52
|
+
:test_key: e374e237fdf5fa5718d2a21bd63dc911
|
53
|
+
|
54
|
+
The name test_key can be anything you want, but you will need to remem-
|
55
|
+
ber it and use it again later in this guide for the --key option.
|
56
|
+
|
57
|
+
1mCreating a Test Gem0m
|
58
|
+
You'll need a test gem before you can play with private gems on your
|
59
|
+
Gemstash server. If you have a gem you can use, move along to the next
|
60
|
+
section. You can start by instantiating a test gem via Bundler:
|
61
|
+
|
62
|
+
$ bundle gem private-example
|
63
|
+
|
64
|
+
You'll need to add a summary and description to the new gem's gemspec
|
65
|
+
file in order to successfully build it. Once you've built the gem, you
|
66
|
+
will be ready to push the new gem.
|
67
|
+
|
68
|
+
$ cd private-example
|
69
|
+
$ rake build
|
70
|
+
|
71
|
+
You will now have a gem at private-example/pkg/private-exam-
|
72
|
+
ple-0.1.0.gem.
|
73
|
+
|
74
|
+
1mPushing0m
|
75
|
+
If your Gemstash server isn't running, go ahead and start it:
|
76
|
+
|
77
|
+
$ gemstash start
|
78
|
+
|
79
|
+
Push your test gem using Rubygems:
|
80
|
+
|
81
|
+
$ gem push --key test_key --host http://localhost:9292/private pkg/private-example-0.1.0.gem
|
82
|
+
|
83
|
+
The /private portion of the --host option tells Gemstash you are inter-
|
84
|
+
acting with the private gems. Gemstash will not let you push, or yank
|
85
|
+
from anything except /private.
|
86
|
+
|
87
|
+
1mBundling0m
|
88
|
+
Once your gem is pushed to your Gemstash server, you are ready to bun-
|
89
|
+
dle it. Create a Gemfile and specify the gem. You will probably want
|
90
|
+
to wrap the private gem in a source block, and let the rest of Gemstash
|
91
|
+
handle all other gems:
|
92
|
+
|
93
|
+
# ./Gemfile
|
94
|
+
source "http://localhost:9292"
|
95
|
+
gem "rubywarrior"
|
96
|
+
|
97
|
+
source "http://localhost:9292/private" do
|
98
|
+
gem "private-example"
|
99
|
+
end
|
100
|
+
|
101
|
+
Notice that the Gemstash server points to /private again when in-
|
102
|
+
stalling your private gem. Go ahead and bundle to install your new
|
103
|
+
private gem:
|
104
|
+
|
105
|
+
$ bundle
|
106
|
+
|
107
|
+
1mYanking0m
|
108
|
+
If you push a private gem by accident, you can yank the gem with
|
109
|
+
Rubygems:
|
110
|
+
|
111
|
+
$ RUBYGEMS_HOST=http://localhost:9292/private gem yank --key test_key private-example --version 0.1.0
|
112
|
+
|
113
|
+
Like with pushing, the /private portion of the host option tells Gem-
|
114
|
+
stash you are interacting with private gems. Gemstash will only let
|
115
|
+
you yank from /private. Unlike pushing, Rubygems doesn't support
|
116
|
+
--host for yank (yet), so you need to specify the host via the
|
117
|
+
RUBYGEMS_HOST environment variable.
|
118
|
+
|
119
|
+
1mProtected Fetching0m
|
120
|
+
By default, private gems and specs can be accessed without authentica-
|
121
|
+
tion.
|
122
|
+
|
123
|
+
Private gems often require protected fetching. For backwards compati-
|
124
|
+
bility this is disabled by default, but can be enabled via $ gemstash
|
125
|
+
setup command.
|
126
|
+
|
127
|
+
When protected fetching is enabled API keys with the permissions all or
|
128
|
+
fetch can be used to download gems and specs.
|
129
|
+
|
130
|
+
On the Bundler side, there are a few ways to configure credentials for
|
131
|
+
a given gem source:
|
132
|
+
|
133
|
+
Add credentials globally:
|
134
|
+
|
135
|
+
$ bundle config my-gemstash.dev api_key
|
136
|
+
|
137
|
+
Add credentials in Gemfile:
|
138
|
+
|
139
|
+
source "https://api_key@my-gemstash.dev"
|
140
|
+
|
141
|
+
However, it's not a good practice to commit credentials to source con-
|
142
|
+
trol. A recommended solution is to use Bundler's configuration keys
|
143
|
+
(http://bundler.io/man/bundle-config.1.html#CONFIGURATION-KEYS), e.g.:
|
144
|
+
|
145
|
+
$ export BUNDLE_MYGEMSTASH__DEV=api_key
|
146
|
+
|
147
|
+
Behind the scene, Bundler will pick up the ENV var according to the
|
148
|
+
host name (e.g. mygemstash.dev) and add to URI.userinfo for making re-
|
149
|
+
quests.
|
150
|
+
|
151
|
+
The API key is treated as a HTTP Basic Auth username and any HTTP Basic
|
152
|
+
password supplied will be ignored.
|
153
|
+
|
154
|
+
October 8, 2015 4mgemstash-private-gems24m(7)
|