gemstash 1.0.2 → 1.0.3

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

@@ -0,0 +1,224 @@
+.\" Automatically generated by Pandoc 1.16.0.2
+.\"
+.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
+.PP
+$ 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] \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
+.RE
+.PP
+Once you\[aq]ve answered the questsions, 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
+.PP
+$ 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]
+.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!
+.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/) for your
+\f[C]:db_adapter\f[].
+When using PostgreSQL, 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
+\f[]
+.fi
+.PP
+Regardless of the adapter you choose, the database will automatically
+migrate to your version of Gemstash whenever the database is needed.
+Except for \f[C]sqlite3\f[], you only need to ensure the database exists
+and Gemstash will do the rest.
+.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.
+.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.

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

@@ -0,0 +1,137 @@
+gemstash-customize(7)					 gemstash-customize(7)
+
+
+
+CUSTOMIZING THE SERVER
+       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 Gem-
+       stash uses, and how Gemstash caches certain requests.
+
+   SETUP
+       Several	customizable options are available via an interactive Gemstash
+       command.  Run gemstash setup and answer the questions  it  provides  (a
+       blank answer will use the default value):
+
+	      $ gemstash setup
+	      Where should files go?  [~/.gemstash]
+	      Cache with what?	[MEMORY, memcached] memcached
+	      What   is   the  comma  separated  Memcached  servers?   [local-
+	      host:11211]
+	      What database adapter?  [SQLITE3, postgres] postgres
+	      Where is the database?  [postgres:///gemstash]
+	      Checking that the cache is available
+	      Checking that the database is available
+	      The database is not available
+
+       Once you've answered the questsions, some checks will be made to ensure
+       the configuration will work.  For example, the database didn't exist in
+       the previous example, so  the  command  failed  and  the  configuration
+       wasn't saved.  If the command passes, you may provide the --redo option
+       to force configuration to be redone:
+
+	      $ gemstash setup --redo
+	      Where should files go?  [~/.gemstash]
+	      Cache with what?	[MEMORY, memcached] memcached
+	      What  is	the  comma  separated  Memcached   servers?    [local-
+	      host:11211]
+	      What database adapter?  [SQLITE3, postgres]
+	      Checking that the cache is available
+	      Checking that the database is available
+	      You are all setup!
+
+       Once  all  checks  have passed, Gemstash will store your answers in the
+       configuration file located at ~/.gemstash/config.yml.
+
+   FILES
+       Storage in Gemstash defaults to ~/.gemstash unless otherwise specified.
+       You can change this in your config file via the :base_path key:
+
+	      # ~/.gemstash/config.yml
+	      ---
+	      :base_path: "/var/gemstash"
+
+       When  customizing  the  base_path,  the directory must exist, otherwise
+       Gemstash will fail to run.  Thus, if you want to use /var/gemstash like
+       in the previous example, make sure to mkdir /var/gemstash and grant ac-
+       cess to the directory for the user you run Gemstash with.
+
+   DATABASE
+       The :db_adapter configuration key specifies what database you  will  be
+       using.	The  default :db_adapter is sqlite3 (https://www.sqlite.org/),
+       which will use a database file located  within  your  :base_path.   The
+       database file will always be named gemstash.db.
+
+       You   may  also	use  postgres  (http://www.postgresql.org/)  for  your
+       :db_adapter.  When using PostgreSQL, you need to specify the :db_url to
+       point to an existing database.  Here is an example configuration to use
+       the postgres adapter:
+
+	      # ~/.gemstash/config.yml
+	      ---
+	      :db_adapter: postgres
+	      :db_url: postgres:///gemstash
+
+       Regardless of the adapter you choose, the database  will  automatically
+       migrate	to  your  version of Gemstash whenever the database is needed.
+       Except for sqlite3, you only need to ensure  the  database  exists  and
+       Gemstash will do the rest.
+
+   CACHE
+       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  Mem-
+       cached,	you  must  update the :cache_type configuration key to be mem-
+       cached, and provide the servers via the	:memcached_servers  configura-
+       tion key:
+
+	      # ~/.gemstash/config.yml
+	      ---
+	      :cache_type: memcached
+	      :memcached_servers: memcached1.local:11211,memcached2.local:11211
+
+       Note  that  the	:memcached_servers  requires a comma separated list of
+       servers.  All caching lasts for 30 minutes.
+
+   SERVER
+       Gemstash uses Puma (http://puma.io/) and Rack  (http://rack.github.io/)
+       as  the server.	Alternate server configurations are not currently sup-
+       ported,	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/mas-
+       ter/lib/gemstash/config.ru) for inspiration.
+
+       While  the  server is not customizable, the way Gemstash binds the port
+       can be changed.	To change the binding, update the :bind  configuration
+       key:
+
+	      # ~/.gemstash/config.yml
+	      ---
+	      :bind: tcp://0.0.0.0:4242
+
+       This	 maps	   directly	 to	the	Puma	 bind	  flag
+       (https://github.com/puma/puma#binding-tcp--sockets), and  will  support
+       anything valid for that flag.
+
+   CONFIG FILE LOCATION
+       By  default,  configuration  for  Gemstash  will be at ~/.gemstash/con-
+       fig.yml.  This can be changed by providing the --config-file option  to
+       the various Gemstash commands:
+
+	      $ 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
+
+       When  providing --config-file to gemstash setup, the provided file will
+       be output to with the provided configuration.  This will overwrite  any
+       existing  configuration.   If  the  file  doesn't  exist when providing
+       --config-file to gemstash start,  gemstash stop,  gemstash status,  and
+       gemstash authorize, the default configuration will be used.
+
+
+
+			       October 28, 2015 	 gemstash-customize(7)

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

@@ -0,0 +1,34 @@
+.\" Automatically generated by Pandoc 1.16.0.2
+.\"
+.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-debugging.7.txt

@@ -0,0 +1,29 @@
+gemstash-debugging(7)					 gemstash-debugging(7)
+
+
+
+DEBUGGING GEMSTASH
+       If  you	are  finding  Gemstash isn't behaving as you would expect, you
+       might want to start by looking at the server log.  You can find the log
+       at  server.log within your base directory.  By default, this will be at
+       ~/.gemstash/server.log.
+
+       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:
+
+	      $ gemstash start --no-daemonize
+
+       You can also check the status (gemstash help status.1) of the server:
+
+	      $ gemstash status
+
+       The  server  status  is	checked  by   passing	through   to   pumactl
+       (https://github.com/puma/puma#pumactl).
+
+       If  you	find  a  bug,  please  don't  hesitate	to  open  a bug report
+       (https://github.com/bundler/gemstash#contributing)!
+
+
+
+			       October 28, 2015 	 gemstash-debugging(7)

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

@@ -0,0 +1,40 @@
+.\" Automatically generated by Pandoc 1.16.0.2
+.\"
+.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 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.