gemstash 1.0.4 → 1.1.0

data/lib/gemstash/man/gemstash-configuration.5.txt

@@ -13,8 +13,15 @@ SYNOPSIS
 	      :memcached_servers: localhost:11211
 	      :db_adapter: postgres
 	      :db_url: postgres:///gemstash
+	      :db_connection_options:
+		:test: true
+		:pool_timeout: 2
 	      :rubygems_url: https://my.gem-source.local
+	      :puma_threads: 32
 	      :bind: tcp://0.0.0.0:4242
+	      :protected_fetch: true
+	      :fetch_timeout: 10
+	      :log_file: gemstash.log
 
 BASE PATH
        :base_path
@@ -64,21 +71,22 @@ DB ADAPTER
        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.
+       sqlite3.  When postgres, mysql, or mysql2 is used, the database to con-
+       nect to must be specified in the :db_url configuration key.  The  data-
+       base must already be created when using anything other than sqlite3.
 
    DEFAULT VALUE
        sqlite3
 
    VALID VALUES
-       sqlite3, postgres
+       sqlite3, postgres, mysql, mysql2
 
 DB URL
        :db_url
 
-       Specifies  the  database  to  connect  to  when	using postgres for the
-       :db_adapter.  Only used when postgres is used for :db_adapter.
+       Specifies  the  database  to  connect to when using postgres, mysql, or
+       mysql2 for the :db_adapter.  Only used  when  the  :db_adapter  is  not
+       sqlite3.
 
    DEFAULT VALUE
        None
@@ -87,6 +95,22 @@ DB URL
        A  valid  database  URL	for  the  Sequel  gem  (http://sequel.jeremye-
        vans.net/)
 
+DB CONNECTION OPTIONS
+       :db_connection_options
+
+       Specifies additional Sequel.connect options to use.  Note that any  op-
+       tions  here  are  merged  in  with the default options, so you need not
+       specify the max_connections if you customize this option.
+
+   DEFAULT VALUE
+       { max_connections: 1 }  for  sqlite3  adapter,  { max_connections: con-
+       fig[:puma_threads] + 1 } for any other adapter.
+
+   VALID VALUES
+       A  valid  connection  options  Hash  for the Sequel.connect (http://se-
+       quel.jeremyevans.net/rdoc/files/doc/opening_databases_rdoc.html#label-
+       General+connection+options) method.
+
 RUBYGEMS URL
        :rubygems_url
 
@@ -101,6 +125,17 @@ RUBYGEMS URL
    VALID VALUES
        A valid gem source URL
 
+PUMA THREADS
+       :puma_threads
+
+       Specifies the number of threads used for the Gemstash server.
+
+   DEFAULT VALUE
+       16
+
+   VALID VALUES
+       Integer value with a minimum of 1
+
 BIND ADDRESS
        :bind
 
