gemstash 1.0.0.pre.1

data/docs/mirror.md

@@ -0,0 +1,30 @@
+# Using Gemstash as a Mirror
+
+If you don't have control over your `Gemfile`, or you don't want to force
+everyone on your team to go through the Gemstash server, you can use Bundler
+mirroring to bundle against your Gemstash server.
+
+For each source in your `Gemfile`, add a mirror pointing to your Gemstash
+server:
+```
+$ bundle config mirror.http://rubygems.org http://localhost:9292
+$ bundle config mirror.https://my.gem-source.local http://localhost:9292/upstream/$(ruby -rcgi -e 'puts CGI.escape("https://my.gem-source.local")')
+```
+
+From now on, bundler will fetch gems from those sources via your Gemstash
+server.
+
+# Simpler Gemstash Mirrors
+
+**WARNING: This feature is not yet available.**
+
+**This feature requires Bundler to be at least version `1.11.0`.**
+
+If you are using Bundler version `1.11.0` or greater, the mirroring becomes a
+bit easier:
+```
+$ bundle config mirror.http://rubygems.org http://localhost:9292
+$ bundle config mirror.https://my.gem-source.local http://localhost:9292
+```
+
+Bundler will then send headers to Gemstash to indicate the correct upstream.

data/docs/multiple_sources.md

