gemstash 2.1.0 → 2.2.0

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

@@ -1,227 +0,0 @@
-.\" Automatically generated by Pandoc 2.5
-.\"
-.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\[cq]t read through the Quickstart
-Guide (../readme.md#quickstart-guide), 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[R] 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[R] command to create the API key:
-.IP
-.nf
-\f[C]
-$ gemstash authorize
-Your new key is: e374e237fdf5fa5718d2a21bd63dc911
-\f[R]
-.fi
-.PP
-This new key can \f[C]push\f[R], \f[C]yank\f[R], and \f[C]fetch\f[R]
-gems from your Gemstash server.
-Run \f[C]gemstash authorize\f[R] 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[R] option:
-.IP
-.nf
-\f[C]
-$ gemstash authorize push yank \-\-key e374e237fdf5fa5718d2a21bd63dc911
-\f[R]
-.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[R]
-.fi
-.PP
-With the key generated, you\[cq]ll need to tell Rubygems about your new
-key.
-If you\[cq]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 \[ti]/.gem
-$ touch \[ti]/.gem/credentials
-$ chmod 0600 \[ti]/.gem/credentials
-\f[R]
-.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]
-# \[ti]/.gem/credentials
-\-\-\-
-:test_key: e374e237fdf5fa5718d2a21bd63dc911
-\f[R]
-.fi
-.PP
-The name \f[C]test_key\f[R] 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[R] option.
-.SS CREATING A TEST GEM
-.PP
-You\[cq]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[R]
-.fi
-.PP
-You\[cq]ll need to add a summary and description to the new gem\[cq]s
-gemspec file in order to successfully build it.
-Once you\[cq]ve built the gem, you will be ready to push the new gem.
-.IP
-.nf
-\f[C]
-$ cd private\-example
-$ rake build
-\f[R]
-.fi
-.PP
-You will now have a gem at
-\f[C]private\-example/pkg/private\-example\-0.1.0.gem\f[R].
-.SS PUSHING
-.PP
-If your Gemstash server isn\[cq]t running, go ahead and start it:
-.IP
-.nf
-\f[C]
-$ gemstash start
-\f[R]
-.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[R]
-.fi
-.PP
-The \f[C]/private\f[R] portion of the \f[C]\-\-host\f[R] option tells
-Gemstash you are interacting with the private gems.
-Gemstash will not let you push, or yank from anything except
-\f[C]/private\f[R].
-.SS BUNDLING
-.PP
-Once your gem is pushed to your Gemstash server, you are ready to bundle
-it.
-Create a \f[C]Gemfile\f[R] 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 \[dq]http://localhost:9292\[dq]
-gem \[dq]rubywarrior\[dq]
-
-source \[dq]http://localhost:9292/private\[dq] do
-  gem \[dq]private\-example\[dq]
-end
-\f[R]
-.fi
-.PP
-Notice that the Gemstash server points to \f[C]/private\f[R] again when
-installing your private gem.
-Go ahead and bundle to install your new private gem:
-.IP
-.nf
-\f[C]
-$ bundle
-\f[R]
-.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[R]
-.fi
-.PP
-Like with pushing, the \f[C]/private\f[R] portion of the host option
-tells Gemstash you are interacting with private gems.
-Gemstash will only let you yank from \f[C]/private\f[R].
-Unlike pushing, Rubygems doesn\[cq]t support \f[C]\-\-host\f[R] for yank
-(yet), so you need to specify the host via the \f[C]RUBYGEMS_HOST\f[R]
-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[R] command.
-.PP
-When protected fetching is enabled API keys with the permissions
-\f[C]all\f[R] or \f[C]fetch\f[R] 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[R]
-.fi
-.PP
-Add credentials in Gemfile:
-.IP
-.nf
-\f[C]
-source \[dq]https://api_key\[at]my\-gemstash.dev\[dq]
-\f[R]
-.fi
-.PP
-However, it\[cq]s not a good practice to commit credentials to source
-control.
-A recommended solution is to use Bundler\[cq]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[R]
-.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[R] 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,233 +0,0 @@
-.\" Automatically generated by Pandoc 2.5
-.\"
-.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\[cq]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\[cq]t bundle
-the same gems frequently?
-Well, maybe you don\[cq]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[R]
-.fi
-.PP
-After it is installed, starting Gemstash requires no additional steps.
-Simply start the Gemstash server with the \f[C]gemstash\f[R] command:
-.IP
-.nf
-\f[C]
-$ gemstash start
-\f[R]
-.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[R]
-.fi
-.PP
-Now you can create a Gemfile and install gems through Gemstash:
-.IP
-.nf
-\f[C]
-# ./Gemfile
-source \[dq]https://rubygems.org\[dq]
-gem \[dq]rubywarrior\[dq]
-\f[R]
-.fi
-.PP
-The gems you include should be gems you don\[cq]t yet have installed,
-otherwise Gemstash will have nothing to stash.
-Now bundle:
-.IP
-.nf
-\f[C]
-$ bundle install \-\-path .bundle
-\f[R]
-.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[R]
-.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[R]
-.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[R]
-.fi
-.SS STOPPING THE SERVER
-.PP
-Once you\[cq]ve finish using your Gemstash server, you can stop it just
-as easily as you started it:
-.IP
-.nf
-\f[C]
-$ gemstash stop
-\f[R]
-.fi
-.PP
-You\[cq]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[R]
-.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]\[ti]/.gemstash\f[R].
-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]\[ti]/.gemstash\f[R], however you
-won\[cq]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[R] 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/rubygems/gemstash/blob/master/CHANGELOG.md).
-.SS DEVELOPMENT
-.PP
-After checking out the repo, run \f[C]bin/setup\f[R] to install
-dependencies.
-Then, run \f[C]rake\f[R] to run RuboCop and the tests.
-While developing, you can run \f[C]bin/gemstash\f[R] to run Gemstash.
-You can also run \f[C]bin/console\f[R] 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/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/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).