@@ -116,6 +151,47 @@ BIND ADDRESS
        Any     valid	 binding     that     is     supported	   by	  Puma
        (https://github.com/puma/puma#binding-tcp--sockets)
 
+PROTECTED FETCH
+       :protected_fetch
+
+       Tells Gemstash to authenticate via  an  API  key  before  allowing  the
+       fetching  of  private gems and specs.  The default behavior is to allow
+       unauthenticated download of private gems and specs.
+
+   DEFAULT VALUE
+       false
+
+   VALID VALUES
+       Boolean values true or false
+
+FETCH TIMEOUT
+       :fetch_timeout
+
+       The timeout setting for fetching gems.  Fetching gems over a slow  con-
+       nection	may  cause  timeout errors.  If you experience timeout errors,
+       you may want to increase this value.  The default is 20 seconds.
+
+   DEFAULT VALUE
+       20
+
+   VALID VALUES
+       Integer value with a minimum of 1
+
+LOG FILE
+       :log_file
+
+       Indicates the name of the file to use for logging.  The	file  will  be
+       placed in the base path (gemstash help configuration.5).
+
+   DEFAULT VALUE
+       server.log
+
+   VALID VALUES
+       Any valid file name, or :stdout to log to $stdout
+
+       Note: Using :stdout for the :log_file requires running with --no-daemo-
+       nize (gemstash help start.1).
+
 
 
 			       October 13, 2015      gemstash-configuration(5)

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

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 1.16.0.2
+.\" Automatically generated by Pandoc 1.19.2.1
 .\"
 .TH "gemstash\-customize" "7" "October 28, 2015" "" ""
 .hy
@@ -16,7 +16,6 @@ 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
@@ -37,7 +36,7 @@ What is the comma separated Memcached servers?
 .P
 .PD
 What database adapter?
-[SQLITE3, postgres] \f[B]postgres\f[]
+[SQLITE3, postgres, mysql, mysql2] \f[B]postgres\f[]
 .PD 0
 .P
 .PD
@@ -55,16 +54,18 @@ Checking that the database is available
 .P
 .PD
 The database is not available
+.PD 0
+.P
+.PD
 .RE
 .PP
-Once you\[aq]ve answered the questsions, some checks will be made to
+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
-.PP
 $ gemstash setup \-\-redo
 .PD 0
 .P
@@ -85,7 +86,7 @@ What is the comma separated Memcached servers?
 .P
 .PD
 What database adapter?
-[SQLITE3, postgres]
+[SQLITE3, postgres, mysql, mysql2]
 .PD 0
 .P
 .PD
@@ -98,6 +99,9 @@ Checking that the database is available
 .P
 .PD
 You are all setup!
+.PD 0
+.P
+.PD
 .RE
 .PP
 Once all checks have passed, Gemstash will store your answers in the
@@ -130,10 +134,12 @@ The default \f[C]:db_adapter\f[] is
 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.
+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
@@ -142,13 +148,18 @@ Here is an example configuration to use the \f[C]postgres\f[] adapter:
 \-\-\-
 :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.
-Except for \f[C]sqlite3\f[], you only need to ensure the database exists
-and Gemstash will do the rest.
+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.
@@ -198,6 +209,36 @@ To change the binding, update the \f[C]:bind\f[] configuration key:
 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
@@ -222,3 +263,18 @@ 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-customize.7.txt

@@ -13,35 +13,34 @@ CUSTOMIZING THE SERVER
        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
+	      What database adapter?  [SQLITE3, postgres, mysql, mysql2] post-
+	      gres
 	      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
+       Once  you've answered the questions, 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
+       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-
+	      What   is   the  comma  separated  Memcached  servers?   [local-
 	      host:11211]
-	      What database adapter?  [SQLITE3, postgres]
+	      What database adapter?  [SQLITE3, postgres, mysql, mysql2]
 	      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
+       Once all checks have passed, Gemstash will store your  answers  in  the
        configuration file located at ~/.gemstash/config.yml.
 
    FILES
@@ -52,31 +51,38 @@ CUSTOMIZING THE SERVER
 	      ---
 	      :base_path: "/var/gemstash"
 
-       When  customizing  the  base_path,  the directory must exist, otherwise
+       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
+       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:
+       You  may  also	use   postgres	 (http://www.postgresql.org/),	 mysql
+       (http://www.mysql.com/),      or     mysql2     (http://sequel.jeremye-
+       vans.net/rdoc/files/doc/opening_databases_rdoc.html#label-mysql2)   for
+       your :db_adapter.  When using any of these options, you need to specify
+       the :db_url to point to an existing database.  Here is an example  con-
+       figuration to use the postgres adapter:
 
 	      # ~/.gemstash/config.yml
 	      ---
 	      :db_adapter: postgres
 	      :db_url: postgres:///gemstash
+	      :db_connection_options: # Sequel.connect options
+		:connect_timeout: 10
+		:read_timeout: 5
+		:timeout: 30
 
-       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.
+       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 sqlite3 (for which Gemstash will also create the data-
+       base for you).
 
    CACHE
        Certain	things	(like dependencies) are cached in memory.  This avoids
@@ -115,9 +121,31 @@ CUSTOMIZING THE SERVER
        (https://github.com/puma/puma#binding-tcp--sockets), and  will  support
        anything valid for that flag.
 
+       The   number  of  threads  Puma	uses  is  also	customizable  via  the
+       :puma_threads configuration key.  The default is 16.
+
+   PROTECTED FETCH
+       Gemstash by default allows unauthenticated  access  for	private  gems.
+       Authenticated  access  is available via the :protected_fetch configura-
+       tion key.
+
+	      # ~/.gemstash/config.yml
+	      ---
+	      :protected_fetch: true
+
+       More details  on  protected_fetch  are  here  (gemstash	help  private-
+       gems.7).
+
+   FETCH TIMEOUT
+       The  default  fetch timeout is 20 seconds.  Use the :fetch_timeout con-
+       figuration key to change it.
+
+	      ---
+	      :fetch_timeout: 20
+
    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
+       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
@@ -126,12 +154,22 @@ CUSTOMIZING THE SERVER
 	      $ 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
+       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.
 
+   ERB PARSED CONFIG
+       You may also create a  ~/.gemstash/config.yml.erb  file.   If  present,
+       this will be used instead of ~/.gemstash/config.yml.  For example, with
+       this you can use environment variables in the config:
+
+	      # ~/.gemstash/config.yml.erb
+	      ---
+	      :db_adapter: postgres
+	      :db_url: <%= ENV["DATABASE_URL"] %>
+
 
 
 			       October 28, 2015 	 gemstash-customize(7)

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

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 1.16.0.2
+.\" Automatically generated by Pandoc 1.19.2.1
 .\"
 .TH "gemstash\-debugging" "7" "October 28, 2015" "" ""
 .hy

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

@@ -1,4 +1,4 @@
-.\" Automatically generated by Pandoc 1.16.0.2
+.\" Automatically generated by Pandoc 1.19.2.1
 .\"
 .TH "gemstash\-deploy" "7" "October 25, 2015" "" ""
 .hy
@@ -34,6 +34,38 @@ $\ 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.