4mgemstash-readme24m(7) 4mgemstash-readme24m(7)

<!– Automatically generated by Pandoc –>

1mGemstash0m

1mWhat is Gemstash?0m
    Gemstash    is    both   a   cache   for   remote   servers   such   as
    https://rubygems.org, and a private gem source.

    If you are using bundler  (https://bundler.io/)  across  many  machines
    that have access to a server within your control, you might want to use
    Gemstash.

    If  you  produce gems that you don't want everyone in the world to have
    access to, you might want to use Gemstash.

    If you frequently bundle the same set of gems across multiple projects,
    you might want to use Gemstash.

    Are you only using gems from https://rubygems.org, and don't bundle the
    same gems frequently?  Well, maybe you don't need Gemstash...  yet.

    Gemstash is maintained by Ruby  Central  (https://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 com-
    pany   (https://rubycentral.org/#/portal/signup),   and   ensure   that
    Bundler,  RubyGems,  Gemstash,  and  other shared tooling is around for
    years to come.

1mQuickstart Guide0m
1mSetup0m
    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.

    Install Gemstash to get started:

           $ gem install gemstash

    After it is installed, starting Gemstash requires no additional  steps.
    Simply start the Gemstash server with the gemstash command:

           $ gemstash start

    You  may  have  noticed that the command finished quickly.  This is be-
    cause Gemstash will run the server in the background by  default.   The
    server runs on port 9292.

1mBundling0m
    With  the server running, you can bundle against it.  Tell Bundler that
    you want to use Gemstash to find gems from RubyGems.org:

           $ bundle config mirror.https://rubygems.org http://localhost:9292

    Now you can create a Gemfile and install gems through Gemstash:

           # ./Gemfile
           source "https://rubygems.org"
           gem "rubywarrior"

    The gems you include should be gems you don't yet have installed,  oth-
    erwise Gemstash will have nothing to stash.  Now bundle:

           $ bundle install --path .bundle

    Your Gemstash server has fetched the gems from https://rubygems.org and
    cached them for you!  To prove this, you can disable your Internet con-
    nection 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 connec-
    tion:

           $ # Disable your Internet first!
           $ rm -rf Gemfile.lock .bundle
           $ bundle

1mFalling back to rubygems.org0m
    If you want to make sure that your bundling  from  https://rubygems.org
    still  works  as  expected when the Gemstash server is not running, you
    can easily configure Bundler to fallback to https://rubygems.org.

           $ bundle config mirror.https://rubygems.org.fallback_timeout true

    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:

           $ bundle config mirror.https://rubygems.org.fallback_timeout 3

1mStopping the Server0m
    Once  you've finish using your Gemstash server, you can stop it just as
    easily as you started it:

           $ gemstash stop

    You'll also want to tell Bundler that it can go back  to  getting  gems
    from RubyGems.org directly, instead of going through Gemstash:

           $ bundle config --delete mirror.https://rubygems.org

1mUnder the Hood0m
    You might wonder where the gems are stored.  After running the commands
    above,  you  will  find a new directory at ~/.gemstash.  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.

    Gemstash  uses  SQLite (https://www.sqlite.org/) to store details about
    private gems.  The database will be located in ~/.gemstash, however you
    won't see the database appear until you start using private  gems.   If
    you prefer, you can use a different database.

    Gemstash  temporarily  caches  things  like gem dependencies in memory.
    Anything cached in memory will last for 30  minutes  before  being  re-
    trieved  again.   You  can  use memcached instead of caching in memory.
    Gem files are always  cached  permanently,  so  bundling  with  a  Gem-
    file.lock   with   all   gems   cached   will   never   call   out   to
    https://rubygems.org.

    The server you ran is provided via  Puma  (https://puma.io/)  and  Rack
    (https://github.com/rack/rack),  however  they  are not customizable at
    this point.

1mDeep Dive0m
    Deep dive into more subjects:

    o Private gems

    o Multiple gem sources

    o Using Gemstash as a mirror

    o Customizing the server (database, storage, caching, and more)

    o Deploying Gemstash

    o Debugging Gemstash

1mReference0m
    An anatomy of various configuration and commands:

    o Configuration

    o Authorize

    o Start

    o Stop

    o Status

    o Setup

    o Version

    To see what has  changed  in  recent  versions  of  Gemstash,  see  the
    CHANGELOG                             (https://github.com/rubygems/gem-
    stash/blob/main/CHANGELOG.md).

1mDevelopment0m
    After checking out the repo, run  bin/setup  to  install  dependencies.
    Then, run rake to run RuboCop and the tests.  While developing, you can
    run  bin/gemstash to run Gemstash.  You can also run bin/console for an
    interactive prompt that will allow you to experiment.

1mContributing0m
    Bug  reports   and   pull   requests   are   welcome   on   GitHub   at
    https://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 (https://github.com/rubygems/gem-
    stash/blob/main/CODE_OF_CONDUCT.md) code of conduct.

1mLicense0m
    The gem is available as open source under the terms of the MIT  License
    (http://opensource.org/licenses/MIT).

                            November 30, 2015            4mgemstash-readme24m(7)