gemstash 2.3.2 → 2.5.0
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 +25 -36
- data/lib/gemstash/authorization.rb +5 -2
- data/lib/gemstash/cli/authorize.rb +42 -1
- data/lib/gemstash/cli.rb +4 -0
- data/lib/gemstash/db/authorization.rb +3 -3
- data/lib/gemstash/man/gemstash-authorize.1 +21 -33
- data/lib/gemstash/man/gemstash-authorize.1.txt +23 -15
- data/lib/gemstash/man/gemstash-configuration.5 +63 -118
- data/lib/gemstash/man/gemstash-configuration.5.txt +54 -54
- data/lib/gemstash/man/gemstash-customize.7 +60 -103
- data/lib/gemstash/man/gemstash-customize.7.txt +35 -35
- data/lib/gemstash/man/gemstash-debugging.7 +8 -27
- data/lib/gemstash/man/gemstash-debugging.7.txt +6 -6
- data/lib/gemstash/man/gemstash-deploy.7 +15 -39
- data/lib/gemstash/man/gemstash-deploy.7.txt +16 -16
- data/lib/gemstash/man/gemstash-mirror.7 +10 -31
- data/lib/gemstash/man/gemstash-mirror.7.txt +3 -3
- data/lib/gemstash/man/gemstash-multiple-sources.7 +72 -44
- data/lib/gemstash/man/gemstash-multiple-sources.7.txt +59 -11
- data/lib/gemstash/man/gemstash-private-gems.7 +51 -102
- data/lib/gemstash/man/gemstash-private-gems.7.txt +21 -21
- data/lib/gemstash/man/gemstash-readme.7 +29 -75
- data/lib/gemstash/man/gemstash-readme.7.txt +10 -10
- data/lib/gemstash/man/gemstash-setup.1 +13 -33
- data/lib/gemstash/man/gemstash-setup.1.txt +11 -11
- data/lib/gemstash/man/gemstash-start.1 +7 -25
- data/lib/gemstash/man/gemstash-start.1.txt +6 -6
- data/lib/gemstash/man/gemstash-status.1 +5 -23
- data/lib/gemstash/man/gemstash-status.1.txt +4 -4
- data/lib/gemstash/man/gemstash-stop.1 +5 -23
- data/lib/gemstash/man/gemstash-stop.1.txt +4 -4
- data/lib/gemstash/man/gemstash-version.1 +4 -24
- data/lib/gemstash/man/gemstash-version.1.txt +1 -1
- data/lib/gemstash/migrations/05_authorization_names.rb +10 -0
- data/lib/gemstash/upstream.rb +33 -2
- data/lib/gemstash/version.rb +1 -1
- metadata +18 -3
@@ -1,24 +1,8 @@
|
|
1
1
|
<!-- Automatically generated by Pandoc -->
|
2
|
-
.\" Automatically generated by Pandoc 3.1.
|
2
|
+
.\" Automatically generated by Pandoc 3.1.8
|
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
4
|
.TH "gemstash-private-gems" "7" "October 8, 2015" "" ""
|
19
|
-
.hy
|
20
5
|
.SH Private Gems
|
21
|
-
.PP
|
22
6
|
Stashing private gems in your Gemstash server requires a bit of
|
23
7
|
additional setup.
|
24
8
|
If you haven\[cq]t read through the Quickstart Guide, you should do that
|
@@ -26,7 +10,6 @@ first.
|
|
26
10
|
By the end of this guide, you will be able to interact with your
|
27
11
|
Gemstash server to store and retrieve your private gems.
|
28
12
|
.SS Authorizing
|
29
|
-
.PP
|
30
13
|
\f[B]IMPORTANT NOTE:\f[R] Do not use the actual key value in this
|
31
14
|
document, otherwise your Gemstash server will be vulnerable to anyone
|
32
15
|
who wants to try to use the key against your server.
|
@@ -35,38 +18,32 @@ running the commands.
|
|
35
18
|
.PP
|
36
19
|
In order to push a gem to your Gemstash server, you need to first create
|
37
20
|
an API key.
|
38
|
-
Utilize the \f[
|
21
|
+
Utilize the \f[CR]gemstash authorize\f[R] command to create the API key:
|
39
22
|
.IP
|
40
|
-
.
|
41
|
-
\f[C]
|
23
|
+
.EX
|
42
24
|
$ gemstash authorize
|
43
25
|
Your new key is: e374e237fdf5fa5718d2a21bd63dc911
|
44
|
-
|
45
|
-
.fi
|
26
|
+
.EE
|
46
27
|
.PP
|
47
|
-
This new key can \f[
|
28
|
+
This new key can \f[CR]push\f[R], \f[CR]yank\f[R], and \f[CR]fetch\f[R]
|
48
29
|
gems from your Gemstash server.
|
49
|
-
Run \f[
|
30
|
+
Run \f[CR]gemstash authorize\f[R] with just the permissions you want to
|
50
31
|
limit what the key will be allowed to do.
|
51
32
|
You can similarly update a specific key by providing it via the
|
52
|
-
\f[
|
33
|
+
\f[CR]--key\f[R] option:
|
53
34
|
.IP
|
54
|
-
.
|
55
|
-
\f[C]
|
35
|
+
.EX
|
56
36
|
$ gemstash authorize push yank --key e374e237fdf5fa5718d2a21bd63dc911
|
57
|
-
|
58
|
-
.fi
|
37
|
+
.EE
|
59
38
|
.PP
|
60
39
|
When no permissions are provided (like the first example), the key will
|
61
40
|
be authorized for all permissions.
|
62
41
|
Leave the key authorized with everything if you want to use it to try
|
63
42
|
all private gem interactions:
|
64
43
|
.IP
|
65
|
-
.
|
66
|
-
\f[C]
|
44
|
+
.EX
|
67
45
|
$ gemstash authorize --key e374e237fdf5fa5718d2a21bd63dc911
|
68
|
-
|
69
|
-
.fi
|
46
|
+
.EE
|
70
47
|
.PP
|
71
48
|
With the key generated, you\[cq]ll need to tell Rubygems about your new
|
72
49
|
key.
|
@@ -75,86 +52,70 @@ already have a credentials file to add the key to.
|
|
75
52
|
If not, run the following commands before modifying the credentials
|
76
53
|
file:
|
77
54
|
.IP
|
78
|
-
.
|
79
|
-
\f[C]
|
55
|
+
.EX
|
80
56
|
$ mkdir -p \[ti]/.gem
|
81
57
|
$ touch \[ti]/.gem/credentials
|
82
58
|
$ chmod 0600 \[ti]/.gem/credentials
|
83
|
-
|
84
|
-
.fi
|
59
|
+
.EE
|
85
60
|
.PP
|
86
61
|
Add your new key to credentials such that it looks something like this
|
87
62
|
(but make sure not to remove any existing keys):
|
88
63
|
.IP
|
89
|
-
.
|
90
|
-
\f[C]
|
64
|
+
.EX
|
91
65
|
# \[ti]/.gem/credentials
|
92
66
|
---
|
93
67
|
:test_key: e374e237fdf5fa5718d2a21bd63dc911
|
94
|
-
|
95
|
-
.fi
|
68
|
+
.EE
|
96
69
|
.PP
|
97
|
-
The name \f[
|
70
|
+
The name \f[CR]test_key\f[R] can be anything you want, but you will need
|
98
71
|
to remember it and use it again later in this guide for the
|
99
|
-
\f[
|
72
|
+
\f[CR]--key\f[R] option.
|
100
73
|
.SS Creating a Test Gem
|
101
|
-
.PP
|
102
74
|
You\[cq]ll need a test gem before you can play with private gems on your
|
103
75
|
Gemstash server.
|
104
76
|
If you have a gem you can use, move along to the next section.
|
105
77
|
You can start by instantiating a test gem via Bundler:
|
106
78
|
.IP
|
107
|
-
.
|
108
|
-
\f[C]
|
79
|
+
.EX
|
109
80
|
$ bundle gem private-example
|
110
|
-
|
111
|
-
.fi
|
81
|
+
.EE
|
112
82
|
.PP
|
113
83
|
You\[cq]ll need to add a summary and description to the new gem\[cq]s
|
114
84
|
gemspec file in order to successfully build it.
|
115
85
|
Once you\[cq]ve built the gem, you will be ready to push the new gem.
|
116
86
|
.IP
|
117
|
-
.
|
118
|
-
\f[C]
|
87
|
+
.EX
|
119
88
|
$ cd private-example
|
120
89
|
$ rake build
|
121
|
-
|
122
|
-
.fi
|
90
|
+
.EE
|
123
91
|
.PP
|
124
92
|
You will now have a gem at
|
125
|
-
\f[
|
93
|
+
\f[CR]private-example/pkg/private-example-0.1.0.gem\f[R].
|
126
94
|
.SS Pushing
|
127
|
-
.PP
|
128
95
|
If your Gemstash server isn\[cq]t running, go ahead and start it:
|
129
96
|
.IP
|
130
|
-
.
|
131
|
-
\f[C]
|
97
|
+
.EX
|
132
98
|
$ gemstash start
|
133
|
-
|
134
|
-
.fi
|
99
|
+
.EE
|
135
100
|
.PP
|
136
101
|
Push your test gem using Rubygems:
|
137
102
|
.IP
|
138
|
-
.
|
139
|
-
\f[C]
|
103
|
+
.EX
|
140
104
|
$ gem push --key test_key --host http://localhost:9292/private pkg/private-example-0.1.0.gem
|
141
|
-
|
142
|
-
.fi
|
105
|
+
.EE
|
143
106
|
.PP
|
144
|
-
The \f[
|
107
|
+
The \f[CR]/private\f[R] portion of the \f[CR]--host\f[R] option tells
|
145
108
|
Gemstash you are interacting with the private gems.
|
146
109
|
Gemstash will not let you push, or yank from anything except
|
147
|
-
\f[
|
110
|
+
\f[CR]/private\f[R].
|
148
111
|
.SS Bundling
|
149
|
-
.PP
|
150
112
|
Once your gem is pushed to your Gemstash server, you are ready to bundle
|
151
113
|
it.
|
152
|
-
Create a \f[
|
114
|
+
Create a \f[CR]Gemfile\f[R] and specify the gem.
|
153
115
|
You will probably want to wrap the private gem in a source block, and
|
154
116
|
let the rest of Gemstash handle all other gems:
|
155
117
|
.IP
|
156
|
-
.
|
157
|
-
\f[C]
|
118
|
+
.EX
|
158
119
|
# ./Gemfile
|
159
120
|
source \[dq]http://localhost:9292\[dq]
|
160
121
|
gem \[dq]rubywarrior\[dq]
|
@@ -162,65 +123,55 @@ gem \[dq]rubywarrior\[dq]
|
|
162
123
|
source \[dq]http://localhost:9292/private\[dq] do
|
163
124
|
gem \[dq]private-example\[dq]
|
164
125
|
end
|
165
|
-
|
166
|
-
.fi
|
126
|
+
.EE
|
167
127
|
.PP
|
168
|
-
Notice that the Gemstash server points to \f[
|
128
|
+
Notice that the Gemstash server points to \f[CR]/private\f[R] again when
|
169
129
|
installing your private gem.
|
170
130
|
Go ahead and bundle to install your new private gem:
|
171
131
|
.IP
|
172
|
-
.
|
173
|
-
\f[C]
|
132
|
+
.EX
|
174
133
|
$ bundle
|
175
|
-
|
176
|
-
.fi
|
134
|
+
.EE
|
177
135
|
.SS Yanking
|
178
|
-
.PP
|
179
136
|
If you push a private gem by accident, you can yank the gem with
|
180
137
|
Rubygems:
|
181
138
|
.IP
|
182
|
-
.
|
183
|
-
\f[C]
|
139
|
+
.EX
|
184
140
|
$ RUBYGEMS_HOST=http://localhost:9292/private gem yank --key test_key private-example --version 0.1.0
|
185
|
-
|
186
|
-
.fi
|
141
|
+
.EE
|
187
142
|
.PP
|
188
|
-
Like with pushing, the \f[
|
143
|
+
Like with pushing, the \f[CR]/private\f[R] portion of the host option
|
189
144
|
tells Gemstash you are interacting with private gems.
|
190
|
-
Gemstash will only let you yank from \f[
|
191
|
-
Unlike pushing, Rubygems doesn\[cq]t support \f[
|
192
|
-
(yet), so you need to specify the host via the \f[
|
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]
|
193
148
|
environment variable.
|
194
149
|
.SS Protected Fetching
|
195
|
-
.PP
|
196
150
|
By default, private gems and specs can be accessed without
|
197
151
|
authentication.
|
198
152
|
.PP
|
199
153
|
Private gems often require protected fetching.
|
200
154
|
For backwards compatibility this is disabled by default, but can be
|
201
|
-
enabled via \f[
|
155
|
+
enabled via \f[CR]$ gemstash setup\f[R] command.
|
202
156
|
.PP
|
203
157
|
When protected fetching is enabled API keys with the permissions
|
204
|
-
\f[
|
158
|
+
\f[CR]all\f[R] or \f[CR]fetch\f[R] can be used to download gems and
|
159
|
+
specs.
|
205
160
|
.PP
|
206
161
|
On the Bundler side, there are a few ways to configure credentials for a
|
207
162
|
given gem source:
|
208
163
|
.PP
|
209
164
|
Add credentials globally:
|
210
165
|
.IP
|
211
|
-
.
|
212
|
-
\f[C]
|
166
|
+
.EX
|
213
167
|
$ bundle config my-gemstash.dev api_key
|
214
|
-
|
215
|
-
.fi
|
168
|
+
.EE
|
216
169
|
.PP
|
217
170
|
Add credentials in Gemfile:
|
218
171
|
.IP
|
219
|
-
.
|
220
|
-
\f[C]
|
172
|
+
.EX
|
221
173
|
source \[dq]https://api_key\[at]my-gemstash.dev\[dq]
|
222
|
-
|
223
|
-
.fi
|
174
|
+
.EE
|
224
175
|
.PP
|
225
176
|
However, it\[cq]s not a good practice to commit credentials to source
|
226
177
|
control.
|
@@ -228,15 +179,13 @@ A recommended solution is to use Bundler\[cq]s configuration
|
|
228
179
|
keys (http://bundler.io/man/bundle-config.1.html#CONFIGURATION-KEYS),
|
229
180
|
e.g.:
|
230
181
|
.IP
|
231
|
-
.
|
232
|
-
\f[C]
|
182
|
+
.EX
|
233
183
|
$ export BUNDLE_MYGEMSTASH__DEV=api_key
|
234
|
-
|
235
|
-
.fi
|
184
|
+
.EE
|
236
185
|
.PP
|
237
186
|
Behind the scene, Bundler will pick up the ENV var according to the host
|
238
|
-
name (e.g.\ mygemstash.dev) and add to \f[
|
239
|
-
requests.
|
187
|
+
name (e.g.\ mygemstash.dev) and add to \f[CR]URI.userinfo\f[R] for
|
188
|
+
making requests.
|
240
189
|
.PP
|
241
190
|
The API key is treated as a HTTP Basic Auth username and any HTTP Basic
|
242
191
|
password supplied will be ignored.
|
@@ -16,16 +16,16 @@
|
|
16
16
|
use whatever key is generated from running the commands.
|
17
17
|
|
18
18
|
In order to push a gem to your Gemstash server, you need to first cre-
|
19
|
-
ate an API key. Utilize the
|
19
|
+
ate an API key. Utilize the gemstash authorize command to create the
|
20
20
|
API key:
|
21
21
|
|
22
22
|
$ gemstash authorize
|
23
23
|
Your new key is: e374e237fdf5fa5718d2a21bd63dc911
|
24
24
|
|
25
|
-
This new key can
|
26
|
-
Run
|
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
27
|
the key will be allowed to do. You can similarly update a specific key
|
28
|
-
by providing it via the
|
28
|
+
by providing it via the --key option:
|
29
29
|
|
30
30
|
$ gemstash authorize push yank --key e374e237fdf5fa5718d2a21bd63dc911
|
31
31
|
|
@@ -51,8 +51,8 @@
|
|
51
51
|
---
|
52
52
|
:test_key: e374e237fdf5fa5718d2a21bd63dc911
|
53
53
|
|
54
|
-
The name
|
55
|
-
ber it and use it again later in this guide for the
|
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
56
|
|
57
57
|
1mCreating a Test Gem0m
|
58
58
|
You'll need a test gem before you can play with private gems on your
|
@@ -68,8 +68,8 @@
|
|
68
68
|
$ cd private-example
|
69
69
|
$ rake build
|
70
70
|
|
71
|
-
You will now have a gem at
|
72
|
-
|
71
|
+
You will now have a gem at private-example/pkg/private-exam-
|
72
|
+
ple-0.1.0.gem.
|
73
73
|
|
74
74
|
1mPushing0m
|
75
75
|
If your Gemstash server isn't running, go ahead and start it:
|
@@ -80,13 +80,13 @@
|
|
80
80
|
|
81
81
|
$ gem push --key test_key --host http://localhost:9292/private pkg/private-example-0.1.0.gem
|
82
82
|
|
83
|
-
The
|
83
|
+
The /private portion of the --host option tells Gemstash you are inter-
|
84
84
|
acting with the private gems. Gemstash will not let you push, or yank
|
85
|
-
from anything except
|
85
|
+
from anything except /private.
|
86
86
|
|
87
87
|
1mBundling0m
|
88
88
|
Once your gem is pushed to your Gemstash server, you are ready to bun-
|
89
|
-
dle it. Create a
|
89
|
+
dle it. Create a Gemfile and specify the gem. You will probably want
|
90
90
|
to wrap the private gem in a source block, and let the rest of Gemstash
|
91
91
|
handle all other gems:
|
92
92
|
|
@@ -98,7 +98,7 @@
|
|
98
98
|
gem "private-example"
|
99
99
|
end
|
100
100
|
|
101
|
-
Notice that the Gemstash server points to
|
101
|
+
Notice that the Gemstash server points to /private again when in-
|
102
102
|
stalling your private gem. Go ahead and bundle to install your new
|
103
103
|
private gem:
|
104
104
|
|
@@ -110,22 +110,22 @@
|
|
110
110
|
|
111
111
|
$ RUBYGEMS_HOST=http://localhost:9292/private gem yank --key test_key private-example --version 0.1.0
|
112
112
|
|
113
|
-
Like with pushing, the
|
113
|
+
Like with pushing, the /private portion of the host option tells Gem-
|
114
114
|
stash you are interacting with private gems. Gemstash will only let
|
115
|
-
you yank from
|
116
|
-
|
117
|
-
|
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
118
|
|
119
119
|
1mProtected Fetching0m
|
120
120
|
By default, private gems and specs can be accessed without authentica-
|
121
121
|
tion.
|
122
122
|
|
123
123
|
Private gems often require protected fetching. For backwards compati-
|
124
|
-
bility this is disabled by default, but can be enabled via
|
125
|
-
|
124
|
+
bility this is disabled by default, but can be enabled via $ gemstash
|
125
|
+
setup command.
|
126
126
|
|
127
|
-
When protected fetching is enabled API keys with the permissions
|
128
|
-
|
127
|
+
When protected fetching is enabled API keys with the permissions all or
|
128
|
+
fetch can be used to download gems and specs.
|
129
129
|
|
130
130
|
On the Bundler side, there are a few ways to configure credentials for
|
131
131
|
a given gem source:
|
@@ -145,7 +145,7 @@
|
|
145
145
|
$ export BUNDLE_MYGEMSTASH__DEV=api_key
|
146
146
|
|
147
147
|
Behind the scene, Bundler will pick up the ENV var according to the
|
148
|
-
host name (e.g. mygemstash.dev) and add to
|
148
|
+
host name (e.g. mygemstash.dev) and add to URI.userinfo for making re-
|
149
149
|
quests.
|
150
150
|
|
151
151
|
The API key is treated as a HTTP Basic Auth username and any HTTP Basic
|
@@ -1,25 +1,9 @@
|
|
1
1
|
<!-- Automatically generated by Pandoc -->
|
2
|
-
.\" Automatically generated by Pandoc 3.1.
|
2
|
+
.\" Automatically generated by Pandoc 3.1.8
|
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
4
|
.TH "gemstash-readme" "7" "November 30, 2015" "" ""
|
19
|
-
.hy
|
20
5
|
.SH Gemstash
|
21
6
|
.SS What is Gemstash?
|
22
|
-
.PP
|
23
7
|
Gemstash is both a cache for remote servers such as
|
24
8
|
https://rubygems.org, and a private gem source.
|
25
9
|
.PP
|
@@ -47,7 +31,6 @@ Bundler, RubyGems, Gemstash, and other shared tooling is around for
|
|
47
31
|
years to come.
|
48
32
|
.SS Quickstart Guide
|
49
33
|
.SS Setup
|
50
|
-
.PP
|
51
34
|
Gemstash is designed to be quick and painless to get set up.
|
52
35
|
By the end of this Quickstart Guide, you will be able to bundle stashed
|
53
36
|
gems from public sources against a Gemstash server running on your
|
@@ -55,56 +38,45 @@ machine.
|
|
55
38
|
.PP
|
56
39
|
Install Gemstash to get started:
|
57
40
|
.IP
|
58
|
-
.
|
59
|
-
\f[C]
|
41
|
+
.EX
|
60
42
|
$ gem install gemstash
|
61
|
-
|
62
|
-
.fi
|
43
|
+
.EE
|
63
44
|
.PP
|
64
45
|
After it is installed, starting Gemstash requires no additional steps.
|
65
|
-
Simply start the Gemstash server with the \f[
|
46
|
+
Simply start the Gemstash server with the \f[CR]gemstash\f[R] command:
|
66
47
|
.IP
|
67
|
-
.
|
68
|
-
\f[C]
|
48
|
+
.EX
|
69
49
|
$ gemstash start
|
70
|
-
|
71
|
-
.fi
|
50
|
+
.EE
|
72
51
|
.PP
|
73
52
|
You may have noticed that the command finished quickly.
|
74
53
|
This is because Gemstash will run the server in the background by
|
75
54
|
default.
|
76
55
|
The server runs on port 9292.
|
77
56
|
.SS Bundling
|
78
|
-
.PP
|
79
57
|
With the server running, you can bundle against it.
|
80
58
|
Tell Bundler that you want to use Gemstash to find gems from
|
81
59
|
RubyGems.org:
|
82
60
|
.IP
|
83
|
-
.
|
84
|
-
\f[C]
|
61
|
+
.EX
|
85
62
|
$ bundle config mirror.https://rubygems.org http://localhost:9292
|
86
|
-
|
87
|
-
.fi
|
63
|
+
.EE
|
88
64
|
.PP
|
89
65
|
Now you can create a Gemfile and install gems through Gemstash:
|
90
66
|
.IP
|
91
|
-
.
|
92
|
-
\f[C]
|
67
|
+
.EX
|
93
68
|
# ./Gemfile
|
94
69
|
source \[dq]https://rubygems.org\[dq]
|
95
70
|
gem \[dq]rubywarrior\[dq]
|
96
|
-
|
97
|
-
.fi
|
71
|
+
.EE
|
98
72
|
.PP
|
99
73
|
The gems you include should be gems you don\[cq]t yet have installed,
|
100
74
|
otherwise Gemstash will have nothing to stash.
|
101
75
|
Now bundle:
|
102
76
|
.IP
|
103
|
-
.
|
104
|
-
\f[C]
|
77
|
+
.EX
|
105
78
|
$ bundle install --path .bundle
|
106
|
-
|
107
|
-
.fi
|
79
|
+
.EE
|
108
80
|
.PP
|
109
81
|
Your Gemstash server has fetched the gems from https://rubygems.org and
|
110
82
|
cached them for you!
|
@@ -114,65 +86,52 @@ Gem dependencies metadata are cached for 30 minutes, so if you bundle
|
|
114
86
|
again before that, you can successfully bundle without an Internet
|
115
87
|
connection:
|
116
88
|
.IP
|
117
|
-
.
|
118
|
-
\f[C]
|
89
|
+
.EX
|
119
90
|
$ # Disable your Internet first!
|
120
91
|
$ rm -rf Gemfile.lock .bundle
|
121
92
|
$ bundle
|
122
|
-
|
123
|
-
.fi
|
93
|
+
.EE
|
124
94
|
.SS Falling back to rubygems.org
|
125
|
-
.PP
|
126
95
|
If you want to make sure that your bundling from https://rubygems.org
|
127
96
|
still works as expected when the Gemstash server is not running, you can
|
128
97
|
easily configure Bundler to fallback to https://rubygems.org.
|
129
98
|
.IP
|
130
|
-
.
|
131
|
-
\f[C]
|
99
|
+
.EX
|
132
100
|
$ bundle config mirror.https://rubygems.org.fallback_timeout true
|
133
|
-
|
134
|
-
.fi
|
101
|
+
.EE
|
135
102
|
.PP
|
136
103
|
You can also configure this fallback as a number of seconds in case the
|
137
104
|
Gemstash server is simply unresponsive.
|
138
105
|
This example uses a 3 second timeout:
|
139
106
|
.IP
|
140
|
-
.
|
141
|
-
\f[C]
|
107
|
+
.EX
|
142
108
|
$ bundle config mirror.https://rubygems.org.fallback_timeout 3
|
143
|
-
|
144
|
-
.fi
|
109
|
+
.EE
|
145
110
|
.SS Stopping the Server
|
146
|
-
.PP
|
147
111
|
Once you\[cq]ve finish using your Gemstash server, you can stop it just
|
148
112
|
as easily as you started it:
|
149
113
|
.IP
|
150
|
-
.
|
151
|
-
\f[C]
|
114
|
+
.EX
|
152
115
|
$ gemstash stop
|
153
|
-
|
154
|
-
.fi
|
116
|
+
.EE
|
155
117
|
.PP
|
156
118
|
You\[cq]ll also want to tell Bundler that it can go back to getting gems
|
157
119
|
from RubyGems.org directly, instead of going through Gemstash:
|
158
120
|
.IP
|
159
|
-
.
|
160
|
-
\f[C]
|
121
|
+
.EX
|
161
122
|
$ bundle config --delete mirror.https://rubygems.org
|
162
|
-
|
163
|
-
.fi
|
123
|
+
.EE
|
164
124
|
.SS Under the Hood
|
165
|
-
.PP
|
166
125
|
You might wonder where the gems are stored.
|
167
126
|
After running the commands above, you will find a new directory at
|
168
|
-
\f[
|
127
|
+
\f[CR]\[ti]/.gemstash\f[R].
|
169
128
|
This directory holds all the cached and private gems.
|
170
129
|
It also has a server log, the database, and configuration for Gemstash.
|
171
130
|
If you prefer, you can point to a different directory.
|
172
131
|
.PP
|
173
132
|
Gemstash uses SQLite (https://www.sqlite.org/) to store details about
|
174
133
|
private gems.
|
175
|
-
The database will be located in \f[
|
134
|
+
The database will be located in \f[CR]\[ti]/.gemstash\f[R], however you
|
176
135
|
won\[cq]t see the database appear until you start using private gems.
|
177
136
|
If you prefer, you can use a different database.
|
178
137
|
.PP
|
@@ -181,14 +140,13 @@ Anything cached in memory will last for 30 minutes before being
|
|
181
140
|
retrieved again.
|
182
141
|
You can use memcached instead of caching in memory.
|
183
142
|
Gem files are always cached permanently, so bundling with a
|
184
|
-
\f[
|
143
|
+
\f[CR]Gemfile.lock\f[R] with all gems cached will never call out to
|
185
144
|
https://rubygems.org.
|
186
145
|
.PP
|
187
146
|
The server you ran is provided via Puma (http://puma.io/) and
|
188
147
|
Rack (http://rack.github.io/), however they are not customizable at this
|
189
148
|
point.
|
190
149
|
.SS Deep Dive
|
191
|
-
.PP
|
192
150
|
Deep dive into more subjects:
|
193
151
|
.IP \[bu] 2
|
194
152
|
Private gems
|
@@ -203,7 +161,6 @@ Deploying Gemstash
|
|
203
161
|
.IP \[bu] 2
|
204
162
|
Debugging Gemstash
|
205
163
|
.SS Reference
|
206
|
-
.PP
|
207
164
|
An anatomy of various configuration and commands:
|
208
165
|
.IP \[bu] 2
|
209
166
|
Configuration
|
@@ -223,15 +180,13 @@ Version
|
|
223
180
|
To see what has changed in recent versions of Gemstash, see the
|
224
181
|
CHANGELOG (https://github.com/rubygems/gemstash/blob/master/CHANGELOG.md).
|
225
182
|
.SS Development
|
226
|
-
|
227
|
-
After checking out the repo, run \f[V]bin/setup\f[R] to install
|
183
|
+
After checking out the repo, run \f[CR]bin/setup\f[R] to install
|
228
184
|
dependencies.
|
229
|
-
Then, run \f[
|
230
|
-
While developing, you can run \f[
|
231
|
-
You can also run \f[
|
185
|
+
Then, run \f[CR]rake\f[R] to run RuboCop and the tests.
|
186
|
+
While developing, you can run \f[CR]bin/gemstash\f[R] to run Gemstash.
|
187
|
+
You can also run \f[CR]bin/console\f[R] for an interactive prompt that
|
232
188
|
will allow you to experiment.
|
233
189
|
.SS Contributing
|
234
|
-
.PP
|
235
190
|
Bug reports and pull requests are welcome on GitHub at
|
236
191
|
https://github.com/rubygems/gemstash.
|
237
192
|
This project is intended to be a safe, welcoming space for
|
@@ -240,6 +195,5 @@ Contributor
|
|
240
195
|
Covenant (https://github.com/rubygems/gemstash/blob/master/CODE_OF_CONDUCT.md)
|
241
196
|
code of conduct.
|
242
197
|
.SS License
|
243
|
-
.PP
|
244
198
|
The gem is available as open source under the terms of the MIT
|
245
199
|
License (http://opensource.org/licenses/MIT).
|
@@ -38,7 +38,7 @@
|
|
38
38
|
$ gem install gemstash
|
39
39
|
|
40
40
|
After it is installed, starting Gemstash requires no additional steps.
|
41
|
-
Simply start the Gemstash server with the
|
41
|
+
Simply start the Gemstash server with the gemstash command:
|
42
42
|
|
43
43
|
$ gemstash start
|
44
44
|
|
@@ -100,21 +100,21 @@
|
|
100
100
|
|
101
101
|
1mUnder the Hood0m
|
102
102
|
You might wonder where the gems are stored. After running the commands
|
103
|
-
above, you will find a new directory at
|
103
|
+
above, you will find a new directory at ~/.gemstash. This directory
|
104
104
|
holds all the cached and private gems. It also has a server log, the
|
105
105
|
database, and configuration for Gemstash. If you prefer, you can point
|
106
106
|
to a different directory.
|
107
107
|
|
108
108
|
Gemstash uses SQLite (https://www.sqlite.org/) to store details about
|
109
|
-
private gems. The database will be located in
|
109
|
+
private gems. The database will be located in ~/.gemstash, however you
|
110
110
|
won't see the database appear until you start using private gems. If
|
111
111
|
you prefer, you can use a different database.
|
112
112
|
|
113
113
|
Gemstash temporarily caches things like gem dependencies in memory.
|
114
114
|
Anything cached in memory will last for 30 minutes before being re-
|
115
115
|
trieved again. You can use memcached instead of caching in memory.
|
116
|
-
Gem files are always cached permanently, so bundling with a
|
117
|
-
|
116
|
+
Gem files are always cached permanently, so bundling with a Gem-
|
117
|
+
file.lock with all gems cached will never call out to
|
118
118
|
https://rubygems.org.
|
119
119
|
|
120
120
|
The server you ran is provided via Puma (http://puma.io/) and Rack
|
@@ -154,13 +154,13 @@
|
|
154
154
|
o Version
|
155
155
|
|
156
156
|
To see what has changed in recent versions of Gemstash, see the
|
157
|
-
CHANGELOG
|
158
|
-
|
157
|
+
CHANGELOG (https://github.com/rubygems/gemstash/blob/mas-
|
158
|
+
ter/CHANGELOG.md).
|
159
159
|
|
160
160
|
1mDevelopment0m
|
161
|
-
After checking out the repo, run
|
162
|
-
Then, run
|
163
|
-
run
|
161
|
+
After checking out the repo, run bin/setup to install dependencies.
|
162
|
+
Then, run rake to run RuboCop and the tests. While developing, you can
|
163
|
+
run bin/gemstash to run Gemstash. You can also run bin/console for an
|
164
164
|
interactive prompt that will allow you to experiment.
|
165
165
|
|
166
166
|
1mContributing0m
|