gemstash 2.0.0 → 2.1.0

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

@@ -1,66 +1,210 @@
+gemstash-configuration(5)			     gemstash-configuration(5)
 
 
 
+1mNAME0m
+       gemstash-configuration
 
+1mSYNOPSIS0m
+	      # ~/.gemstash/config.yml
+	      ---
+	      :base_path: "/var/gemstash"
+	      :cache_type: memcached
+	      :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
+	      :ignore_gemfile_source: false
+	      :puma_threads: 32
+	      :bind: tcp://0.0.0.0:4242
+	      :protected_fetch: true
+	      :fetch_timeout: 10
+	      :log_file: gemstash.log
 
+1mBASE PATH0m
+       :base_path
 
+       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 Gem-
+       stash  server  process.	 Specifying  the :base_path via gemstash setup
+       (gemstash help setup.1) will create the directory for you.
 
+   1mDEFAULT VALUE0m
+       ~/.gemstash
 
+   1mVALID VALUES0m
+       Any valid path
 
+1mCACHE TYPE0m
+       :cache_type
 
+       Specifies how to cache values other than gem files (such as gem	depen-
+       dencies).   memory  will	 use  an  in memory cache while memcached will
+       point to 1 or more Memcached servers.  Use the :memcached_servers  con-
+       figuration key for specifying where the Memcached server(s) are.
 
+   1mDEFAULT VALUE0m
+       memory
 
+   1mVALID VALUES0m
+       memory, memcached
 
+1mMEMCACHED SERVERS0m
+       :memcached_servers
 
+       Specifies  the Memcached servers to connect to when using memcached for
+       the :cache_type.	 Only used when memcached is used for :cache_type.
 
+   1mDEFAULT VALUE0m
+       localhost:11211
 
+   1mVALID VALUES0m
+       A comma delimited list of Memcached servers
 
+1mDB ADAPTER0m
+       :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, 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.
 
+   1mDEFAULT VALUE0m
+       sqlite3
 
+   1mVALID VALUES0m
+       sqlite3, postgres, mysql, mysql2
 
+1mDB URL0m
+       :db_url
 
+       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.
 
+   1mDEFAULT VALUE0m
+       None
 
+   1mVALID VALUES0m
+       A  valid	 database  URL	for  the  Sequel  gem  (http://sequel.jeremye-
+       vans.net/)
 
+1mDB CONNECTION OPTIONS0m
+       :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.
 
+   1mDEFAULT VALUE0m
+       { max_connections: 1 } for sqlite3  adapter,  {	max_connections:  con-
+       fig[:puma_threads] + 1 } for any other adapter.
 
+   1mVALID VALUES0m
+       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.
 
+1mRUBYGEMS URL0m
+       :rubygems_url
 
+       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.
 
+   1mDEFAULT VALUE0m
+       https://rubygems.org
 
+   1mVALID VALUES0m
+       A valid gem source URL
 
+1mIGNORE GEMFILE SOURCE0m
+       :ignore_gemfile_source
 
+       Ignore the source specified in Gemfile and always use :rubygems_url  as
+       gems upstream.
 
+   1mDEFAULT VALUE0m
+       false
 
+   1mVALID VALUES0m
+       Boolean: true or false
 
+1mPUMA THREADS0m
+       :puma_threads
 
+       Specifies the number of threads used for the Gemstash server.
 
+   1mDEFAULT VALUE0m
+       16
 
+   1mVALID VALUES0m
+       Integer value with a minimum of 1
 
+1mBIND ADDRESS0m
+       :bind
 
+       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 Gem-
+       stash as the root user.
 
+   1mDEFAULT VALUE0m
+       tcp://0.0.0.0:9292
 
+   1mVALID VALUES0m
+       Any     valid	 binding     that     is     supported	   by	  Puma
+       (https://github.com/puma/puma#binding-tcp--sockets)
 
+1mPROTECTED FETCH0m
+       :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.
 
+   1mDEFAULT VALUE0m
+       false
 
+   1mVALID VALUES0m
+       Boolean values true or false
 
+1mFETCH TIMEOUT0m
+       :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.
 
+   1mDEFAULT VALUE0m
+       20
 
+   1mVALID VALUES0m
+       Integer value with a minimum of 1
 
+1mLOG FILE0m
+       :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).
 
+   1mDEFAULT VALUE0m
+       server.log
 
+   1mVALID VALUES0m
+       Any valid file name, or :stdout to log to $stdout
 
+       4mNote:24m 4mUsing24m 4m:stdout24m 4mfor24m 4mthe24m 4m:log_file24m 4mrequires24m 4mrunning24m 4mwith24m 4m--no-daemo-0m
+       4mnize24m 4m(gemstash24m 4mhelp24m 4mstart.1).0m
 
 
 
-
-
-
-
-
-
+			       October 13, 2015	     gemstash-configuration(5)

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

@@ -0,0 +1,301 @@
+.\" 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