data/lib/gemstash/man/gemstash-setup.1

@@ -1,43 +0,0 @@
-.\" Automatically generated by Pandoc 2.5
-.\"
-.TH "gemstash\-setup" "1" "October 9, 2015" "" ""
-.hy
-.SH NAME
-.PP
-gemstash\-setup \- Customize your Gemstash configuration interactively
-.SH SYNOPSIS
-.PP
-\f[C]gemstash setup [\-\-redo] [\-\-debug] [\-\-config\-file FILE]\f[R]
-.SH DESCRIPTION
-.PP
-Customize your Gemstash configuration interactively.
-This will save your config file, but only if a few checks pass after
-you\[cq]ve provided your answers.
-.SS USAGE
-.IP
-.nf
-\f[C]
-gemstash setup
-gemstash setup \-\-redo
-gemstash setup \-\-config\-file <file>
-\f[R]
-.fi
-.SH OPTIONS
-.IP \[bu] 2
-\f[C]\-\-redo\f[R]: Redo the configuration.
-This does nothing the first time \f[C]gemstash setup\f[R] is run.
-If you want to change your configuration using \f[C]gemstash setup\f[R]
-after you\[cq]ve run it before, you must provide this option, otherwise
-Gemstash will simply indicate your setup is complete.
-.IP \[bu] 2
-\f[C]\-\-debug\f[R]: Output additional information if one of the checks
-at the end of setup fails.
-This will do nothing if all checks pass.
-.IP \[bu] 2
-\f[C]\-\-config\-file FILE\f[R]: Specify the config file to write to.
-Without this option, your configuration will be written to
-\f[C]\[ti]/.gemstash/config.yml\f[R].
-If you write to a custom location, you will need to pass the
-\f[C]\-\-config\-file\f[R] option to all Gemstash commands.
-If you plan to use ERB in your config file (gemstash help customize.7),
-you might want to use \f[C]\[ti]/.gemstash/config.yml.erb\f[R].

