gemstash 1.1.0 → 2.0.0

data/lib/gemstash/man/gemstash-private-gems.7

@@ -1,244 +0,0 @@
-.\" Automatically generated by Pandoc 1.19.2.1
-.\"
-.TH "gemstash\-private\-gems" "7" "October 8, 2015" "" ""
-.hy
-.SH PRIVATE GEMS
-.PP
-Stashing private gems in your Gemstash server requires a bit of
-additional setup.
-If you haven\[aq]t read through the Quickstart
-Guide (gemstash help readme.7), you should do that first.
-By the end of this guide, you will be able to interact with your
-Gemstash server to store and retrieve your private gems.
-.SS AUTHORIZING
-.PP
-\f[B]IMPORTANT NOTE:\f[] Do not use the actual key value in this
-document, otherwise your Gemstash server will be vulnerable to anyone
-who wants to try to use the key against your server.
-Instead of the key value here, use whatever key is generated from
-running the commands.
-.PP
-In order to push a gem to your Gemstash server, you need to first create
-an API key.
-Utilize the \f[C]gemstash\ authorize\f[] command to create the API key:
-.IP
-.nf
-\f[C]
-$\ gemstash\ authorize
-Your\ new\ key\ is:\ e374e237fdf5fa5718d2a21bd63dc911
-\f[]
-.fi
-.PP
-This new key can \f[C]push\f[], \f[C]yank\f[], \f[C]unyank\f[], and
-\f[C]fetch\f[] gems from your Gemstash server.
-Run \f[C]gemstash\ authorize\f[] with just the permissions you want to
-limit what the key will be allowed to do.
-You can similarly update a specific key by providing it via the
-\f[C]\-\-key\f[] option:
-.IP
-.nf
-\f[C]
-$\ gemstash\ authorize\ push\ yank\ \-\-key\ e374e237fdf5fa5718d2a21bd63dc911
-\f[]
-.fi
-.PP
-When no permissions are provided (like the first example), the key will
-be authorized for all permissions.
-Leave the key authorized with everything if you want to use it to try
-all private gem interactions:
-.IP
-.nf
-\f[C]
-$\ gemstash\ authorize\ \-\-key\ e374e237fdf5fa5718d2a21bd63dc911
-\f[]
-.fi
-.PP
-With the key generated, you\[aq]ll need to tell Rubygems about your new
-key.
-If you\[aq]ve pushed a gem to https://rubygems.org, then you will
-already have a credentials file to add the key to.
-If not, run the following commands before modifying the credentials
-file:
-.IP
-.nf
-\f[C]
-$\ mkdir\ \-p\ ~/.gem
-$\ touch\ ~/.gem/credentials
-$\ chmod\ 0600\ ~/.gem/credentials
-\f[]
-.fi
-.PP
-Add your new key to credentials such that it looks something like this
-(but make sure not to remove any existing keys):
-.IP
-.nf
-\f[C]
-#\ ~/.gem/credentials
-\-\-\-
-:test_key:\ e374e237fdf5fa5718d2a21bd63dc911
-\f[]
-.fi
-.PP
-The name \f[C]test_key\f[] can be anything you want, but you will need
-to remember it and use it again later in this guide for the
-\f[C]\-\-key\f[] option.
-.SS CREATING A TEST GEM
-.PP
-You\[aq]ll need a test gem before you can play with private gems on your
-Gemstash server.
-If you have a gem you can use, move along to the next section.
-You can start by instantiating a test gem via Bundler:
-.IP
-.nf
-\f[C]
-$\ bundle\ gem\ private\-example
-\f[]
-.fi
-.PP
-You\[aq]ll need to add a summary and description to the new gem\[aq]s
-gemspec file in order to successfully build it.
-Once you\[aq]ve built the gem, you will be ready to push the new gem.
-.IP
-.nf
-\f[C]
-$\ cd\ private\-example
-$\ rake\ build
-\f[]
-.fi
-.PP
-You will now have a gem at
-\f[C]private\-example/pkg/private\-example\-0.1.0.gem\f[].
-.SS PUSHING
-.PP
-If your Gemstash server isn\[aq]t running, go ahead and start it:
-.IP
-.nf
-\f[C]
-$\ gemstash\ start
-\f[]
-.fi
-.PP
-Push your test gem using Rubygems:
-.IP
-.nf
-\f[C]
-$\ gem\ push\ \-\-key\ test_key\ \-\-host\ http://localhost:9292/private\ pkg/private\-example\-0.1.0.gem
-\f[]
-.fi
-.PP
-The \f[C]/private\f[] portion of the \f[C]\-\-host\f[] option tells
-Gemstash you are interacting with the private gems.
-Gemstash will not let you push, yank, or unyank from anything except
-\f[C]/private\f[].
-.SS BUNDLING
-.PP
-Once your gem is pushed to your Gemstash server, you are ready to bundle
-it.
-Create a \f[C]Gemfile\f[] and specify the gem.
-You will probably want to wrap the private gem in a source block, and
-let the rest of Gemstash handle all other gems:
-.IP
-.nf
-\f[C]
-#\ ./Gemfile
-source\ "http://localhost:9292"
-gem\ "rubywarrior"
-
-source\ "http://localhost:9292/private"\ do
-\ \ gem\ "private\-example"
-end
-\f[]
-.fi
-.PP
-Notice that the Gemstash server points to \f[C]/private\f[] again when
-installing your private gem.
-Go ahead and bundle to install your new private gem:
-.IP
-.nf
-\f[C]
-$\ bundle
-\f[]
-.fi
-.SS YANKING
-.PP
-If you push a private gem by accident, you can yank the gem with
-Rubygems:
-.IP
-.nf
-\f[C]
-$\ RUBYGEMS_HOST=http://localhost:9292/private\ gem\ yank\ \-\-key\ test_key\ private\-example\ \-\-version\ 0.1.0
-\f[]
-.fi
-.PP
-Like with pushing, the \f[C]/private\f[] portion of the host option
-tells Gemstash you are interacting with private gems.
-Gemstash will only let you yank from \f[C]/private\f[].
-Unlike pushing, Rubygems doesn\[aq]t support \f[C]\-\-host\f[] for yank
-and unyank (yet), so you need to specify the host via the
-\f[C]RUBYGEMS_HOST\f[] environment variable.
-.SS UNYANKING
-.PP
-If you yank a private gem by accident, you can unyank the gem with
-Rubygems:
-.IP
-.nf
-\f[C]
-$\ RUBYGEMS_HOST=http://localhost:9292/private\ gem\ yank\ \-\-key\ test_key\ private\-example\ \-\-version\ 0.1.0\ \-\-undo
-\f[]
-.fi
-.PP
-Like with pushing and yanking, the \f[C]/private\f[] portion of the host
-option tells Gemstash you are interacting with private gems.
-Gemstash will only let you unyank from \f[C]/private\f[].
-Unlike pushing, Rubygems doesn\[aq]t support \f[C]\-\-host\f[] for
-unyank and yank (yet), so you need to specify the host via the
-\f[C]RUBYGEMS_HOST\f[] environment variable.
-.SS PROTECTED FETCHING
-.PP
-By default, private gems and specs can be accessed without
-authentication.
-.PP
-Private gems often require protected fetching.
-For backwards compatibility this is disabled by default, but can be
-enabled via \f[C]$\ gemstash\ setup\f[] command.
-.PP
-When protected fetching is enabled API keys with the permissions
-\f[C]all\f[] or \f[C]fetch\f[] can be used to download gems and specs.
-.PP
-On the Bundler side, there are a few ways to configure credentials for a
-given gem source:
-.PP
-Add credentials globally:
-.IP
-.nf
-\f[C]
-$\ bundle\ config\ my\-gemstash.dev\ api_key
-\f[]
-.fi
-.PP
-Add credentials in Gemfile:
-.IP
-.nf
-\f[C]
-source\ "https://api_key\@my\-gemstash.dev"
-\f[]
-.fi
-.PP
-However, it\[aq]s not a good practice to commit credentials to source
-control.
-A recommended solution is to use Bundler\[aq]s configuration
-keys (http://bundler.io/man/bundle-config.1.html#CONFIGURATION-KEYS),
-e.g.:
-.IP
-.nf
-\f[C]
-$\ export\ BUNDLE_MYGEMSTASH__DEV=api_key
-\f[]
-.fi
-.PP
-Behind the scene, Bundler will pick up the ENV var according to the host
-name (e.g.
-mygemstash.dev) and add to \f[C]URI.userinfo\f[] for making requests.
-.PP
-The API key is treated as a HTTP Basic Auth username and any HTTP Basic
-password supplied will be ignored.

data/lib/gemstash/man/gemstash-readme.7

@@ -1,234 +0,0 @@
-.\" Automatically generated by Pandoc 1.19.2.1
-.\"
-.TH "gemstash\-readme" "7" "November 30, 2015" "" ""
-.hy
-.SH GEMSTASH
-.SS WHAT IS GEMSTASH?
-.PP
-Gemstash is both a cache for remote servers such as
-https://rubygems.org, and a private gem source.
-.PP
-If you are using bundler (http://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 don\[aq]t 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 https://rubygems.org, and don\[aq]t bundle
-the same gems frequently?
-Well, maybe you don\[aq]t need Gemstash...
-yet.
-.PP
-Gemstash is maintained by Ruby Together (https://rubytogether.org/), a
-grassroots initiative committed to supporting the critical Ruby
-infrastructure you rely on.
-Contribute today as an individual (https://rubytogether.org/developers)
-or even better, as a company (https://rubytogether.org/companies), and
-ensure that Bundler, RubyGems, Gemstash, and other shared tooling is
-around for years to come.
-.SS QUICKSTART GUIDE
-.SS SETUP
-.PP
-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
-.nf
-\f[C]
-$\ gem\ install\ gemstash
-\f[]
-.fi
-.PP
-After it is installed, starting Gemstash requires no additional steps.
-Simply start the Gemstash server with the \f[C]gemstash\f[] command:
-.IP
-.nf
-\f[C]
-$\ gemstash\ start
-\f[]
-.fi
-.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
-.PP
-With the server running, you can bundle against it.
-Tell Bundler that you want to use Gemstash to find gems from
-RubyGems.org:
-.IP
-.nf
-\f[C]
-$\ bundle\ config\ mirror.https://rubygems.org\ http://localhost:9292
-\f[]
-.fi
-.PP
-Now you can create a Gemfile and install gems through Gemstash:
-.IP
-.nf
-\f[C]
-#\ ./Gemfile
-source\ "https://rubygems.org"
-gem\ "rubywarrior"
-\f[]
-.fi
-.PP
-The gems you include should be gems you don\[aq]t yet have installed,
-otherwise Gemstash will have nothing to stash.
-Now bundle:
-.IP
-.nf
-\f[C]
-$\ bundle\ install\ \-\-path\ .bundle
-\f[]
-.fi
-.PP
-Your Gemstash server has fetched the gems from https://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
-.nf
-\f[C]
-$\ #\ Disable\ your\ Internet\ first!
-$\ rm\ \-rf\ Gemfile.lock\ .bundle
-$\ bundle
-\f[]
-.fi
-.SS FALLING BACK TO RUBYGEMS.ORG
-.PP
-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.
-.IP
-.nf
-\f[C]
-$\ bundle\ config\ mirror.https://rubygems.org.fallback_timeout\ true
-\f[]
-.fi
-.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
-.nf
-\f[C]
-$\ bundle\ config\ mirror.https://rubygems.org.fallback_timeout\ 3
-\f[]
-.fi
-.SS STOPPING THE SERVER
-.PP
-Once you\[aq]ve finish using your Gemstash server, you can stop it just
-as easily as you started it:
-.IP
-.nf
-\f[C]
-$\ gemstash\ stop
-\f[]
-.fi
-.PP
-You\[aq]ll also want to tell Bundler that it can go back to getting gems
-from RubyGems.org directly, instead of going through Gemstash:
-.IP
-.nf
-\f[C]
-$\ bundle\ config\ \-\-delete\ mirror.https://rubygems.org
-\f[]
-.fi
-.SS UNDER THE HOOD
-.PP
-You might wonder where the gems are stored.
-After running the commands above, you will find a new directory at
-\f[C]~/.gemstash\f[].
-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 help customize.7).
-.PP
-Gemstash uses SQLite (https://www.sqlite.org/) to store details about
-private gems.
-The database will be located in \f[C]~/.gemstash\f[], however you
-won\[aq]t see the database appear until you start using private gems.
-If you prefer, you can use a different
-database (gemstash help customize.7).
-.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 (gemstash help customize.7) instead of caching in
-memory.
-Gem files are always cached permanently, so bundling with a
-\f[C]Gemfile.lock\f[] with all gems cached will never call out to
-https://rubygems.org.
-.PP
-The server you ran is provided via Puma (http://puma.io/) and
-Rack (http://rack.github.io/), however they are not customizable at this
-point.
-.SS DEEP DIVE
-.PP
-Deep dive into more subjects:
-.IP \[bu] 2
-Private gems (gemstash help private-gems.7)
-.IP \[bu] 2
-Multiple gem sources (gemstash help multiple-sources.7)
-.IP \[bu] 2
-Using Gemstash as a mirror (gemstash help mirror.7)
-.IP \[bu] 2
-Customizing the server (database, storage, caching, and
-more) (gemstash help customize.7)
-.IP \[bu] 2
-Deploying Gemstash (gemstash help deploy.7)
-.IP \[bu] 2
-Debugging Gemstash (gemstash help debugging.7)
-.SS REFERENCE
-.PP
-An anatomy of various configuration and commands:
-.IP \[bu] 2
-Configuration (gemstash help configuration.5)
-.IP \[bu] 2
-Authorize (gemstash help authorize.1)
-.IP \[bu] 2
-Start (gemstash help start.1)
-.IP \[bu] 2
-Stop (gemstash help stop.1)
-.IP \[bu] 2
-Status (gemstash help status.1)
-.IP \[bu] 2
-Setup (gemstash help setup.1)
-.IP \[bu] 2
-Version (gemstash help version.1)
-.PP
-To see what has changed in recent versions of Gemstash, see the
-CHANGELOG (https://github.com/bundler/gemstash/blob/master/CHANGELOG.md).
-.SS DEVELOPMENT
-.PP
-After checking out the repo, run \f[C]bin/setup\f[] to install
-dependencies.
-Then, run \f[C]rake\f[] to run RuboCop and the tests.
-While developing, you can run \f[C]bin/gemstash\f[] to run Gemstash.
-You can also run \f[C]bin/console\f[] for an interactive prompt that
-will allow you to experiment.
-.SS CONTRIBUTING
-.PP
-Bug reports and pull requests are welcome on GitHub at
-https://github.com/bundler/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/bundler/gemstash/blob/master/CODE_OF_CONDUCT.md)
-code of conduct.
-.SS LICENSE
-.PP
-The gem is available as open source under the terms of the MIT
-License (http://opensource.org/licenses/MIT).