<!– Automatically generated by Pandoc –> ." Automatically generated by Pandoc 3.1.8 ." .TH “gemstash-readme” “7” “November 30, 2015” “” “” .SH Gemstash
.SS What is Gemstash
? Gemstash
is both a cache for remote servers such as rubygems.org, and a private gem source. .PP If you are using bundler (bundler.io/) across many machines that have access to a server within your control, you might want to use Gemstash
. .PP If you produce gems that you dont want everyone in the world to have access to, you might want to use Gemstash
. .PP If you frequently bundle the same set of gems across multiple projects, you might want to use Gemstash
. .PP Are you only using gems from rubygems.org, and dont bundle the same gems frequently? Well, maybe you dont need Gemstash&… yet. .PP Gemstash
is maintained by Ruby Central (rubycentral.org/), a non-profit committed to supporting the critical Ruby infrastructure you rely on. Contribute today as an individual, or even better, as a company (rubycentral.org/#/portal/signup), and ensure that Bundler, RubyGems, Gemstash
, and other shared tooling is around for years to come. .SS Quickstart Guide .SS Setup Gemstash
is designed to be quick and painless to get set up. By the end of this Quickstart Guide, you will be able to bundle stashed gems from public sources against a Gemstash
server running on your machine. .PP Install Gemstash
to get started: .IP .EX $ gem install gemstash .EE .PP After it is installed, starting Gemstash
requires no additional steps. Simply start the Gemstash
server with the f[CR]gemstashf[R] command: .IP .EX $ gemstash start .EE .PP You may have noticed that the command finished quickly. This is because Gemstash
will run the server in the background by default. The server runs on port 9292. .SS Bundling With the server running, you can bundle against it. Tell Bundler that you want to use Gemstash
to find gems from RubyGems.org: .IP .EX $ bundle config mirror.https://rubygems.org localhost:9292 .EE .PP Now you can create a Gemfile and install gems through Gemstash: .IP .EX # ./Gemfile source [dq]https://rubygems.org[dq] gem [dq]rubywarrior[dq] .EE .PP The gems you include should be gems you dont yet have installed, otherwise Gemstash
will have nothing to stash. Now bundle: .IP .EX $ bundle install –path .bundle .EE .PP Your Gemstash
server has fetched the gems from rubygems.org and cached them for you! To prove this, you can disable your Internet connection and try again. Gem files (*.gem) are cached indefinitely. Gem dependencies metadata are cached for 30 minutes, so if you bundle again before that, you can successfully bundle without an Internet connection: .IP .EX $ # Disable your Internet first! $ rm -rf Gemfile.lock .bundle $ bundle .EE .SS Falling back to rubygems.org If you want to make sure that your bundling from rubygems.org still works as expected when the Gemstash
server is not running, you can easily configure Bundler to fallback to rubygems.org. .IP .EX $ bundle config mirror.https://rubygems.org.fallback_timeout true .EE .PP You can also configure this fallback as a number of seconds in case the Gemstash
server is simply unresponsive. This example uses a 3 second timeout: .IP .EX $ bundle config mirror.https://rubygems.org.fallback_timeout 3 .EE .SS Stopping the Server Once youve finish using your Gemstash
server, you can stop it just as easily as you started it: .IP .EX $ gemstash stop .EE .PP Youll also want to tell Bundler that it can go back to getting gems from RubyGems.org directly, instead of going through Gemstash: .IP .EX $ bundle config –delete mirror.https://rubygems.org .EE .SS Under the Hood You might wonder where the gems are stored. After running the commands above, you will find a new directory at f[CR][ti]/.gemstashf. This directory holds all the cached and private gems. It also has a server log, the database, and configuration for Gemstash
. If you prefer, you can point to a different directory. .PP Gemstash
uses SQLite (www.sqlite.org/) to store details about private gems. The database will be located in f[CR][ti]/.gemstashf, however you wont see the database appear until you start using private gems. If you prefer, you can use a different database. .PP Gemstash
temporarily caches things like gem dependencies in memory. Anything cached in memory will last for 30 minutes before being retrieved again. You can use memcached instead of caching in memory. Gem files are always cached permanently, so bundling with a f[CR]Gemfile.lockf[R] with all gems cached will never call out to rubygems.org. .PP The server you ran is provided via Puma (puma.io/) and Rack (github.com/rack/rack), however they are not customizable at this point. .SS Deep Dive Deep dive into more subjects: .IP [bu] 2 Private gems .IP [bu] 2 Multiple gem sources .IP [bu] 2 Using Gemstash
as a mirror .IP [bu] 2 Customizing the server (database, storage, caching, and more) .IP [bu] 2 Deploying Gemstash
.IP [bu] 2 Debugging Gemstash
.SS Reference An anatomy of various configuration and commands: .IP [bu] 2 Configuration .IP [bu] 2 Authorize .IP [bu] 2 Start .IP [bu] 2 Stop .IP [bu] 2 Status .IP [bu] 2 Setup .IP [bu] 2 Version .PP To see what has changed in recent versions of Gemstash
, see the CHANGELOG (github.com/rubygems/gemstash/blob/main/CHANGELOG.md). .SS Development After checking out the repo, run f[CR]bin/setupf[R] to install dependencies. Then, run f[CR]rakef[R] to run RuboCop and the tests. While developing, you can run f[CR]bin/gemstashf[R] to run Gemstash
. You can also run f[CR]bin/consolef[R] for an interactive prompt that will allow you to experiment. .SS Contributing Bug reports and pull requests are welcome on GitHub at github.com/rubygems/gemstash. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant (github.com/rubygems/gemstash/blob/main/CODE_OF_CONDUCT.md) code of conduct. .SS License The gem is available as open source under the terms of the MIT License (opensource.org/licenses/MIT).