data/lib/gemstash/man/gemstash-start.1

@@ -1,26 +0,0 @@
-.\" Automatically generated by Pandoc 2.5
-.\"
-.TH "gemstash\-start" "1" "October 9, 2015" "" ""
-.hy
-.SH NAME
-.PP
-gemstash\-start \- Starts the Gemstash server
-.SH SYNOPSIS
-.PP
-\f[C]gemstash start [\-\-no\-daemonize] [\-\-config\-file FILE]\f[R]
-.SH DESCRIPTION
-.PP
-Starts the Gemstash server.
-.SH OPTIONS
-.IP \[bu] 2
-\f[C]\-\-config\-file FILE\f[R]: Specify the config file to use.
-If you aren\[cq]t using the default config file at
-\f[C]\[ti]/.gemstash/config.yml\f[R] or
-\f[C]\[ti]/.gemstash/config.yml.erb\f[R] (gemstash help customize.7),
-then you must specify the config file via this option.
-.IP \[bu] 2
-\f[C]\-\-no\-daemonize\f[R]: The Gemstash server daemonizes itself by
-default.
-Provide this option to instead run the server until \f[C]Ctrl\-C\f[R] is
-typed.
-When not daemonized, the log will be output to standard out.

data/lib/gemstash/man/gemstash-status.1

@@ -1,20 +0,0 @@
-.\" Automatically generated by Pandoc 2.5
-.\"
-.TH "gemstash\-status" "1" "October 28, 2015" "" ""
-.hy
-.SH NAME
-.PP
-gemstash\-status \- Checks status of the Gemstash server
-.SH SYNOPSIS
-.PP
-\f[C]gemstash status [\-\-config\-file FILE]\f[R]
-.SH DESCRIPTION
-.PP
-Checks status of the Gemstash server.
-.SH OPTIONS
-.IP \[bu] 2
-\f[C]\-\-config\-file FILE\f[R]: Specify the config file to use.
-If you aren\[cq]t using the default config file at
-\f[C]\[ti]/.gemstash/config.yml\f[R] or
-\f[C]\[ti]/.gemstash/config.yml.erb\f[R] (gemstash help customize.7),
-then you must specify the config file via this option.

data/lib/gemstash/man/gemstash-stop.1

@@ -1,20 +0,0 @@
-.\" Automatically generated by Pandoc 2.5
-.\"
-.TH "gemstash\-stop" "1" "October 9, 2015" "" ""
-.hy
-.SH NAME
-.PP
-gemstash\-stop \- Stops the Gemstash server
-.SH SYNOPSIS
-.PP
-\f[C]gemstash stop [\-\-config\-file FILE]\f[R]
-.SH DESCRIPTION
-.PP
-Stops the Gemstash server.
-.SH OPTIONS
-.IP \[bu] 2
-\f[C]\-\-config\-file FILE\f[R]: Specify the config file to use.
-If you aren\[cq]t using the default config file at
-\f[C]\[ti]/.gemstash/config.yml\f[R] or
-\f[C]\[ti]/.gemstash/config.yml.erb\f[R] (gemstash help customize.7),
-then you must specify the config file via this option.

data/lib/gemstash/man/gemstash-version.1

@@ -1,22 +0,0 @@
-.\" Automatically generated by Pandoc 2.5
-.\"
-.TH "gemstash\-version" "1" "December 14, 2015" "" ""
-.hy
-.SH NAME
-.PP
-gemstash\-version \- Show what version of Gemstash you are using
-.SH SYNOPSIS
-.PP
-\f[C]gemstash version\f[R]
-.SH DESCRIPTION
-.PP
-Show what version of Gemstash you are using.
-.SS USAGE
-.IP
-.nf
-\f[C]
-gemstash version
-gemstash \-\-version
-gemstash \-v
-\f[R]
-.fi