gemstash 1.1.0 → 2.0.0

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

@@ -1,280 +0,0 @@
-.\" Automatically generated by Pandoc 1.19.2.1
-.\"
-.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[] and answer the questions it provides (a
-blank answer will use the default value):
-.RS
-$ gemstash setup
-.PD 0
-.P
-.PD
-Where should files go?
-[~/.gemstash]
-.PD 0
-.P
-.PD
-Cache with what?
-[MEMORY, memcached] \f[B]memcached\f[]
-.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[]
-.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\[aq]ve answered the questions, some checks will be made to
-ensure the configuration will work.
-For example, the database didn\[aq]t exist in the previous example, so
-the command failed and the configuration wasn\[aq]t saved.
-If the command passes, you may provide the \f[C]\-\-redo\f[] option to
-force configuration to be redone:
-.RS
-$ gemstash setup \-\-redo
-.PD 0
-.P
-.PD
-Where should files go?
-[~/.gemstash]
-.PD 0
-.P
-.PD
-Cache with what?
-[MEMORY, memcached] \f[B]memcached\f[]
-.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]~/.gemstash/config.yml\f[].
-.SS FILES
-.PP
-Storage in Gemstash defaults to \f[C]~/.gemstash\f[] unless otherwise
-specified.
-You can change this in your config file via the \f[C]:base_path\f[] key:
-.IP
-.nf
-\f[C]
-#\ ~/.gemstash/config.yml
-\-\-\-
-:base_path:\ "/var/gemstash"
-\f[]
-.fi
-.PP
-When customizing the \f[C]base_path\f[], the directory must exist,
-otherwise Gemstash will fail to run.
-Thus, if you want to use \f[C]/var/gemstash\f[] like in the previous
-example, make sure to \f[C]mkdir\ /var/gemstash\f[] and grant access to
-the directory for the user you run Gemstash with.
-.SS DATABASE
-.PP
-The \f[C]:db_adapter\f[] configuration key specifies what database you
-will be using.
-The default \f[C]:db_adapter\f[] is
-\f[C]sqlite3\f[] (https://www.sqlite.org/), which will use a database
-file located within your \f[C]:base_path\f[].
-The database file will always be named \f[C]gemstash.db\f[].
-.PP
-You may also use \f[C]postgres\f[] (http://www.postgresql.org/),
-\f[C]mysql\f[] (http://www.mysql.com/), or
-\f[C]mysql2\f[] (http://sequel.jeremyevans.net/rdoc/files/doc/opening_databases_rdoc.html#label-mysql2)
-for your \f[C]:db_adapter\f[].
-When using any of these options, you need to specify the
-\f[C]:db_url\f[] to point to an existing database.
-Here is an example configuration to use the \f[C]postgres\f[] adapter:
-.IP
-.nf
-\f[C]
-#\ ~/.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[]
-.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[] (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.
-The memory cache can optionally be swapped out with a
-Memcached (http://memcached.org/) server (or cluster of servers).
-To use Memcached, you must update the \f[C]:cache_type\f[] configuration
-key to be \f[C]memcached\f[], and provide the servers via the
-\f[C]:memcached_servers\f[] configuration key:
-.IP
-.nf
-\f[C]
-#\ ~/.gemstash/config.yml
-\-\-\-
-:cache_type:\ memcached
-:memcached_servers:\ memcached1.local:11211,memcached2.local:11211
-\f[]
-.fi
-.PP
-Note that the \f[C]:memcached_servers\f[] requires a comma separated
-list of servers.
-All caching lasts for 30 minutes.
-.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/bundler/gemstash/blob/master/lib/gemstash/puma.rb)
-and the rackup
-file (https://github.com/bundler/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[] configuration key:
-.IP
-.nf
-\f[C]
-#\ ~/.gemstash/config.yml
-\-\-\-
-:bind:\ tcp://0.0.0.0:4242
-\f[]
-.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[] configuration key.
-The default is \f[C]16\f[].
-.SS PROTECTED FETCH
-.PP
-Gemstash by default allows unauthenticated access for private gems.
-Authenticated access is available via the \f[C]:protected_fetch\f[]
-configuration key.
-.IP
-.nf
-\f[C]
-#\ ~/.gemstash/config.yml
-\-\-\-
-:protected_fetch:\ true
-\f[]
-.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[] configuration key to change it.
-.IP
-.nf
-\f[C]
-\-\-\-
-:fetch_timeout:\ 20
-\f[]
-.fi
-.SS CONFIG FILE LOCATION
-.PP
-By default, configuration for Gemstash will be at
-\f[C]~/.gemstash/config.yml\f[].
-This can be changed by providing the \f[C]\-\-config\-file\f[] 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[]
-.fi
-.PP
-When providing \f[C]\-\-config\-file\f[] to \f[C]gemstash\ setup\f[],
-the provided file will be output to with the provided configuration.
-\f[B]This will overwrite\f[] any existing configuration.
-If the file doesn\[aq]t exist when providing \f[C]\-\-config\-file\f[]
-to \f[C]gemstash\ start\f[], \f[C]gemstash\ stop\f[],
-\f[C]gemstash\ status\f[], and \f[C]gemstash\ authorize\f[], the default
-configuration will be used.
-.SS ERB PARSED CONFIG
-.PP
-You may also create a \f[C]~/.gemstash/config.yml.erb\f[] file.
-If present, this will be used instead of
-\f[C]~/.gemstash/config.yml\f[].
-For example, with this you can use environment variables in the config:
-.IP
-.nf
-\f[C]
-#\ ~/.gemstash/config.yml.erb
-\-\-\-
-:db_adapter:\ postgres
-:db_url:\ <%=\ ENV["DATABASE_URL"]\ %>
-\f[]
-.fi

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

@@ -1,34 +0,0 @@
-.\" Automatically generated by Pandoc 1.19.2.1
-.\"
-.TH "gemstash\-debugging" "7" "October 28, 2015" "" ""
-.hy
-.SH DEBUGGING GEMSTASH
-.PP
-If you are finding Gemstash isn\[aq]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[] within your base directory.
-By default, this will be at \f[C]~/.gemstash/server.log\f[].
-.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[]
-.fi
-.PP
-You can also check the status (gemstash help status.1) of the server:
-.IP
-.nf
-\f[C]
-$\ gemstash\ status
-\f[]
-.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\[aq]t hesitate to open a bug
-report (https://github.com/bundler/gemstash#contributing)!

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

@@ -1,72 +0,0 @@
-.\" Automatically generated by Pandoc 1.19.2.1
-.\"
-.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[] pointing to Gemstash:
-.IP
-.nf
-\f[C]
-#\ ./Gemfile
-source\ "https://rubygems.org"
-gem\ "gemstash"
-\f[]
-.fi
-.PP
-Then \f[C]bundle\f[] to create your \f[C]Gemfile.lock\f[].
-When you are ready to upgrade, simply \f[C]bundle\ update\f[].
-You may need to run \f[C]gemstash\f[] via \f[C]bundle\ exec\f[].
-Alternatively, you can \f[C]gem\ uninstall\ gemstash\f[] and
-\f[C]gem\ install\ gemstash\f[] 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[]
-.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[] 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]
-{
-\ \ "status":\ {
-\ \ \ \ "heartbeat":\ "OK",
-\ \ \ \ "storage_read":\ "OK",
-\ \ \ \ "storage_write":\ "OK",
-\ \ \ \ "db_read":\ "OK",
-\ \ \ \ "db_write":\ "OK"
-\ \ }
-}
-\f[]
-.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\[aq]t interact
-with storage or the database, you can use \f[C]/health/heartbeat\f[]
-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 1.19.2.1
-.\"
-.TH "gemstash\-mirror" "7" "October 25, 2015" "" ""
-.hy
-.SH USING GEMSTASH AS A MIRROR
-.PP
-If you don\[aq]t have control over your \f[C]Gemfile\f[], or you
-don\[aq]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[], 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("https://my.gem\-source.local")\[aq])
-\f[]
-.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[C]1.11.0\f[].\f[]
-.PP
-If you are using Bundler version \f[C]1.11.0\f[] 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[]
-.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 1.19.2.1
-.\"
-.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\[aq]t provide an explicit source (as with the Quickstart
-Guide (gemstash help readme.7)), 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]~/.gemstash/config.yml\f[]:
-.IP
-.nf
-\f[C]
-#\ ~/.gemstash/config.yml
-\-\-\-
-:rubygems_url:\ https://my.gem\-source.local
-\f[]
-.fi
-.PP
-Make sure to restart your Gemstash server after changing the config:
-.IP
-.nf
-\f[C]
-$\ gemstash\ stop
-$\ gemstash\ start
-\f[]
-.fi
-.PP
-Once restarted, bundling against \f[C]http://localhost:9292\f[] will
-fetch gems from \f[C]https://my.gem\-source.local\f[].
-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\[aq]t leak between each other.
-.SS BUNDLING WITH MULTIPLE SOURCES
-.PP
-Changing the default source won\[aq]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\[aq]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[]:
-.IP
-.nf
-\f[C]
-#\ ./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
-\f[]
-.fi
-.PP
-Notice the \f[C]CGI.escape\f[] 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[] 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[] like so:
-.IP
-.nf
-\f[C]
-#\ ./Gemfile
-require\ "cgi"
-source\ "http://localhost:9292/redirect/#{CGI.escape("https://rubygems.org")}"
-gem\ "rubywarrior"
-\f[]
-.fi
-.PP
-Notice the \f[C]/redirect\f[] 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.