@@ -0,0 +1,68 @@
+# Multiple Gem Sources
+
+Gemstash will stash from any amount of gem sources. By the end of this guide,
+you will be able to bundle using multiple gem sources, all stashed within your
+Gemstash server.
+
+## Default Source
+
+When you don't provide an explicit source (as with the [Quickstart
+Guide](../README.md#quickstart-guide)), your gems will be fetched from
+https://www.rubygems.org. This default source is not set in stone. To change it,
+you need only edit the Gemstash configuration found at `~/.gemstash/config.yml`:
+```yaml
+# ~/.gemstash/config.yml
+---
+:rubygems_url: https://my.gem-source.local
+```
+
+Make sure to restart your Gemstash server after changing the config:
+```
+$ gemstash stop
+$ gemstash start
+```
+
+Once restarted, bundling against `http://localhost:9292` will fetch gems from
+`https://my.gem-source.local`. If you had bundled before making these changes,
+fear not; bundling with a different default gem source will store gems in a
+separate location, ensuring different sources won't leak between each other.
+
+## Bundling with Multiple Sources
+
+Changing the default source won't help you if you need to bundle against
+https://www.rubygems.org along with additional sources. If you need to bundle
+with multiple gem sources, Gemstash doesn't need to be specially configured.
+Your Gemstash server will honor any gem source specified via a specialized URL.
+Consider the following `Gemfile`:
+```ruby
+# ./Gemfile
+require "cgi"
+source "http://localhost:9292"
+gem "rubywarrior"
+
+source "http://localhost:9292/upstream/#{CGI.escape("https://my.gem-source.local")}" do
+  gem "my-gem"
+end
+```
+
+Notice the `CGI.escape` call in the second source. This is important, as it
+properly URL escapes the source URL so Gemstash knows what gem source you want.
+The `/upstream` prefix tells Gemstash to use a gem source other than the default
+source. You can now bundle with the additional source.
+
+## Redirecting
+
+Gemstash supports an alternate mode of specifying your gem sources. If you want
+Gemstash to redirect Bundler to your given gem sources, then you can specify
+your `Gemfile` like so:
+```ruby
+# ./Gemfile
+require "cgi"
+source "http://localhost:9292/redirect/#{CGI.escape("https://www.rubygems.org")}"
+gem "rubywarrior"
+```
+
+Notice the `/redirect` prefix. This prefix tells Gemstash to redirect API calls
+to the provided URL. Redirected calls like this will not be cached by Gemstash,
+and gem files will not be stashed, even if they were previously cached or
+stashed from the same gem source.

data/docs/private_gems.md

@@ -0,0 +1,140 @@
+# Private Gems
+
+Stashing private gems in your Gemstash server requires a bit of additional
+setup. If you haven'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.
+
+## Authorizing
+
+**IMPORTANT NOTE:** 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.
+
+In order to push a gem to your Gemstash server, you need to first create an API
+key. Utilize the `gemstash` command to create the API key:
+```
+$ gemstash authorize
+Your new key is: e374e237fdf5fa5718d2a21bd63dc911
+```
+
+This new key can `push`, `yank`, and `unyank` gems from your Gemstash server.
+Run `gemstash authorize` 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 `--key` option:
+```
+$ gemstash authorize push yank --key e374e237fdf5fa5718d2a21bd63dc911
+```
+
+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:
+```
+$ gemstash authorize --key e374e237fdf5fa5718d2a21bd63dc911
+```
+
+With the key generated, you'll need to tell Rubygems about your new key. If
+you've pushed a gem to https://www.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:
+```
+$ mkdir -p ~/.gem
+$ touch ~/.gem/credentials
+$ chmod 0600 ~/.gem/credentials
+```
+
+Add your new key to credentials such that it looks something like this (but make
+sure not to remove any existing keys):
+```yaml
+# ~/.gem/credentials
+---
+:test_key: e374e237fdf5fa5718d2a21bd63dc911
+```
+
+The name `test_key` can be anything you want, but you will need to remember it
+and use it again later in this guide for the `--key` option.
+
+## Creating a Test Gem
+
+You'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:
+```
+$ bundle gem private-example
+```
+
+You'll need to add a summary and description to the new gem's gemspec file in
+order to successfully build it. Once you've built the gem, you will be ready to
+push the new gem.
+```
+$ cd private-example
+$ rake build
+```
+
+You will now have a gem at `private-example/pkg/private-example-0.1.0.gem`.
+
+## Pushing
+
+If your Gemstash server isn't running, go ahead and start it:
+```
+$ gemstash start
+```
+
+Push your test gem using Rubygems:
+```
+$ gem push --key test_key --host http://localhost:9292/private pkg/private-example-0.1.0.gem
+```
+
+The `/private` portion of the `--host` option tells Gemstash you are interacting
+with the private gems. Gemstash will not let you push, yank, or unyank from
+anything except `/private`.
+
+## Bundling
+
+Once your gem is pushed to your Gemstash server, you are ready to bundle it.
+Create a `Gemfile` 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:
+```ruby
+# ./Gemfile
+source "http://localhost:9292"
+gem "rubywarrior"
+
+source "http://localhost:9292/private" do
+  gem "private-example"
+end
+```
+
+Notice that the Gemstash server points to `/private` again when installing your
+private gem. Go ahead and bundle to install your new private gem:
+```
+$ bundle
+```
+
+## Yanking
+
+If you push a private gem by accident, you can yank the gem with Rubygems:
+```
+$ RUBYGEMS_HOST=http://localhost:9292/private gem yank --key test_key private-example --version 0.1.0
+```
+
+Like with pushing, the `/private` portion of the host option tells Gemstash you
+are interacting with private gems. Gemstash will only let you yank from
+`/private`. Unlike pushing, Rubygems doesn't support `--host` for yank and
+unyank (yet), so you need to specify the host via the `RUBYGEMS_HOST`
+environment variable.
+
+## Unyanking
+
+If you yank a private gem by accident, you can unyank the gem with Rubygems:
+```
+$ RUBYGEMS_HOST=http://localhost:9292/private gem yank --key test_key private-example --version 0.1.0 --undo
+```
+
+Like with pushing and yanking, the `/private` portion of the host option tells
+Gemstash you are interacting with private gems. Gemstash will only let you
+unyank from `/private`. Unlike pushing, Rubygems doesn't support `--host` for
+unyank and yank (yet), so you need to specify the host via the `RUBYGEMS_HOST`
+environment variable.

data/docs/reference.md

@@ -0,0 +1,308 @@
+
+Table of Contents
+=================
+
+  * [Reference](#reference)
+    * [Configuration](#configuration)
+      * [:base_path](#base_path)
+      * [:cache_type](#cache_type)
+      * [:memcached_servers](#memcached_servers)
+      * [:db_adapter](#db_adapter)
+      * [:db_url](#db_url)
+      * [:rubygems_url](#rubygems_url)
+      * [:bind](#bind)
+    * [Authorize](#authorize)
+      * [Usage](#usage)
+      * [Arguments](#arguments)
+      * [Options](#options)
+        * [--config-file](#--config-file)
+        * [--key](#--key)
+        * [--remove](#--remove)
+    * [Start](#start)
+      * [Usage](#usage-1)
+      * [Options](#options-1)
+        * [--config-file](#--config-file-1)
+        * [--no-daemonize](#--no-daemonize)
+    * [Stop](#stop)
+      * [Usage](#usage-2)
+      * [Options](#options-2)
+        * [--config-file](#--config-file-2)
+    * [Status](#status)
+      * [Usage](#usage-3)
+      * [Options](#options-3)
+        * [--config-file](#--config-file-3)
+    * [Setup](#setup)
+      * [Usage](#usage-4)
+      * [Options](#options-4)
+        * [--redo](#--redo)
+        * [--debug](#--debug)
+        * [--config-file](#--config-file-4)
+
+
+
+---
+
+# Reference
+
+## Configuration
+
+**Example:**
+```yaml
+# ~/.gemstash/config.yml
+---
+:base_path: "/var/gemstash"
+:cache_type: memcached
+:memcached_servers: localhost:11211
+:db_adapter: postgres
+:db_url: postgres:///gemstash
+:rubygems_url: https://my.gem-source.local
+:bind: tcp://0.0.0.0:4242
+```
+
+### :base_path
+
+**Default value:** `~/.gemstash`
+
+**Valid values:** Any valid path
+
+**Description**<br />
+Specifies where to store local files like the server log, cached gem files, and
+the database (when using SQLite). If the default is being used, the directory
+will be created if it does not exist. Any other directory needs to be created
+ahead of time and be writable to the Gemstash server process. Specifying the
+`:base_path` via [`gemstash setup`](reference.md#setup) will create the
+directory for you.
+
+### :cache_type
+
+**Default value:** `memory`
+
+**Valid values:** `memory`, `memcached`
+
+**Description**<br />
+Specifies how to cache values other than gem files (such as gem dependencies).
+`memory` will use an in memory cache while `memcached` will point to 1 or more
+Memcached servers. Use the `:memcached_servers` configuration key for specifying
+where the Memcached server(s) are.
+
+### :memcached_servers
+
+**Default value:** `localhost:11211`
+
+**Valid values:** A comma delimited list of Memcached servers
+
+**Description**<br />
+Specifies the Memcached servers to connect to when using `memcached` for the
+`:cache_type`. Only used when `memcached` is used for `:cache_type`.
+
+### :db_adapter
+
+**Default value:** `sqlite3`
+
+**Valid values:** `sqlite3`, `postgres`
+
+**Description**<br />
+Specifies what database adapter to use. When `sqlite3` is used, the database
+will be located at `gemstash.db` within the directory specified by `:base_path`.
+The database will automatically be created when using `sqlite3`. When `postgres`
+is used, the database to connect to must be specified in the `:db_url`
+configuration key. The database must already be created when using `postgres`.
+
+### :db_url
+
+**Default value:** None
+
+**Valid values:** A valid database URL for the [Sequel
+gem](http://sequel.jeremyevans.net/)
+
+**Description**<br />
+Specifies the database to connect to when using `postgres` for the
+`:db_adapter`. Only used when `postgres` is used for `:db_adapter`.
+
+### :rubygems_url
+
+**Default value:** `https://www.rubygems.org`
+
+**Valid values:** A valid gem source URL
+
+**Description**<br />
+Specifies the default gem source URL. When any API endpoint is called without a
+`/private` or `/upstream/<url>` prefix, this URL will be used to fetch the
+result. This value can be safely changed even if there are already gems stashed
+for the previous value.
+
+### :bind
+
+**Default value:** `tcp://0.0.0.0:9292`
+
+**Valid values:** Any valid binding that [is supported by
+Puma](https://github.com/puma/puma#binding-tcp--sockets)
+
+**Description**<br />
+Specifies the binding used to start the Gemstash server. Keep in mind the user
+starting Gemstash needs to have access to bind in this manner. For example, if
+you use a port below 1024, you will need to run Gemstash as the root user.
+
+## Authorize
+
+Adds or removes authorization to interact with privately stored gems.
+
+### Usage
+
+```
+gemstash authorize
+gemstash authorize push yank
+gemstash authorize yank unyank --key <secure-key>
+gemstash authorize --remove --key <secure-key>
+```
+
+### Arguments
+
+Any arguments will be used as specific permissions. Valid permissions include
+`push`, `yank`, and `unyank`. If no permissions are provided, then all
+permissions will be granted (including any that may be added in future versions
+of Gemstash).
+
+### Options
+
+#### --config-file
+
+**Usage:** `--config-file <file>`
+
+**Description**<br />
+Specify the config file to use. If you aren't using the default config file at
+`~/.gemstash/config.yml`, then you must specify the config file via this option.
+
+#### --key
+
+**Usage:** `--key <secure-key>`
+
+**Description**<br />
+Specify the API key to affect. This should be the actual key value, not a name.
+This option is required when using `--remove` but is optional otherwise. If
+adding an authorization, using this will either create or update the permissions
+for the specified API key. If missing, a new API key will always be generated.
+
+#### --remove
+
+**Usage:** `--remove`
+
+**Description**<br />
+Remove an authorization rather than add or update one. When removing, permission
+values are not allowed. The `--key <secure-key>` option is required.
+
+## Start
+
+Starts the Gemstash server.
+
+### Usage
+
+```
+gemstash start
+gemstash start --no-daemonize
+```
+
+### Options
+
+#### --config-file
+
+**Usage:** `--config-file <file>`
+
+**Description**<br />
+Specify the config file to use. If you aren't using the default config file at
+`~/.gemstash/config.yml`, then you must specify the config file via this option.
+
+#### --no-daemonize
+
+**Usage:** `--no-daemonize`
+
+**Description**<br />
+The Gemstash server daemonizes itself by default. Provide this option to instead
+run the server until `Ctrl-C` is typed. When not daemonized, the log will be
+output to standard out.
+
+## Stop
+
+Stops the Gemstash server.
+
+### Usage
+
+```
+gemstash stop
+```
+
+### Options
+
+#### --config-file
+
+**Usage:** `--config-file <file>`
+
+**Description**<br />
+Specify the config file to use. If you aren't using the default config file at
+`~/.gemstash/config.yml`, then you must specify the config file via this option.
+
+## Status
+
+Checks status of the Gemstash server.
+
+### Usage
+
+```
+gemstash status
+```
+
+### Options
+
+#### --config-file
+
+**Usage:** `--config-file <file>`
+
+**Description**<br />
+Specify the config file to use. If you aren't using the default config file at
+`~/.gemstash/config.yml`, then you must specify the config file via this option.
+
+## Setup
+
+Customize your Gemstash configuration interactively. This will save your config
+file, but only if a few checks pass after you've provided your answers.
+
+### Usage
+
+```
+gemstash setup
+gemstash setup --redo
+gemstash setup --config-file <file>
+```
+
+### Options
+
+#### --redo
+
+**Usage:** `--redo`
+
+**Description**<br />
+Redo the configuration. This does nothing the first time `gemstash setup` is
+run. If you want to change your configuration using `gemstash setup` after
+you've run it before, you must provide this option, otherwise Gemstash will
+simply indicate your setup is complete.
+
+#### --debug
+
+**Usage:** `--debug`
+
+**Description**<br />
+Output additional information if one of the checks at the end of setup fails.
+This will do nothing if all checks pass.
+
+#### --config-file
+
+**Usage:** `--config-file <file>`
+
+**Description**<br />
+Specify the config file to write to. Without this option, your configuration
+will be written to `~/.gemstash/config.yml`. If you write to a custom location,
+you will need to pass the `--config-file` option to all Gemstash commands.
+
+---
+
+Table of contents thanks to [gh-md-toc](https://github.com/ekalinin/github-markdown-toc).