gemstash 2.1.0 → 2.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +57 -0
- data/lib/gemstash/cache.rb +37 -0
- data/lib/gemstash/cli/authorize.rb +2 -2
- data/lib/gemstash/cli/setup.rb +11 -3
- data/lib/gemstash/configuration.rb +1 -1
- data/lib/gemstash/dependencies.rb +2 -2
- data/lib/gemstash/env.rb +2 -0
- data/lib/gemstash/gem_fetcher.rb +2 -2
- data/lib/gemstash/gem_pusher.rb +2 -2
- data/lib/gemstash/gem_source/private_source.rb +3 -3
- data/lib/gemstash/gem_source.rb +2 -2
- data/lib/gemstash/http_client.rb +8 -3
- data/lib/gemstash/logging.rb +1 -1
- data/lib/gemstash/man/gemstash-authorize.1 +36 -21
- data/lib/gemstash/man/gemstash-authorize.1.txt +21 -19
- data/lib/gemstash/man/gemstash-configuration.5 +118 -106
- data/lib/gemstash/man/gemstash-configuration.5.txt +105 -103
- data/lib/gemstash/man/gemstash-customize.7 +83 -68
- data/lib/gemstash/man/gemstash-customize.7.txt +63 -62
- data/lib/gemstash/man/gemstash-debugging.7 +24 -9
- data/lib/gemstash/man/gemstash-debugging.7.txt +11 -9
- data/lib/gemstash/man/gemstash-deploy.7 +30 -15
- data/lib/gemstash/man/gemstash-deploy.7.txt +18 -16
- data/lib/gemstash/man/gemstash-mirror.7 +25 -10
- data/lib/gemstash/man/gemstash-mirror.7.txt +9 -7
- data/lib/gemstash/man/gemstash-multiple-sources.7 +34 -20
- data/lib/gemstash/man/gemstash-multiple-sources.7.txt +30 -29
- data/lib/gemstash/man/gemstash-private-gems.7 +55 -40
- data/lib/gemstash/man/gemstash-private-gems.7.txt +40 -38
- data/lib/gemstash/man/gemstash-readme.7 +61 -49
- data/lib/gemstash/man/gemstash-readme.7.txt +58 -58
- data/lib/gemstash/man/gemstash-setup.1 +36 -21
- data/lib/gemstash/man/gemstash-setup.1.txt +19 -17
- data/lib/gemstash/man/gemstash-start.1 +29 -14
- data/lib/gemstash/man/gemstash-start.1.txt +14 -12
- data/lib/gemstash/man/gemstash-status.1 +27 -12
- data/lib/gemstash/man/gemstash-status.1.txt +12 -10
- data/lib/gemstash/man/gemstash-stop.1 +27 -12
- data/lib/gemstash/man/gemstash-stop.1.txt +12 -10
- data/lib/gemstash/man/gemstash-version.1 +25 -10
- data/lib/gemstash/man/gemstash-version.1.txt +7 -5
- data/lib/gemstash/storage.rb +5 -4
- data/lib/gemstash/upstream.rb +6 -5
- data/lib/gemstash/version.rb +2 -2
- data/lib/gemstash/web.rb +6 -4
- data/lib/gemstash.rb +1 -1
- metadata +31 -157
@@ -1,16 +1,31 @@
|
|
1
|
-
|
1
|
+
<!-- Automatically generated by Pandoc -->
|
2
|
+
.\" Automatically generated by Pandoc 3.0.1
|
2
3
|
.\"
|
3
|
-
|
4
|
+
.\" Define V font for inline verbatim, using C font in formats
|
5
|
+
.\" that render this, and otherwise B font.
|
6
|
+
.ie "\f[CB]x\f[]"x" \{\
|
7
|
+
. ftr V B
|
8
|
+
. ftr VI BI
|
9
|
+
. ftr VB B
|
10
|
+
. ftr VBI BI
|
11
|
+
.\}
|
12
|
+
.el \{\
|
13
|
+
. ftr V CR
|
14
|
+
. ftr VI CI
|
15
|
+
. ftr VB CB
|
16
|
+
. ftr VBI CBI
|
17
|
+
.\}
|
18
|
+
.TH "gemstash-private-gems" "7" "October 8, 2015" "" ""
|
4
19
|
.hy
|
5
|
-
.SH
|
20
|
+
.SH Private Gems
|
6
21
|
.PP
|
7
22
|
Stashing private gems in your Gemstash server requires a bit of
|
8
23
|
additional setup.
|
9
|
-
If you haven\[cq]t read through the Quickstart
|
10
|
-
|
24
|
+
If you haven\[cq]t read through the Quickstart Guide, you should do that
|
25
|
+
first.
|
11
26
|
By the end of this guide, you will be able to interact with your
|
12
27
|
Gemstash server to store and retrieve your private gems.
|
13
|
-
.SS
|
28
|
+
.SS Authorizing
|
14
29
|
.PP
|
15
30
|
\f[B]IMPORTANT NOTE:\f[R] Do not use the actual key value in this
|
16
31
|
document, otherwise your Gemstash server will be vulnerable to anyone
|
@@ -20,7 +35,7 @@ running the commands.
|
|
20
35
|
.PP
|
21
36
|
In order to push a gem to your Gemstash server, you need to first create
|
22
37
|
an API key.
|
23
|
-
Utilize the \f[
|
38
|
+
Utilize the \f[V]gemstash authorize\f[R] command to create the API key:
|
24
39
|
.IP
|
25
40
|
.nf
|
26
41
|
\f[C]
|
@@ -29,16 +44,16 @@ Your new key is: e374e237fdf5fa5718d2a21bd63dc911
|
|
29
44
|
\f[R]
|
30
45
|
.fi
|
31
46
|
.PP
|
32
|
-
This new key can \f[
|
47
|
+
This new key can \f[V]push\f[R], \f[V]yank\f[R], and \f[V]fetch\f[R]
|
33
48
|
gems from your Gemstash server.
|
34
|
-
Run \f[
|
49
|
+
Run \f[V]gemstash authorize\f[R] with just the permissions you want to
|
35
50
|
limit what the key will be allowed to do.
|
36
51
|
You can similarly update a specific key by providing it via the
|
37
|
-
\f[
|
52
|
+
\f[V]--key\f[R] option:
|
38
53
|
.IP
|
39
54
|
.nf
|
40
55
|
\f[C]
|
41
|
-
$ gemstash authorize push yank
|
56
|
+
$ gemstash authorize push yank --key e374e237fdf5fa5718d2a21bd63dc911
|
42
57
|
\f[R]
|
43
58
|
.fi
|
44
59
|
.PP
|
@@ -49,7 +64,7 @@ all private gem interactions:
|
|
49
64
|
.IP
|
50
65
|
.nf
|
51
66
|
\f[C]
|
52
|
-
$ gemstash authorize
|
67
|
+
$ gemstash authorize --key e374e237fdf5fa5718d2a21bd63dc911
|
53
68
|
\f[R]
|
54
69
|
.fi
|
55
70
|
.PP
|
@@ -62,7 +77,7 @@ file:
|
|
62
77
|
.IP
|
63
78
|
.nf
|
64
79
|
\f[C]
|
65
|
-
$ mkdir
|
80
|
+
$ mkdir -p \[ti]/.gem
|
66
81
|
$ touch \[ti]/.gem/credentials
|
67
82
|
$ chmod 0600 \[ti]/.gem/credentials
|
68
83
|
\f[R]
|
@@ -74,15 +89,15 @@ Add your new key to credentials such that it looks something like this
|
|
74
89
|
.nf
|
75
90
|
\f[C]
|
76
91
|
# \[ti]/.gem/credentials
|
77
|
-
|
92
|
+
---
|
78
93
|
:test_key: e374e237fdf5fa5718d2a21bd63dc911
|
79
94
|
\f[R]
|
80
95
|
.fi
|
81
96
|
.PP
|
82
|
-
The name \f[
|
97
|
+
The name \f[V]test_key\f[R] can be anything you want, but you will need
|
83
98
|
to remember it and use it again later in this guide for the
|
84
|
-
\f[
|
85
|
-
.SS
|
99
|
+
\f[V]--key\f[R] option.
|
100
|
+
.SS Creating a Test Gem
|
86
101
|
.PP
|
87
102
|
You\[cq]ll need a test gem before you can play with private gems on your
|
88
103
|
Gemstash server.
|
@@ -91,7 +106,7 @@ You can start by instantiating a test gem via Bundler:
|
|
91
106
|
.IP
|
92
107
|
.nf
|
93
108
|
\f[C]
|
94
|
-
$ bundle gem private
|
109
|
+
$ bundle gem private-example
|
95
110
|
\f[R]
|
96
111
|
.fi
|
97
112
|
.PP
|
@@ -101,14 +116,14 @@ Once you\[cq]ve built the gem, you will be ready to push the new gem.
|
|
101
116
|
.IP
|
102
117
|
.nf
|
103
118
|
\f[C]
|
104
|
-
$ cd private
|
119
|
+
$ cd private-example
|
105
120
|
$ rake build
|
106
121
|
\f[R]
|
107
122
|
.fi
|
108
123
|
.PP
|
109
124
|
You will now have a gem at
|
110
|
-
\f[
|
111
|
-
.SS
|
125
|
+
\f[V]private-example/pkg/private-example-0.1.0.gem\f[R].
|
126
|
+
.SS Pushing
|
112
127
|
.PP
|
113
128
|
If your Gemstash server isn\[cq]t running, go ahead and start it:
|
114
129
|
.IP
|
@@ -122,19 +137,19 @@ Push your test gem using Rubygems:
|
|
122
137
|
.IP
|
123
138
|
.nf
|
124
139
|
\f[C]
|
125
|
-
$ gem push
|
140
|
+
$ gem push --key test_key --host http://localhost:9292/private pkg/private-example-0.1.0.gem
|
126
141
|
\f[R]
|
127
142
|
.fi
|
128
143
|
.PP
|
129
|
-
The \f[
|
144
|
+
The \f[V]/private\f[R] portion of the \f[V]--host\f[R] option tells
|
130
145
|
Gemstash you are interacting with the private gems.
|
131
146
|
Gemstash will not let you push, or yank from anything except
|
132
|
-
\f[
|
133
|
-
.SS
|
147
|
+
\f[V]/private\f[R].
|
148
|
+
.SS Bundling
|
134
149
|
.PP
|
135
150
|
Once your gem is pushed to your Gemstash server, you are ready to bundle
|
136
151
|
it.
|
137
|
-
Create a \f[
|
152
|
+
Create a \f[V]Gemfile\f[R] and specify the gem.
|
138
153
|
You will probably want to wrap the private gem in a source block, and
|
139
154
|
let the rest of Gemstash handle all other gems:
|
140
155
|
.IP
|
@@ -145,12 +160,12 @@ source \[dq]http://localhost:9292\[dq]
|
|
145
160
|
gem \[dq]rubywarrior\[dq]
|
146
161
|
|
147
162
|
source \[dq]http://localhost:9292/private\[dq] do
|
148
|
-
gem \[dq]private
|
163
|
+
gem \[dq]private-example\[dq]
|
149
164
|
end
|
150
165
|
\f[R]
|
151
166
|
.fi
|
152
167
|
.PP
|
153
|
-
Notice that the Gemstash server points to \f[
|
168
|
+
Notice that the Gemstash server points to \f[V]/private\f[R] again when
|
154
169
|
installing your private gem.
|
155
170
|
Go ahead and bundle to install your new private gem:
|
156
171
|
.IP
|
@@ -159,34 +174,34 @@ Go ahead and bundle to install your new private gem:
|
|
159
174
|
$ bundle
|
160
175
|
\f[R]
|
161
176
|
.fi
|
162
|
-
.SS
|
177
|
+
.SS Yanking
|
163
178
|
.PP
|
164
179
|
If you push a private gem by accident, you can yank the gem with
|
165
180
|
Rubygems:
|
166
181
|
.IP
|
167
182
|
.nf
|
168
183
|
\f[C]
|
169
|
-
$ RUBYGEMS_HOST=http://localhost:9292/private gem yank
|
184
|
+
$ RUBYGEMS_HOST=http://localhost:9292/private gem yank --key test_key private-example --version 0.1.0
|
170
185
|
\f[R]
|
171
186
|
.fi
|
172
187
|
.PP
|
173
|
-
Like with pushing, the \f[
|
188
|
+
Like with pushing, the \f[V]/private\f[R] portion of the host option
|
174
189
|
tells Gemstash you are interacting with private gems.
|
175
|
-
Gemstash will only let you yank from \f[
|
176
|
-
Unlike pushing, Rubygems doesn\[cq]t support \f[
|
177
|
-
(yet), so you need to specify the host via the \f[
|
190
|
+
Gemstash will only let you yank from \f[V]/private\f[R].
|
191
|
+
Unlike pushing, Rubygems doesn\[cq]t support \f[V]--host\f[R] for yank
|
192
|
+
(yet), so you need to specify the host via the \f[V]RUBYGEMS_HOST\f[R]
|
178
193
|
environment variable.
|
179
|
-
.SS
|
194
|
+
.SS Protected Fetching
|
180
195
|
.PP
|
181
196
|
By default, private gems and specs can be accessed without
|
182
197
|
authentication.
|
183
198
|
.PP
|
184
199
|
Private gems often require protected fetching.
|
185
200
|
For backwards compatibility this is disabled by default, but can be
|
186
|
-
enabled via \f[
|
201
|
+
enabled via \f[V]$ gemstash setup\f[R] command.
|
187
202
|
.PP
|
188
203
|
When protected fetching is enabled API keys with the permissions
|
189
|
-
\f[
|
204
|
+
\f[V]all\f[R] or \f[V]fetch\f[R] can be used to download gems and specs.
|
190
205
|
.PP
|
191
206
|
On the Bundler side, there are a few ways to configure credentials for a
|
192
207
|
given gem source:
|
@@ -195,7 +210,7 @@ Add credentials globally:
|
|
195
210
|
.IP
|
196
211
|
.nf
|
197
212
|
\f[C]
|
198
|
-
$ bundle config my
|
213
|
+
$ bundle config my-gemstash.dev api_key
|
199
214
|
\f[R]
|
200
215
|
.fi
|
201
216
|
.PP
|
@@ -203,7 +218,7 @@ Add credentials in Gemfile:
|
|
203
218
|
.IP
|
204
219
|
.nf
|
205
220
|
\f[C]
|
206
|
-
source \[dq]https://api_key\[at]my
|
221
|
+
source \[dq]https://api_key\[at]my-gemstash.dev\[dq]
|
207
222
|
\f[R]
|
208
223
|
.fi
|
209
224
|
.PP
|
@@ -220,7 +235,7 @@ $ export BUNDLE_MYGEMSTASH__DEV=api_key
|
|
220
235
|
.fi
|
221
236
|
.PP
|
222
237
|
Behind the scene, Bundler will pick up the ENV var according to the host
|
223
|
-
name (e.g.\ mygemstash.dev) and add to \f[
|
238
|
+
name (e.g.\ mygemstash.dev) and add to \f[V]URI.userinfo\f[R] for making
|
224
239
|
requests.
|
225
240
|
.PP
|
226
241
|
The API key is treated as a HTTP Basic Auth username and any HTTP Basic
|
@@ -2,30 +2,32 @@ gemstash-private-gems(7) gemstash-private-gems(7)
|
|
2
2
|
|
3
3
|
|
4
4
|
|
5
|
-
|
6
|
-
|
7
|
-
|
8
|
-
|
9
|
-
|
10
|
-
|
11
|
-
|
12
|
-
|
5
|
+
<!-- Automatically generated by Pandoc -->
|
6
|
+
|
7
|
+
1mPrivate Gems0m
|
8
|
+
Stashing private gems in your Gemstash server requires a bit of addi-
|
9
|
+
tional setup. If you haven't read through the Quickstart Guide, you
|
10
|
+
should do that first. By the end of this guide, you will be able to
|
11
|
+
interact with your Gemstash server to store and retrieve your private
|
12
|
+
gems.
|
13
|
+
|
14
|
+
1mAuthorizing0m
|
13
15
|
1mIMPORTANT NOTE: 22mDo not use the actual key value in this document, oth-
|
14
16
|
erwise your Gemstash server will be vulnerable to anyone who wants to
|
15
17
|
try to use the key against your server. Instead of the key value here,
|
16
18
|
use whatever key is generated from running the commands.
|
17
19
|
|
18
20
|
In order to push a gem to your Gemstash server, you need to first cre-
|
19
|
-
ate an API key. Utilize the
|
21
|
+
ate an API key. Utilize the 1mgemstash authorize 22mcommand to create the
|
20
22
|
API key:
|
21
23
|
|
22
24
|
$ gemstash authorize
|
23
25
|
Your new key is: e374e237fdf5fa5718d2a21bd63dc911
|
24
26
|
|
25
|
-
This new key can
|
26
|
-
Run
|
27
|
+
This new key can 1mpush22m, 1myank22m, and 1mfetch 22mgems from your Gemstash server.
|
28
|
+
Run 1mgemstash authorize 22mwith just the permissions you want to limit what
|
27
29
|
the key will be allowed to do. You can similarly update a specific key
|
28
|
-
by providing it via the --key
|
30
|
+
by providing it via the 1m--key 22moption:
|
29
31
|
|
30
32
|
$ gemstash authorize push yank --key e374e237fdf5fa5718d2a21bd63dc911
|
31
33
|
|
@@ -51,13 +53,13 @@ gemstash-private-gems(7) gemstash-private-gems(7)
|
|
51
53
|
---
|
52
54
|
:test_key: e374e237fdf5fa5718d2a21bd63dc911
|
53
55
|
|
54
|
-
The name
|
55
|
-
ber it and use it again later in this guide for the --key
|
56
|
+
The name 1mtest_key 22mcan be anything you want, but you will need to remem-
|
57
|
+
ber it and use it again later in this guide for the 1m--key 22moption.
|
56
58
|
|
57
|
-
|
59
|
+
1mCreating a Test Gem0m
|
58
60
|
You'll need a test gem before you can play with private gems on your
|
59
|
-
Gemstash server.
|
60
|
-
section.
|
61
|
+
Gemstash server. If you have a gem you can use, move along to the next
|
62
|
+
section. You can start by instantiating a test gem via Bundler:
|
61
63
|
|
62
64
|
$ bundle gem private-example
|
63
65
|
|
@@ -68,10 +70,10 @@ gemstash-private-gems(7) gemstash-private-gems(7)
|
|
68
70
|
$ cd private-example
|
69
71
|
$ rake build
|
70
72
|
|
71
|
-
You will now have a
|
72
|
-
|
73
|
+
You will now have a gem at 1mprivate-example/pkg/private-exam-0m
|
74
|
+
1mple-0.1.0.gem22m.
|
73
75
|
|
74
|
-
|
76
|
+
1mPushing0m
|
75
77
|
If your Gemstash server isn't running, go ahead and start it:
|
76
78
|
|
77
79
|
$ gemstash start
|
@@ -80,13 +82,13 @@ gemstash-private-gems(7) gemstash-private-gems(7)
|
|
80
82
|
|
81
83
|
$ gem push --key test_key --host http://localhost:9292/private pkg/private-example-0.1.0.gem
|
82
84
|
|
83
|
-
The /private
|
85
|
+
The 1m/private 22mportion of the 1m--host 22moption tells Gemstash you are inter-
|
84
86
|
acting with the private gems. Gemstash will not let you push, or yank
|
85
|
-
from anything except /
|
87
|
+
from anything except 1m/private22m.
|
86
88
|
|
87
|
-
|
89
|
+
1mBundling0m
|
88
90
|
Once your gem is pushed to your Gemstash server, you are ready to bun-
|
89
|
-
dle it. Create a
|
91
|
+
dle it. Create a 1mGemfile 22mand specify the gem. You will probably want
|
90
92
|
to wrap the private gem in a source block, and let the rest of Gemstash
|
91
93
|
handle all other gems:
|
92
94
|
|
@@ -98,34 +100,34 @@ gemstash-private-gems(7) gemstash-private-gems(7)
|
|
98
100
|
gem "private-example"
|
99
101
|
end
|
100
102
|
|
101
|
-
Notice that the Gemstash server points to /private
|
102
|
-
stalling
|
103
|
+
Notice that the Gemstash server points to 1m/private 22magain when in-
|
104
|
+
stalling your private gem. Go ahead and bundle to install your new
|
103
105
|
private gem:
|
104
106
|
|
105
107
|
$ bundle
|
106
108
|
|
107
|
-
|
109
|
+
1mYanking0m
|
108
110
|
If you push a private gem by accident, you can yank the gem with
|
109
111
|
Rubygems:
|
110
112
|
|
111
113
|
$ RUBYGEMS_HOST=http://localhost:9292/private gem yank --key test_key private-example --version 0.1.0
|
112
114
|
|
113
|
-
Like with pushing, the /private
|
115
|
+
Like with pushing, the 1m/private 22mportion of the host option tells Gem-
|
114
116
|
stash you are interacting with private gems. Gemstash will only let
|
115
|
-
you yank from /
|
116
|
-
--host
|
117
|
-
|
117
|
+
you yank from 1m/private22m. Unlike pushing, Rubygems doesn't support
|
118
|
+
1m--host 22mfor yank (yet), so you need to specify the host via the
|
119
|
+
1mRUBYGEMS_HOST 22menvironment variable.
|
118
120
|
|
119
|
-
|
121
|
+
1mProtected Fetching0m
|
120
122
|
By default, private gems and specs can be accessed without authentica-
|
121
123
|
tion.
|
122
124
|
|
123
125
|
Private gems often require protected fetching. For backwards compati-
|
124
|
-
bility this is disabled by default, but can be enabled via $
|
125
|
-
|
126
|
+
bility this is disabled by default, but can be enabled via 1m$ gemstash0m
|
127
|
+
1msetup 22mcommand.
|
126
128
|
|
127
|
-
When protected fetching is enabled API keys with the permissions
|
128
|
-
|
129
|
+
When protected fetching is enabled API keys with the permissions 1mall 22mor
|
130
|
+
1mfetch 22mcan be used to download gems and specs.
|
129
131
|
|
130
132
|
On the Bundler side, there are a few ways to configure credentials for
|
131
133
|
a given gem source:
|
@@ -145,7 +147,7 @@ gemstash-private-gems(7) gemstash-private-gems(7)
|
|
145
147
|
$ export BUNDLE_MYGEMSTASH__DEV=api_key
|
146
148
|
|
147
149
|
Behind the scene, Bundler will pick up the ENV var according to the
|
148
|
-
host name (e.g. mygemstash.dev) and add to
|
150
|
+
host name (e.g. mygemstash.dev) and add to 1mURI.userinfo 22mfor making re-
|
149
151
|
quests.
|
150
152
|
|
151
153
|
The API key is treated as a HTTP Basic Auth username and any HTTP Basic
|
@@ -153,4 +155,4 @@ gemstash-private-gems(7) gemstash-private-gems(7)
|
|
153
155
|
|
154
156
|
|
155
157
|
|
156
|
-
October 8, 2015
|
158
|
+
October 8, 2015 gemstash-private-gems(7)
|
@@ -1,9 +1,24 @@
|
|
1
|
-
|
1
|
+
<!-- Automatically generated by Pandoc -->
|
2
|
+
.\" Automatically generated by Pandoc 3.0.1
|
2
3
|
.\"
|
3
|
-
|
4
|
+
.\" Define V font for inline verbatim, using C font in formats
|
5
|
+
.\" that render this, and otherwise B font.
|
6
|
+
.ie "\f[CB]x\f[]"x" \{\
|
7
|
+
. ftr V B
|
8
|
+
. ftr VI BI
|
9
|
+
. ftr VB B
|
10
|
+
. ftr VBI BI
|
11
|
+
.\}
|
12
|
+
.el \{\
|
13
|
+
. ftr V CR
|
14
|
+
. ftr VI CI
|
15
|
+
. ftr VB CB
|
16
|
+
. ftr VBI CBI
|
17
|
+
.\}
|
18
|
+
.TH "gemstash-readme" "7" "November 30, 2015" "" ""
|
4
19
|
.hy
|
5
|
-
.SH
|
6
|
-
.SS
|
20
|
+
.SH Gemstash
|
21
|
+
.SS What is Gemstash?
|
7
22
|
.PP
|
8
23
|
Gemstash is both a cache for remote servers such as
|
9
24
|
https://rubygems.org, and a private gem source.
|
@@ -20,7 +35,8 @@ you might want to use Gemstash.
|
|
20
35
|
.PP
|
21
36
|
Are you only using gems from https://rubygems.org, and don\[cq]t bundle
|
22
37
|
the same gems frequently?
|
23
|
-
Well, maybe you don\[cq]t need Gemstash\&...
|
38
|
+
Well, maybe you don\[cq]t need Gemstash\&...
|
39
|
+
yet.
|
24
40
|
.PP
|
25
41
|
Gemstash is maintained by Ruby Together (https://rubytogether.org/), a
|
26
42
|
grassroots initiative committed to supporting the critical Ruby
|
@@ -29,8 +45,8 @@ Contribute today as an individual (https://rubytogether.org/developers)
|
|
29
45
|
or even better, as a company (https://rubytogether.org/companies), and
|
30
46
|
ensure that Bundler, RubyGems, Gemstash, and other shared tooling is
|
31
47
|
around for years to come.
|
32
|
-
.SS
|
33
|
-
.SS
|
48
|
+
.SS Quickstart Guide
|
49
|
+
.SS Setup
|
34
50
|
.PP
|
35
51
|
Gemstash is designed to be quick and painless to get set up.
|
36
52
|
By the end of this Quickstart Guide, you will be able to bundle stashed
|
@@ -46,7 +62,7 @@ $ gem install gemstash
|
|
46
62
|
.fi
|
47
63
|
.PP
|
48
64
|
After it is installed, starting Gemstash requires no additional steps.
|
49
|
-
Simply start the Gemstash server with the \f[
|
65
|
+
Simply start the Gemstash server with the \f[V]gemstash\f[R] command:
|
50
66
|
.IP
|
51
67
|
.nf
|
52
68
|
\f[C]
|
@@ -58,7 +74,7 @@ You may have noticed that the command finished quickly.
|
|
58
74
|
This is because Gemstash will run the server in the background by
|
59
75
|
default.
|
60
76
|
The server runs on port 9292.
|
61
|
-
.SS
|
77
|
+
.SS Bundling
|
62
78
|
.PP
|
63
79
|
With the server running, you can bundle against it.
|
64
80
|
Tell Bundler that you want to use Gemstash to find gems from
|
@@ -86,13 +102,13 @@ Now bundle:
|
|
86
102
|
.IP
|
87
103
|
.nf
|
88
104
|
\f[C]
|
89
|
-
$ bundle install
|
105
|
+
$ bundle install --path .bundle
|
90
106
|
\f[R]
|
91
107
|
.fi
|
92
108
|
.PP
|
93
109
|
Your Gemstash server has fetched the gems from https://rubygems.org and
|
94
|
-
cached them for you!
|
95
|
-
connection and try again.
|
110
|
+
cached them for you!
|
111
|
+
To prove this, you can disable your Internet connection and try again.
|
96
112
|
Gem files (*.gem) are cached indefinitely.
|
97
113
|
Gem dependencies metadata are cached for 30 minutes, so if you bundle
|
98
114
|
again before that, you can successfully bundle without an Internet
|
@@ -101,11 +117,11 @@ connection:
|
|
101
117
|
.nf
|
102
118
|
\f[C]
|
103
119
|
$ # Disable your Internet first!
|
104
|
-
$ rm
|
120
|
+
$ rm -rf Gemfile.lock .bundle
|
105
121
|
$ bundle
|
106
122
|
\f[R]
|
107
123
|
.fi
|
108
|
-
.SS
|
124
|
+
.SS Falling back to rubygems.org
|
109
125
|
.PP
|
110
126
|
If you want to make sure that your bundling from https://rubygems.org
|
111
127
|
still works as expected when the Gemstash server is not running, you can
|
@@ -126,7 +142,7 @@ This example uses a 3 second timeout:
|
|
126
142
|
$ bundle config mirror.https://rubygems.org.fallback_timeout 3
|
127
143
|
\f[R]
|
128
144
|
.fi
|
129
|
-
.SS
|
145
|
+
.SS Stopping the Server
|
130
146
|
.PP
|
131
147
|
Once you\[cq]ve finish using your Gemstash server, you can stop it just
|
132
148
|
as easily as you started it:
|
@@ -142,83 +158,79 @@ from RubyGems.org directly, instead of going through Gemstash:
|
|
142
158
|
.IP
|
143
159
|
.nf
|
144
160
|
\f[C]
|
145
|
-
$ bundle config
|
161
|
+
$ bundle config --delete mirror.https://rubygems.org
|
146
162
|
\f[R]
|
147
163
|
.fi
|
148
|
-
.SS
|
164
|
+
.SS Under the Hood
|
149
165
|
.PP
|
150
166
|
You might wonder where the gems are stored.
|
151
167
|
After running the commands above, you will find a new directory at
|
152
|
-
\f[
|
168
|
+
\f[V]\[ti]/.gemstash\f[R].
|
153
169
|
This directory holds all the cached and private gems.
|
154
170
|
It also has a server log, the database, and configuration for Gemstash.
|
155
|
-
If you prefer, you can point to a different
|
156
|
-
directory (gemstash help customize.7).
|
171
|
+
If you prefer, you can point to a different directory.
|
157
172
|
.PP
|
158
173
|
Gemstash uses SQLite (https://www.sqlite.org/) to store details about
|
159
174
|
private gems.
|
160
|
-
The database will be located in \f[
|
175
|
+
The database will be located in \f[V]\[ti]/.gemstash\f[R], however you
|
161
176
|
won\[cq]t see the database appear until you start using private gems.
|
162
|
-
If you prefer, you can use a different
|
163
|
-
database (gemstash help customize.7).
|
177
|
+
If you prefer, you can use a different database.
|
164
178
|
.PP
|
165
179
|
Gemstash temporarily caches things like gem dependencies in memory.
|
166
180
|
Anything cached in memory will last for 30 minutes before being
|
167
181
|
retrieved again.
|
168
|
-
You can use memcached
|
169
|
-
memory.
|
182
|
+
You can use memcached instead of caching in memory.
|
170
183
|
Gem files are always cached permanently, so bundling with a
|
171
|
-
\f[
|
184
|
+
\f[V]Gemfile.lock\f[R] with all gems cached will never call out to
|
172
185
|
https://rubygems.org.
|
173
186
|
.PP
|
174
187
|
The server you ran is provided via Puma (http://puma.io/) and
|
175
188
|
Rack (http://rack.github.io/), however they are not customizable at this
|
176
189
|
point.
|
177
|
-
.SS
|
190
|
+
.SS Deep Dive
|
178
191
|
.PP
|
179
192
|
Deep dive into more subjects:
|
180
193
|
.IP \[bu] 2
|
181
|
-
Private gems
|
194
|
+
Private gems
|
182
195
|
.IP \[bu] 2
|
183
|
-
Multiple gem sources
|
196
|
+
Multiple gem sources
|
184
197
|
.IP \[bu] 2
|
185
|
-
Using Gemstash as a mirror
|
198
|
+
Using Gemstash as a mirror
|
186
199
|
.IP \[bu] 2
|
187
|
-
Customizing the server (database, storage, caching, and
|
188
|
-
more) (gemstash help customize.7)
|
200
|
+
Customizing the server (database, storage, caching, and more)
|
189
201
|
.IP \[bu] 2
|
190
|
-
Deploying Gemstash
|
202
|
+
Deploying Gemstash
|
191
203
|
.IP \[bu] 2
|
192
|
-
Debugging Gemstash
|
193
|
-
.SS
|
204
|
+
Debugging Gemstash
|
205
|
+
.SS Reference
|
194
206
|
.PP
|
195
207
|
An anatomy of various configuration and commands:
|
196
208
|
.IP \[bu] 2
|
197
|
-
Configuration
|
209
|
+
Configuration
|
198
210
|
.IP \[bu] 2
|
199
|
-
Authorize
|
211
|
+
Authorize
|
200
212
|
.IP \[bu] 2
|
201
|
-
Start
|
213
|
+
Start
|
202
214
|
.IP \[bu] 2
|
203
|
-
Stop
|
215
|
+
Stop
|
204
216
|
.IP \[bu] 2
|
205
|
-
Status
|
217
|
+
Status
|
206
218
|
.IP \[bu] 2
|
207
|
-
Setup
|
219
|
+
Setup
|
208
220
|
.IP \[bu] 2
|
209
|
-
Version
|
221
|
+
Version
|
210
222
|
.PP
|
211
223
|
To see what has changed in recent versions of Gemstash, see the
|
212
224
|
CHANGELOG (https://github.com/rubygems/gemstash/blob/master/CHANGELOG.md).
|
213
|
-
.SS
|
225
|
+
.SS Development
|
214
226
|
.PP
|
215
|
-
After checking out the repo, run \f[
|
227
|
+
After checking out the repo, run \f[V]bin/setup\f[R] to install
|
216
228
|
dependencies.
|
217
|
-
Then, run \f[
|
218
|
-
While developing, you can run \f[
|
219
|
-
You can also run \f[
|
229
|
+
Then, run \f[V]rake\f[R] to run RuboCop and the tests.
|
230
|
+
While developing, you can run \f[V]bin/gemstash\f[R] to run Gemstash.
|
231
|
+
You can also run \f[V]bin/console\f[R] for an interactive prompt that
|
220
232
|
will allow you to experiment.
|
221
|
-
.SS
|
233
|
+
.SS Contributing
|
222
234
|
.PP
|
223
235
|
Bug reports and pull requests are welcome on GitHub at
|
224
236
|
https://github.com/rubygems/gemstash.
|
@@ -227,7 +239,7 @@ collaboration, and contributors are expected to adhere to the
|
|
227
239
|
Contributor
|
228
240
|
Covenant (https://github.com/rubygems/gemstash/blob/master/CODE_OF_CONDUCT.md)
|
229
241
|
code of conduct.
|
230
|
-
.SS
|
242
|
+
.SS License
|
231
243
|
.PP
|
232
244
|
The gem is available as open source under the terms of the MIT
|
233
245
|
License (http://opensource.org/licenses/MIT).
|