gemstash 2.1.0 → 2.2.0

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

@@ -1,301 +0,0 @@
-.\" Automatically generated by Pandoc 2.5
-.\"
-.TH "gemstash\-customize" "7" "October 28, 2015" "" ""
-.hy
-.SH CUSTOMIZING THE SERVER
-.PP
-Although Gemstash is designed for as minimal setup as possible, there
-may be times you will want to change some of the default configuration.
-By the end of this guide, you will be able to customize some of the
-Gemstash behavior, including where files are stored, what database
-Gemstash uses, and how Gemstash caches certain requests.
-.SS SETUP
-.PP
-Several customizable options are available via an interactive Gemstash
-command.
-Run \f[C]gemstash setup\f[R] and answer the questions it provides (a
-blank answer will use the default value):
-.RS
-.PP
-$ gemstash setup
-.PD 0
-.P
-.PD
-Where should files go?
-[\[ti]/.gemstash]
-.PD 0
-.P
-.PD
-Cache with what?
-[MEMORY, memcached] \f[B]memcached\f[R]
-.PD 0
-.P
-.PD
-What is the comma separated Memcached servers?
-[localhost:11211]
-.PD 0
-.P
-.PD
-What database adapter?
-[SQLITE3, postgres, mysql, mysql2] \f[B]postgres\f[R]
-.PD 0
-.P
-.PD
-Where is the database?
-[postgres:///gemstash]
-.PD 0
-.P
-.PD
-Checking that the cache is available
-.PD 0
-.P
-.PD
-Checking that the database is available
-.PD 0
-.P
-.PD
-The database is not available
-.PD 0
-.P
-.PD
-.RE
-.PP
-Once you\[cq]ve answered the questions, some checks will be made to
-ensure the configuration will work.
-For example, the database didn\[cq]t exist in the previous example, so
-the command failed and the configuration wasn\[cq]t saved.
-If the command passes, you may provide the \f[C]\-\-redo\f[R] option to
-force configuration to be redone:
-.RS
-.PP
-\f[C]$ gemstash setup \-\-redo\f[R]
-.PD 0
-.P
-.PD
-Where should files go?
-[\[ti]/.gemstash]
-.PD 0
-.P
-.PD
-Cache with what?
-[MEMORY, memcached] \f[B]memcached\f[R]
-.PD 0
-.P
-.PD
-What is the comma separated Memcached servers?
-[localhost:11211]
-.PD 0
-.P
-.PD
-What database adapter?
-[SQLITE3, postgres, mysql, mysql2]
-.PD 0
-.P
-.PD
-Checking that the cache is available
-.PD 0
-.P
-.PD
-Checking that the database is available
-.PD 0
-.P
-.PD
-You are all setup!
-.PD 0
-.P
-.PD
-.RE
-.PP
-Once all checks have passed, Gemstash will store your answers in the
-configuration file located at \f[C]\[ti]/.gemstash/config.yml\f[R].
-.SS FILES
-.PP
-Storage in Gemstash defaults to \f[C]\[ti]/.gemstash\f[R] unless
-otherwise specified.
-You can change this in your config file via the \f[C]:base_path\f[R]
-key:
-.IP
-.nf
-\f[C]
-# \[ti]/.gemstash/config.yml
-\-\-\-
-:base_path: \[dq]/var/gemstash\[dq]
-\f[R]
-.fi
-.PP
-When customizing the \f[C]base_path\f[R], the directory must exist,
-otherwise Gemstash will fail to run.
-Thus, if you want to use \f[C]/var/gemstash\f[R] like in the previous
-example, make sure to \f[C]mkdir /var/gemstash\f[R] and grant access to
-the directory for the user you run Gemstash with.
-.SS DATABASE
-.PP
-The \f[C]:db_adapter\f[R] configuration key specifies what database you
-will be using.
-The default \f[C]:db_adapter\f[R] is
-\f[C]sqlite3\f[R] (https://www.sqlite.org/), which will use a database
-file located within your \f[C]:base_path\f[R].
-The database file will always be named \f[C]gemstash.db\f[R].
-.PP
-You may also use \f[C]postgres\f[R] (http://www.postgresql.org/),
-\f[C]mysql\f[R] (http://www.mysql.com/), or
-\f[C]mysql2\f[R] (http://sequel.jeremyevans.net/rdoc/files/doc/opening_databases_rdoc.html#label-mysql2)
-for your \f[C]:db_adapter\f[R].
-When using any of these options, you need to specify the
-\f[C]:db_url\f[R] to point to an existing database.
-Here is an example configuration to use the \f[C]postgres\f[R] adapter:
-.IP
-.nf
-\f[C]
-# \[ti]/.gemstash/config.yml
-\-\-\-
-:db_adapter: postgres
-:db_url: postgres:///gemstash
-:db_connection_options: # Sequel.connect options
-  :connect_timeout: 10
-  :read_timeout: 5
-  :timeout: 30
-\f[R]
-.fi
-.PP
-Regardless of the adapter you choose, the database will automatically
-migrate to your version of Gemstash whenever the database is needed.
-You only need to ensure the database exists and Gemstash will do the
-rest, except for \f[C]sqlite3\f[R] (for which Gemstash will also create
-the database for you).
-.SS CACHE
-.PP
-Certain things (like dependencies) are cached in memory.
-This avoids web calls to the gem source, and database calls for private
-gems.
-.IP
-.nf
-\f[C]
-# \[ti]/.gemstash/config.yml
-\-\-\-
-:cache_type: memory
-:cache_max_size: 2000
-\f[R]
-.fi
-.PP
-This configuration uses the default \f[C]memory\f[R] cache, and has
-increased the \f[C]cache_max_size\f[R] setting from its default of 500
-items.
-.PP
-The memory cache can optionally be swapped out with a
-Memcached (http://memcached.org/) server (or cluster of servers).
-.PP
-To use Memcached, use the \f[C]memcached\f[R] \f[C]:cache_type\f[R]
-configuration.
-.PP
-Provide the servers as a comma\-separated list to the
-\f[C]:memcached_servers\f[R] configuration key:
-.IP
-.nf
-\f[C]
-# \[ti]/.gemstash/config.yml
-\-\-\-
-:cache_type: memcached
-:memcached_servers: memcached1.local:11211,memcached2.local:11211
-:cache_expiration: 1800
-\f[R]
-.fi
-.PP
-All caching expires in \f[C]cache_expiration\f[R] number of seconds.
-Default is 1800 seconds (30 minutes).
-This option applies to all caching.
-.SS SERVER
-.PP
-Gemstash uses Puma (http://puma.io/) and Rack (http://rack.github.io/)
-as the server.
-Alternate server configurations are not currently supported, but you can
-take a look at the Puma
-configuration (https://github.com/rubygems/gemstash/blob/master/lib/gemstash/puma.rb)
-and the rackup
-file (https://github.com/rubygems/gemstash/blob/master/lib/gemstash/config.ru)
-for inspiration.
-.PP
-While the server is not customizable, the way Gemstash binds the port
-can be changed.
-To change the binding, update the \f[C]:bind\f[R] configuration key:
-.IP
-.nf
-\f[C]
-# \[ti]/.gemstash/config.yml
-\-\-\-
-:bind: tcp://0.0.0.0:4242
-\f[R]
-.fi
-.PP
-This maps directly to the Puma bind
-flag (https://github.com/puma/puma#binding-tcp--sockets), and will
-support anything valid for that flag.
-.PP
-The number of threads Puma uses is also customizable via the
-\f[C]:puma_threads\f[R] configuration key.
-The default is \f[C]16\f[R].
-.SS PROTECTED FETCH
-.PP
-Gemstash by default allows unauthenticated access for private gems.
-Authenticated access is available via the \f[C]:protected_fetch\f[R]
-configuration key.
-.IP
-.nf
-\f[C]
-# \[ti]/.gemstash/config.yml
-\-\-\-
-:protected_fetch: true
-\f[R]
-.fi
-.PP
-More details on protected_fetch are here (gemstash help private-gems.7).
-.SS FETCH TIMEOUT
-.PP
-The default fetch timeout is 20 seconds.
-Use the \f[C]:fetch_timeout\f[R] configuration key to change it.
-.IP
-.nf
-\f[C]
-\-\-\-
-:fetch_timeout: 20
-\f[R]
-.fi
-.SS CONFIG FILE LOCATION
-.PP
-By default, configuration for Gemstash will be at
-\f[C]\[ti]/.gemstash/config.yml\f[R].
-This can be changed by providing the \f[C]\-\-config\-file\f[R] option
-to the various Gemstash commands:
-.IP
-.nf
-\f[C]
-$ gemstash setup \-\-config\-file ./gemstash\-config.yml
-$ gemstash authorize \-\-config\-file ./gemstash\-config.yml
-$ gemstash start \-\-config\-file ./gemstash\-config.yml
-$ gemstash stop \-\-config\-file ./gemstash\-config.yml
-$ gemstash status \-\-config\-file ./gemstash\-config.yml
-\f[R]
-.fi
-.PP
-When providing \f[C]\-\-config\-file\f[R] to \f[C]gemstash setup\f[R],
-the provided file will be output to with the provided configuration.
-\f[B]This will overwrite\f[R] any existing configuration.
-If the file doesn\[cq]t exist when providing \f[C]\-\-config\-file\f[R]
-to \f[C]gemstash start\f[R], \f[C]gemstash stop\f[R],
-\f[C]gemstash status\f[R], and \f[C]gemstash authorize\f[R], the default
-configuration will be used.
-.SS ERB PARSED CONFIG
-.PP
-You may also create a \f[C]\[ti]/.gemstash/config.yml.erb\f[R] file.
-If present, this will be used instead of
-\f[C]\[ti]/.gemstash/config.yml\f[R].
-For example, with this you can use environment variables in the config:
-.IP
-.nf
-\f[C]
-# \[ti]/.gemstash/config.yml.erb
-\-\-\-
-:db_adapter: postgres
-:db_url: <%= ENV[\[dq]DATABASE_URL\[dq]] %>
-\f[R]
-.fi

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

@@ -1,34 +0,0 @@
-.\" Automatically generated by Pandoc 2.5
-.\"
-.TH "gemstash\-debugging" "7" "October 28, 2015" "" ""
-.hy
-.SH DEBUGGING GEMSTASH
-.PP
-If you are finding Gemstash isn\[cq]t behaving as you would expect, you
-might want to start by looking at the server log.
-You can find the log at \f[C]server.log\f[R] within your base directory.
-By default, this will be at \f[C]\[ti]/.gemstash/server.log\f[R].
-.PP
-You might find it easier to view the log directly in your terminal.
-If you run Gemstash in non\-daemonized form (gemstash help start.1), the
-log will be output directly to standard out:
-.IP
-.nf
-\f[C]
-$ gemstash start \-\-no\-daemonize
-\f[R]
-.fi
-.PP
-You can also check the status (gemstash help status.1) of the server:
-.IP
-.nf
-\f[C]
-$ gemstash status
-\f[R]
-.fi
-.PP
-The server status is checked by passing through to
-pumactl (https://github.com/puma/puma#pumactl).
-.PP
-If you find a bug, please don\[cq]t hesitate to open a bug
-report (https://github.com/rubygems/gemstash#contributing)!

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

@@ -1,72 +0,0 @@
-.\" Automatically generated by Pandoc 2.5
-.\"
-.TH "gemstash\-deploy" "7" "October 25, 2015" "" ""
-.hy
-.SH DEPLOYING GEMSTASH
-.PP
-Bundler is here for the rescue to keep Gemstash up to date! Create a
-\f[C]Gemfile\f[R] pointing to Gemstash:
-.IP
-.nf
-\f[C]
-# ./Gemfile
-source \[dq]https://rubygems.org\[dq]
-gem \[dq]gemstash\[dq]
-\f[R]
-.fi
-.PP
-Then \f[C]bundle\f[R] to create your \f[C]Gemfile.lock\f[R].
-When you are ready to upgrade, simply \f[C]bundle update\f[R].
-You may need to run \f[C]gemstash\f[R] via \f[C]bundle exec\f[R].
-Alternatively, you can \f[C]gem uninstall gemstash\f[R] and
-\f[C]gem install gemstash\f[R] when you want to upgrade.
-.PP
-Gemstash will automatically run any necessary migrations, so updating
-the gem is all that needs to be done.
-.PP
-It is probably wise to stop Gemstash before upgrading, then starting
-again once you are done:
-.IP
-.nf
-\f[C]
-$ bundle exec gemstash stop
-$ bundle update
-$ bundle exec gemstash start
-\f[R]
-.fi
-.SS MONITORING
-.PP
-Health monitoring is built in to Gemstash using the
-server_health_check\-rack (https://github.com/on-site/server_health_check-rack)
-gem.
-If you request \f[C]/health\f[R] from your Gemstash instance, you will
-get a JSON response along with an HTTP status code indicating success or
-failure.
-The JSON response will look something like this for a success case:
-.IP
-.nf
-\f[C]
-{
-  \[dq]status\[dq]: {
-    \[dq]heartbeat\[dq]: \[dq]OK\[dq],
-    \[dq]storage_read\[dq]: \[dq]OK\[dq],
-    \[dq]storage_write\[dq]: \[dq]OK\[dq],
-    \[dq]db_read\[dq]: \[dq]OK\[dq],
-    \[dq]db_write\[dq]: \[dq]OK\[dq]
-  }
-}
-\f[R]
-.fi
-.PP
-This request will test storage and database access and report on the
-result.
-Each key in the status can be requested alone to just report on that
-status.
-For example, if you would like a health check that doesn\[cq]t interact
-with storage or the database, you can use \f[C]/health/heartbeat\f[R]
-which will always respond with a success while your Gemstash server is
-running.
-.SS DOWNGRADING
-.PP
-It is not recommended to go backwards in Gemstash versions.
-Migrations may have run that could leave the database in a bad state.

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

@@ -1,40 +0,0 @@
-.\" Automatically generated by Pandoc 2.5
-.\"
-.TH "gemstash\-mirror" "7" "October 25, 2015" "" ""
-.hy
-.SH USING GEMSTASH AS A MIRROR
-.PP
-If you don\[cq]t have control over your \f[C]Gemfile\f[R], or you
-don\[cq]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.
-.PP
-For each source in your \f[C]Gemfile\f[R], add a mirror pointing to your
-Gemstash server:
-.IP
-.nf
-\f[C]
-$ bundle config mirror.http://rubygems.org http://localhost:9292
-$ bundle config mirror.https://my.gem\-source.local http://localhost:9292/upstream/$(ruby \-rcgi \-e \[aq]puts CGI.escape(\[dq]https://my.gem\-source.local\[dq])\[aq])
-\f[R]
-.fi
-.PP
-From now on, bundler will fetch gems from those sources via your
-Gemstash server.
-.SH SIMPLER GEMSTASH MIRRORS
-.PP
-\f[B]This feature requires Bundler to be at least version
-\f[CB]1.11.0\f[B].\f[R]
-.PP
-If you are using Bundler version \f[C]1.11.0\f[R] or greater, the
-mirroring becomes a bit easier:
-.IP
-.nf
-\f[C]
-$ bundle config mirror.http://rubygems.org http://localhost:9292
-$ bundle config mirror.https://my.gem\-source.local http://localhost:9292
-\f[R]
-.fi
-.PP
-Bundler will then send headers to Gemstash to indicate the correct
-upstream.

data/lib/gemstash/man/gemstash-multiple-sources.7

@@ -1,89 +0,0 @@
-.\" Automatically generated by Pandoc 2.5
-.\"
-.TH "gemstash\-multiple\-sources" "7" "October 8, 2015" "" ""
-.hy
-.SH MULTIPLE GEM SOURCES
-.PP
-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.
-.SS DEFAULT SOURCE
-.PP
-When you don\[cq]t provide an explicit source (as with the Quickstart
-Guide (../readme.md#quickstart-guide)), your gems will be fetched from
-https://rubygems.org.
-This default source is not set in stone.
-To change it, you need only edit the Gemstash configuration found at
-\f[C]\[ti]/.gemstash/config.yml\f[R]:
-.IP
-.nf
-\f[C]
-# \[ti]/.gemstash/config.yml
-\-\-\-
-:rubygems_url: https://my.gem\-source.local
-\f[R]
-.fi
-.PP
-Make sure to restart your Gemstash server after changing the config:
-.IP
-.nf
-\f[C]
-$ gemstash stop
-$ gemstash start
-\f[R]
-.fi
-.PP
-Once restarted, bundling against \f[C]http://localhost:9292\f[R] will
-fetch gems from \f[C]https://my.gem\-source.local\f[R].
-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\[cq]t leak between each other.
-.SS BUNDLING WITH MULTIPLE SOURCES
-.PP
-Changing the default source won\[cq]t help you if you need to bundle
-against https://rubygems.org along with additional sources.
-If you need to bundle with multiple gem sources, Gemstash doesn\[cq]t
-need to be specially configured.
-Your Gemstash server will honor any gem source specified via a
-specialized URL.
-Consider the following \f[C]Gemfile\f[R]:
-.IP
-.nf
-\f[C]
-# ./Gemfile
-require \[dq]cgi\[dq]
-source \[dq]http://localhost:9292\[dq]
-gem \[dq]rubywarrior\[dq]
-
-source \[dq]http://localhost:9292/upstream/#{CGI.escape(\[dq]https://my.gem\-source.local\[dq])}\[dq] do
-  gem \[dq]my\-gem\[dq]
-end
-\f[R]
-.fi
-.PP
-Notice the \f[C]CGI.escape\f[R] 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 \f[C]/upstream\f[R] prefix tells Gemstash to use a gem source other
-than the default source.
-You can now bundle with the additional source.
-.SS REDIRECTING
-.PP
-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 \f[C]Gemfile\f[R] like so:
-.IP
-.nf
-\f[C]
-# ./Gemfile
-require \[dq]cgi\[dq]
-source \[dq]http://localhost:9292/redirect/#{CGI.escape(\[dq]https://rubygems.org\[dq])}\[dq]
-gem \[dq]rubywarrior\[dq]
-\f[R]
-.fi
-.PP
-Notice the \f[C]/redirect\f[R] 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.