gemstash 2.0.0 → 2.1.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/exe/gemstash +3 -0
- data/lib/gemstash.rb +2 -0
- data/lib/gemstash/api_key_authorization.rb +3 -0
- data/lib/gemstash/authorization.rb +7 -3
- data/lib/gemstash/cache.rb +5 -2
- data/lib/gemstash/cli.rb +2 -0
- data/lib/gemstash/cli/authorize.rb +3 -3
- data/lib/gemstash/cli/base.rb +4 -1
- data/lib/gemstash/cli/setup.rb +8 -1
- data/lib/gemstash/cli/start.rb +4 -1
- data/lib/gemstash/cli/status.rb +2 -0
- data/lib/gemstash/cli/stop.rb +2 -0
- data/lib/gemstash/config.ru +3 -3
- data/lib/gemstash/configuration.rb +7 -1
- data/lib/gemstash/db.rb +3 -0
- data/lib/gemstash/db/authorization.rb +2 -0
- data/lib/gemstash/db/cached_rubygem.rb +3 -0
- data/lib/gemstash/db/dependency.rb +2 -0
- data/lib/gemstash/db/rubygem.rb +3 -0
- data/lib/gemstash/db/upstream.rb +3 -0
- data/lib/gemstash/db/version.rb +3 -0
- data/lib/gemstash/dependencies.rb +4 -0
- data/lib/gemstash/env.rb +22 -4
- data/lib/gemstash/gem_fetcher.rb +2 -0
- data/lib/gemstash/gem_pusher.rb +5 -3
- data/lib/gemstash/gem_source.rb +2 -0
- data/lib/gemstash/gem_source/dependency_caching.rb +4 -4
- data/lib/gemstash/gem_source/private_source.rb +3 -0
- data/lib/gemstash/gem_source/rack_middleware.rb +3 -0
- data/lib/gemstash/gem_source/upstream_source.rb +9 -3
- data/lib/gemstash/gem_yanker.rb +4 -0
- data/lib/gemstash/health.rb +2 -0
- data/lib/gemstash/http_client.rb +4 -1
- data/lib/gemstash/logging.rb +2 -0
- data/lib/gemstash/man/gemstash-authorize.1 +51 -0
- data/lib/gemstash/man/gemstash-authorize.1.txt +33 -53
- data/lib/gemstash/man/gemstash-configuration.5 +229 -0
- data/lib/gemstash/man/gemstash-configuration.5.txt +150 -6
- data/lib/gemstash/man/gemstash-customize.7 +301 -0
- data/lib/gemstash/man/gemstash-customize.7.txt +183 -62
- data/lib/gemstash/man/gemstash-debugging.7 +34 -0
- data/lib/gemstash/man/gemstash-debugging.7.txt +17 -54
- data/lib/gemstash/man/gemstash-deploy.7 +72 -0
- data/lib/gemstash/man/gemstash-deploy.7.txt +44 -51
- data/lib/gemstash/man/gemstash-mirror.7 +40 -0
- data/lib/gemstash/man/gemstash-mirror.7.txt +20 -53
- data/lib/gemstash/man/gemstash-multiple-sources.7 +89 -0
- data/lib/gemstash/man/gemstash-multiple-sources.7.txt +53 -48
- data/lib/gemstash/man/gemstash-private-gems.7 +227 -0
- data/lib/gemstash/man/gemstash-private-gems.7.txt +108 -18
- data/lib/gemstash/man/gemstash-readme.7 +233 -0
- data/lib/gemstash/man/gemstash-readme.7.txt +126 -10
- data/lib/gemstash/man/gemstash-setup.1 +43 -0
- data/lib/gemstash/man/gemstash-setup.1.txt +28 -54
- data/lib/gemstash/man/gemstash-start.1 +26 -0
- data/lib/gemstash/man/gemstash-start.1.txt +16 -56
- data/lib/gemstash/man/gemstash-status.1 +20 -0
- data/lib/gemstash/man/gemstash-status.1.txt +13 -57
- data/lib/gemstash/man/gemstash-stop.1 +20 -0
- data/lib/gemstash/man/gemstash-stop.1.txt +13 -57
- data/lib/gemstash/man/gemstash-version.1 +22 -0
- data/lib/gemstash/man/gemstash-version.1.txt +12 -57
- data/lib/gemstash/migrations/01_gem_dependencies.rb +2 -0
- data/lib/gemstash/migrations/02_authorizations.rb +2 -0
- data/lib/gemstash/migrations/03_cached_gems.rb +2 -0
- data/lib/gemstash/migrations/04_health_tests.rb +2 -0
- data/lib/gemstash/puma.rb +2 -0
- data/lib/gemstash/rack_env_rewriter.rb +11 -2
- data/lib/gemstash/specs_builder.rb +5 -1
- data/lib/gemstash/storage.rb +12 -3
- data/lib/gemstash/upstream.rb +2 -0
- data/lib/gemstash/version.rb +3 -1
- data/lib/gemstash/web.rb +2 -0
- metadata +69 -22
@@ -1,66 +1,156 @@
|
|
1
|
+
gemstash-private-gems(7) gemstash-private-gems(7)
|
1
2
|
|
2
3
|
|
3
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
|
8
|
+
(../readme.md#quickstart-guide), you should do that first. By the end
|
9
|
+
of this guide, you will be able to interact with your Gemstash server
|
10
|
+
to store and retrieve your private gems.
|
4
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.
|
5
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:
|
6
21
|
|
22
|
+
$ gemstash authorize
|
23
|
+
Your new key is: e374e237fdf5fa5718d2a21bd63dc911
|
7
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:
|
8
29
|
|
30
|
+
$ gemstash authorize push yank --key e374e237fdf5fa5718d2a21bd63dc911
|
9
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 ev-
|
34
|
+
erything if you want to use it to try all private gem interactions:
|
10
35
|
|
36
|
+
$ gemstash authorize --key e374e237fdf5fa5718d2a21bd63dc911
|
11
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:
|
12
42
|
|
43
|
+
$ mkdir -p ~/.gem
|
44
|
+
$ touch ~/.gem/credentials
|
45
|
+
$ chmod 0600 ~/.gem/credentials
|
13
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):
|
14
49
|
|
50
|
+
# ~/.gem/credentials
|
51
|
+
---
|
52
|
+
:test_key: e374e237fdf5fa5718d2a21bd63dc911
|
15
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.
|
16
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:
|
17
61
|
|
62
|
+
$ bundle gem private-example
|
18
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.
|
19
67
|
|
68
|
+
$ cd private-example
|
69
|
+
$ rake build
|
20
70
|
|
71
|
+
You will now have a gem at private-example/pkg/private-exam-
|
72
|
+
ple-0.1.0.gem.
|
21
73
|
|
74
|
+
1mPUSHING0m
|
75
|
+
If your Gemstash server isn't running, go ahead and start it:
|
22
76
|
|
77
|
+
$ gemstash start
|
23
78
|
|
79
|
+
Push your test gem using Rubygems:
|
24
80
|
|
81
|
+
$ gem push --key test_key --host http://localhost:9292/private pkg/private-example-0.1.0.gem
|
25
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.
|
26
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:
|
27
92
|
|
93
|
+
# ./Gemfile
|
94
|
+
source "http://localhost:9292"
|
95
|
+
gem "rubywarrior"
|
28
96
|
|
97
|
+
source "http://localhost:9292/private" do
|
98
|
+
gem "private-example"
|
99
|
+
end
|
29
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:
|
30
104
|
|
105
|
+
$ bundle
|
31
106
|
|
107
|
+
1mYANKING0m
|
108
|
+
If you push a private gem by accident, you can yank the gem with
|
109
|
+
Rubygems:
|
32
110
|
|
111
|
+
$ RUBYGEMS_HOST=http://localhost:9292/private gem yank --key test_key private-example --version 0.1.0
|
33
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.
|
34
118
|
|
119
|
+
1mPROTECTED FETCHING0m
|
120
|
+
By default, private gems and specs can be accessed without authentica-
|
121
|
+
tion.
|
35
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.
|
36
126
|
|
127
|
+
When protected fetching is enabled API keys with the permissions all or
|
128
|
+
fetch can be used to download gems and specs.
|
37
129
|
|
130
|
+
On the Bundler side, there are a few ways to configure credentials for
|
131
|
+
a given gem source:
|
38
132
|
|
133
|
+
Add credentials globally:
|
39
134
|
|
135
|
+
$ bundle config my-gemstash.dev api_key
|
40
136
|
|
137
|
+
Add credentials in Gemfile:
|
41
138
|
|
139
|
+
source "https://api_key@my-gemstash.dev"
|
42
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.:
|
43
144
|
|
145
|
+
$ export BUNDLE_MYGEMSTASH__DEV=api_key
|
44
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.
|
45
150
|
|
151
|
+
The API key is treated as a HTTP Basic Auth username and any HTTP Basic
|
152
|
+
password supplied will be ignored.
|
46
153
|
|
47
154
|
|
48
155
|
|
49
|
-
|
50
|
-
|
51
|
-
|
52
|
-
|
53
|
-
|
54
|
-
|
55
|
-
|
56
|
-
|
57
|
-
|
58
|
-
|
59
|
-
|
60
|
-
|
61
|
-
|
62
|
-
|
63
|
-
|
64
|
-
|
65
|
-
|
66
|
-
|
156
|
+
October 8, 2015 gemstash-private-gems(7)
|
@@ -0,0 +1,233 @@
|
|
1
|
+
.\" Automatically generated by Pandoc 2.5
|
2
|
+
.\"
|
3
|
+
.TH "gemstash\-readme" "7" "November 30, 2015" "" ""
|
4
|
+
.hy
|
5
|
+
.SH GEMSTASH
|
6
|
+
.SS WHAT IS GEMSTASH?
|
7
|
+
.PP
|
8
|
+
Gemstash is both a cache for remote servers such as
|
9
|
+
https://rubygems.org, and a private gem source.
|
10
|
+
.PP
|
11
|
+
If you are using bundler (http://bundler.io/) across many machines that
|
12
|
+
have access to a server within your control, you might want to use
|
13
|
+
Gemstash.
|
14
|
+
.PP
|
15
|
+
If you produce gems that you don\[cq]t want everyone in the world to
|
16
|
+
have access to, you might want to use Gemstash.
|
17
|
+
.PP
|
18
|
+
If you frequently bundle the same set of gems across multiple projects,
|
19
|
+
you might want to use Gemstash.
|
20
|
+
.PP
|
21
|
+
Are you only using gems from https://rubygems.org, and don\[cq]t bundle
|
22
|
+
the same gems frequently?
|
23
|
+
Well, maybe you don\[cq]t need Gemstash\&... yet.
|
24
|
+
.PP
|
25
|
+
Gemstash is maintained by Ruby Together (https://rubytogether.org/), a
|
26
|
+
grassroots initiative committed to supporting the critical Ruby
|
27
|
+
infrastructure you rely on.
|
28
|
+
Contribute today as an individual (https://rubytogether.org/developers)
|
29
|
+
or even better, as a company (https://rubytogether.org/companies), and
|
30
|
+
ensure that Bundler, RubyGems, Gemstash, and other shared tooling is
|
31
|
+
around for years to come.
|
32
|
+
.SS QUICKSTART GUIDE
|
33
|
+
.SS SETUP
|
34
|
+
.PP
|
35
|
+
Gemstash is designed to be quick and painless to get set up.
|
36
|
+
By the end of this Quickstart Guide, you will be able to bundle stashed
|
37
|
+
gems from public sources against a Gemstash server running on your
|
38
|
+
machine.
|
39
|
+
.PP
|
40
|
+
Install Gemstash to get started:
|
41
|
+
.IP
|
42
|
+
.nf
|
43
|
+
\f[C]
|
44
|
+
$ gem install gemstash
|
45
|
+
\f[R]
|
46
|
+
.fi
|
47
|
+
.PP
|
48
|
+
After it is installed, starting Gemstash requires no additional steps.
|
49
|
+
Simply start the Gemstash server with the \f[C]gemstash\f[R] command:
|
50
|
+
.IP
|
51
|
+
.nf
|
52
|
+
\f[C]
|
53
|
+
$ gemstash start
|
54
|
+
\f[R]
|
55
|
+
.fi
|
56
|
+
.PP
|
57
|
+
You may have noticed that the command finished quickly.
|
58
|
+
This is because Gemstash will run the server in the background by
|
59
|
+
default.
|
60
|
+
The server runs on port 9292.
|
61
|
+
.SS BUNDLING
|
62
|
+
.PP
|
63
|
+
With the server running, you can bundle against it.
|
64
|
+
Tell Bundler that you want to use Gemstash to find gems from
|
65
|
+
RubyGems.org:
|
66
|
+
.IP
|
67
|
+
.nf
|
68
|
+
\f[C]
|
69
|
+
$ bundle config mirror.https://rubygems.org http://localhost:9292
|
70
|
+
\f[R]
|
71
|
+
.fi
|
72
|
+
.PP
|
73
|
+
Now you can create a Gemfile and install gems through Gemstash:
|
74
|
+
.IP
|
75
|
+
.nf
|
76
|
+
\f[C]
|
77
|
+
# ./Gemfile
|
78
|
+
source \[dq]https://rubygems.org\[dq]
|
79
|
+
gem \[dq]rubywarrior\[dq]
|
80
|
+
\f[R]
|
81
|
+
.fi
|
82
|
+
.PP
|
83
|
+
The gems you include should be gems you don\[cq]t yet have installed,
|
84
|
+
otherwise Gemstash will have nothing to stash.
|
85
|
+
Now bundle:
|
86
|
+
.IP
|
87
|
+
.nf
|
88
|
+
\f[C]
|
89
|
+
$ bundle install \-\-path .bundle
|
90
|
+
\f[R]
|
91
|
+
.fi
|
92
|
+
.PP
|
93
|
+
Your Gemstash server has fetched the gems from https://rubygems.org and
|
94
|
+
cached them for you! To prove this, you can disable your Internet
|
95
|
+
connection and try again.
|
96
|
+
Gem files (*.gem) are cached indefinitely.
|
97
|
+
Gem dependencies metadata are cached for 30 minutes, so if you bundle
|
98
|
+
again before that, you can successfully bundle without an Internet
|
99
|
+
connection:
|
100
|
+
.IP
|
101
|
+
.nf
|
102
|
+
\f[C]
|
103
|
+
$ # Disable your Internet first!
|
104
|
+
$ rm \-rf Gemfile.lock .bundle
|
105
|
+
$ bundle
|
106
|
+
\f[R]
|
107
|
+
.fi
|
108
|
+
.SS FALLING BACK TO RUBYGEMS.ORG
|
109
|
+
.PP
|
110
|
+
If you want to make sure that your bundling from https://rubygems.org
|
111
|
+
still works as expected when the Gemstash server is not running, you can
|
112
|
+
easily configure Bundler to fallback to https://rubygems.org.
|
113
|
+
.IP
|
114
|
+
.nf
|
115
|
+
\f[C]
|
116
|
+
$ bundle config mirror.https://rubygems.org.fallback_timeout true
|
117
|
+
\f[R]
|
118
|
+
.fi
|
119
|
+
.PP
|
120
|
+
You can also configure this fallback as a number of seconds in case the
|
121
|
+
Gemstash server is simply unresponsive.
|
122
|
+
This example uses a 3 second timeout:
|
123
|
+
.IP
|
124
|
+
.nf
|
125
|
+
\f[C]
|
126
|
+
$ bundle config mirror.https://rubygems.org.fallback_timeout 3
|
127
|
+
\f[R]
|
128
|
+
.fi
|
129
|
+
.SS STOPPING THE SERVER
|
130
|
+
.PP
|
131
|
+
Once you\[cq]ve finish using your Gemstash server, you can stop it just
|
132
|
+
as easily as you started it:
|
133
|
+
.IP
|
134
|
+
.nf
|
135
|
+
\f[C]
|
136
|
+
$ gemstash stop
|
137
|
+
\f[R]
|
138
|
+
.fi
|
139
|
+
.PP
|
140
|
+
You\[cq]ll also want to tell Bundler that it can go back to getting gems
|
141
|
+
from RubyGems.org directly, instead of going through Gemstash:
|
142
|
+
.IP
|
143
|
+
.nf
|
144
|
+
\f[C]
|
145
|
+
$ bundle config \-\-delete mirror.https://rubygems.org
|
146
|
+
\f[R]
|
147
|
+
.fi
|
148
|
+
.SS UNDER THE HOOD
|
149
|
+
.PP
|
150
|
+
You might wonder where the gems are stored.
|
151
|
+
After running the commands above, you will find a new directory at
|
152
|
+
\f[C]\[ti]/.gemstash\f[R].
|
153
|
+
This directory holds all the cached and private gems.
|
154
|
+
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).
|
157
|
+
.PP
|
158
|
+
Gemstash uses SQLite (https://www.sqlite.org/) to store details about
|
159
|
+
private gems.
|
160
|
+
The database will be located in \f[C]\[ti]/.gemstash\f[R], however you
|
161
|
+
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).
|
164
|
+
.PP
|
165
|
+
Gemstash temporarily caches things like gem dependencies in memory.
|
166
|
+
Anything cached in memory will last for 30 minutes before being
|
167
|
+
retrieved again.
|
168
|
+
You can use memcached (gemstash help customize.7) instead of caching in
|
169
|
+
memory.
|
170
|
+
Gem files are always cached permanently, so bundling with a
|
171
|
+
\f[C]Gemfile.lock\f[R] with all gems cached will never call out to
|
172
|
+
https://rubygems.org.
|
173
|
+
.PP
|
174
|
+
The server you ran is provided via Puma (http://puma.io/) and
|
175
|
+
Rack (http://rack.github.io/), however they are not customizable at this
|
176
|
+
point.
|
177
|
+
.SS DEEP DIVE
|
178
|
+
.PP
|
179
|
+
Deep dive into more subjects:
|
180
|
+
.IP \[bu] 2
|
181
|
+
Private gems (gemstash help private-gems.7)
|
182
|
+
.IP \[bu] 2
|
183
|
+
Multiple gem sources (gemstash help multiple-sources.7)
|
184
|
+
.IP \[bu] 2
|
185
|
+
Using Gemstash as a mirror (gemstash help mirror.7)
|
186
|
+
.IP \[bu] 2
|
187
|
+
Customizing the server (database, storage, caching, and
|
188
|
+
more) (gemstash help customize.7)
|
189
|
+
.IP \[bu] 2
|
190
|
+
Deploying Gemstash (gemstash help deploy.7)
|
191
|
+
.IP \[bu] 2
|
192
|
+
Debugging Gemstash (gemstash help debugging.7)
|
193
|
+
.SS REFERENCE
|
194
|
+
.PP
|
195
|
+
An anatomy of various configuration and commands:
|
196
|
+
.IP \[bu] 2
|
197
|
+
Configuration (gemstash help configuration.5)
|
198
|
+
.IP \[bu] 2
|
199
|
+
Authorize (gemstash help authorize.1)
|
200
|
+
.IP \[bu] 2
|
201
|
+
Start (gemstash help start.1)
|
202
|
+
.IP \[bu] 2
|
203
|
+
Stop (gemstash help stop.1)
|
204
|
+
.IP \[bu] 2
|
205
|
+
Status (gemstash help status.1)
|
206
|
+
.IP \[bu] 2
|
207
|
+
Setup (gemstash help setup.1)
|
208
|
+
.IP \[bu] 2
|
209
|
+
Version (gemstash help version.1)
|
210
|
+
.PP
|
211
|
+
To see what has changed in recent versions of Gemstash, see the
|
212
|
+
CHANGELOG (https://github.com/rubygems/gemstash/blob/master/CHANGELOG.md).
|
213
|
+
.SS DEVELOPMENT
|
214
|
+
.PP
|
215
|
+
After checking out the repo, run \f[C]bin/setup\f[R] to install
|
216
|
+
dependencies.
|
217
|
+
Then, run \f[C]rake\f[R] to run RuboCop and the tests.
|
218
|
+
While developing, you can run \f[C]bin/gemstash\f[R] to run Gemstash.
|
219
|
+
You can also run \f[C]bin/console\f[R] for an interactive prompt that
|
220
|
+
will allow you to experiment.
|
221
|
+
.SS CONTRIBUTING
|
222
|
+
.PP
|
223
|
+
Bug reports and pull requests are welcome on GitHub at
|
224
|
+
https://github.com/rubygems/gemstash.
|
225
|
+
This project is intended to be a safe, welcoming space for
|
226
|
+
collaboration, and contributors are expected to adhere to the
|
227
|
+
Contributor
|
228
|
+
Covenant (https://github.com/rubygems/gemstash/blob/master/CODE_OF_CONDUCT.md)
|
229
|
+
code of conduct.
|
230
|
+
.SS LICENSE
|
231
|
+
.PP
|
232
|
+
The gem is available as open source under the terms of the MIT
|
233
|
+
License (http://opensource.org/licenses/MIT).
|
@@ -1,66 +1,182 @@
|
|
1
|
+
gemstash-readme(7) gemstash-readme(7)
|
1
2
|
|
2
3
|
|
3
4
|
|
5
|
+
1mGEMSTASH0m
|
6
|
+
1mWHAT IS GEMSTASH?0m
|
7
|
+
Gemstash is both a cache for remote servers such as
|
8
|
+
https://rubygems.org, and a private gem source.
|
4
9
|
|
10
|
+
If you are using bundler (http://bundler.io/) across many machines that
|
11
|
+
have access to a server within your control, you might want to use Gem-
|
12
|
+
stash.
|
5
13
|
|
14
|
+
If you produce gems that you don't want everyone in the world to have
|
15
|
+
access to, you might want to use Gemstash.
|
6
16
|
|
17
|
+
If you frequently bundle the same set of gems across multiple projects,
|
18
|
+
you might want to use Gemstash.
|
7
19
|
|
20
|
+
Are you only using gems from https://rubygems.org, and don't bundle the
|
21
|
+
same gems frequently? Well, maybe you don't need Gemstash... yet.
|
8
22
|
|
23
|
+
Gemstash is maintained by Ruby Together (https://rubytogether.org/), a
|
24
|
+
grassroots initiative committed to supporting the critical Ruby infra-
|
25
|
+
structure you rely on. Contribute today as an individual
|
26
|
+
(https://rubytogether.org/developers) or even better, as a company
|
27
|
+
(https://rubytogether.org/companies), and ensure that Bundler,
|
28
|
+
RubyGems, Gemstash, and other shared tooling is around for years to
|
29
|
+
come.
|
9
30
|
|
31
|
+
1mQUICKSTART GUIDE0m
|
32
|
+
1mSETUP0m
|
33
|
+
Gemstash is designed to be quick and painless to get set up. By the
|
34
|
+
end of this Quickstart Guide, you will be able to bundle stashed gems
|
35
|
+
from public sources against a Gemstash server running on your machine.
|
10
36
|
|
37
|
+
Install Gemstash to get started:
|
11
38
|
|
39
|
+
$ gem install gemstash
|
12
40
|
|
41
|
+
After it is installed, starting Gemstash requires no additional steps.
|
42
|
+
Simply start the Gemstash server with the gemstash command:
|
13
43
|
|
44
|
+
$ gemstash start
|
14
45
|
|
46
|
+
You may have noticed that the command finished quickly. This is be-
|
47
|
+
cause Gemstash will run the server in the background by default. The
|
48
|
+
server runs on port 9292.
|
15
49
|
|
50
|
+
1mBUNDLING0m
|
51
|
+
With the server running, you can bundle against it. Tell Bundler that
|
52
|
+
you want to use Gemstash to find gems from RubyGems.org:
|
16
53
|
|
54
|
+
$ bundle config mirror.https://rubygems.org http://localhost:9292
|
17
55
|
|
56
|
+
Now you can create a Gemfile and install gems through Gemstash:
|
18
57
|
|
58
|
+
# ./Gemfile
|
59
|
+
source "https://rubygems.org"
|
60
|
+
gem "rubywarrior"
|
19
61
|
|
62
|
+
The gems you include should be gems you don't yet have installed, oth-
|
63
|
+
erwise Gemstash will have nothing to stash. Now bundle:
|
20
64
|
|
65
|
+
$ bundle install --path .bundle
|
21
66
|
|
67
|
+
Your Gemstash server has fetched the gems from https://rubygems.org and
|
68
|
+
cached them for you! To prove this, you can disable your Internet con-
|
69
|
+
nection and try again. Gem files (*.gem) are cached indefinitely. Gem
|
70
|
+
dependencies metadata are cached for 30 minutes, so if you bundle again
|
71
|
+
before that, you can successfully bundle without an Internet connec-
|
72
|
+
tion:
|
22
73
|
|
74
|
+
$ # Disable your Internet first!
|
75
|
+
$ rm -rf Gemfile.lock .bundle
|
76
|
+
$ bundle
|
23
77
|
|
78
|
+
1mFALLING BACK TO RUBYGEMS.ORG0m
|
79
|
+
If you want to make sure that your bundling from https://rubygems.org
|
80
|
+
still works as expected when the Gemstash server is not running, you
|
81
|
+
can easily configure Bundler to fallback to https://rubygems.org.
|
24
82
|
|
83
|
+
$ bundle config mirror.https://rubygems.org.fallback_timeout true
|
25
84
|
|
85
|
+
You can also configure this fallback as a number of seconds in case the
|
86
|
+
Gemstash server is simply unresponsive. This example uses a 3 second
|
87
|
+
timeout:
|
26
88
|
|
89
|
+
$ bundle config mirror.https://rubygems.org.fallback_timeout 3
|
27
90
|
|
91
|
+
1mSTOPPING THE SERVER0m
|
92
|
+
Once you've finish using your Gemstash server, you can stop it just as
|
93
|
+
easily as you started it:
|
28
94
|
|
95
|
+
$ gemstash stop
|
29
96
|
|
97
|
+
You'll also want to tell Bundler that it can go back to getting gems
|
98
|
+
from RubyGems.org directly, instead of going through Gemstash:
|
30
99
|
|
100
|
+
$ bundle config --delete mirror.https://rubygems.org
|
31
101
|
|
102
|
+
1mUNDER THE HOOD0m
|
103
|
+
You might wonder where the gems are stored. After running the commands
|
104
|
+
above, you will find a new directory at ~/.gemstash. This directory
|
105
|
+
holds all the cached and private gems. It also has a server log, the
|
106
|
+
database, and configuration for Gemstash. If you prefer, you can point
|
107
|
+
to a different directory (gemstash help customize.7).
|
32
108
|
|
109
|
+
Gemstash uses SQLite (https://www.sqlite.org/) to store details about
|
110
|
+
private gems. The database will be located in ~/.gemstash, however you
|
111
|
+
won't see the database appear until you start using private gems. If
|
112
|
+
you prefer, you can use a different database (gemstash help custom-
|
113
|
+
ize.7).
|
33
114
|
|
115
|
+
Gemstash temporarily caches things like gem dependencies in memory.
|
116
|
+
Anything cached in memory will last for 30 minutes before being re-
|
117
|
+
trieved again. You can use memcached (gemstash help customize.7) in-
|
118
|
+
stead of caching in memory. Gem files are always cached permanently,
|
119
|
+
so bundling with a Gemfile.lock with all gems cached will never call
|
120
|
+
out to https://rubygems.org.
|
34
121
|
|
122
|
+
The server you ran is provided via Puma (http://puma.io/) and Rack
|
123
|
+
(http://rack.github.io/), however they are not customizable at this
|
124
|
+
point.
|
35
125
|
|
126
|
+
1mDEEP DIVE0m
|
127
|
+
Deep dive into more subjects:
|
36
128
|
|
129
|
+
o Private gems (gemstash help private-gems.7)
|
37
130
|
|
131
|
+
o Multiple gem sources (gemstash help multiple-sources.7)
|
38
132
|
|
133
|
+
o Using Gemstash as a mirror (gemstash help mirror.7)
|
39
134
|
|
135
|
+
o Customizing the server (database, storage, caching, and more) (gem-
|
136
|
+
stash help customize.7)
|
40
137
|
|
138
|
+
o Deploying Gemstash (gemstash help deploy.7)
|
41
139
|
|
140
|
+
o Debugging Gemstash (gemstash help debugging.7)
|
42
141
|
|
142
|
+
1mREFERENCE0m
|
143
|
+
An anatomy of various configuration and commands:
|
43
144
|
|
145
|
+
o Configuration (gemstash help configuration.5)
|
44
146
|
|
147
|
+
o Authorize (gemstash help authorize.1)
|
45
148
|
|
149
|
+
o Start (gemstash help start.1)
|
46
150
|
|
151
|
+
o Stop (gemstash help stop.1)
|
47
152
|
|
153
|
+
o Status (gemstash help status.1)
|
48
154
|
|
155
|
+
o Setup (gemstash help setup.1)
|
49
156
|
|
157
|
+
o Version (gemstash help version.1)
|
50
158
|
|
159
|
+
To see what has changed in recent versions of Gemstash, see the
|
160
|
+
CHANGELOG (https://github.com/rubygems/gemstash/blob/master/CHANGEL-
|
161
|
+
OG.md).
|
51
162
|
|
163
|
+
1mDEVELOPMENT0m
|
164
|
+
After checking out the repo, run bin/setup to install dependencies.
|
165
|
+
Then, run rake to run RuboCop and the tests. While developing, you can
|
166
|
+
run bin/gemstash to run Gemstash. You can also run bin/console for an
|
167
|
+
interactive prompt that will allow you to experiment.
|
52
168
|
|
169
|
+
1mCONTRIBUTING0m
|
170
|
+
Bug reports and pull requests are welcome on GitHub at
|
171
|
+
https://github.com/rubygems/gemstash. This project is intended to be a
|
172
|
+
safe, welcoming space for collaboration, and contributors are expected
|
173
|
+
to adhere to the Contributor Covenant (https://github.com/rubygems/gem-
|
174
|
+
stash/blob/master/CODE_OF_CONDUCT.md) code of conduct.
|
53
175
|
|
176
|
+
1mLICENSE0m
|
177
|
+
The gem is available as open source under the terms of the MIT License
|
178
|
+
(http://opensource.org/licenses/MIT).
|
54
179
|
|
55
180
|
|
56
181
|
|
57
|
-
|
58
|
-
|
59
|
-
|
60
|
-
|
61
|
-
|
62
|
-
|
63
|
-
|
64
|
-
|
65
|
-
|
66
|
-
|
182
|
+
November 30, 2015 gemstash-readme(7)
|