<!– Automatically generated by Pandoc –> ." Automatically generated by Pandoc 3.1.8 ." .TH “gemstash-customize” “7” “October 28, 2015” “” “” .SH 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 Gemstash uses, and how Gemstash caches certain requests. .SS Setup Several customizable options are available via an interactive Gemstash command. Run f[CR]gemstash setupf 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]memcachedf[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]postgresf[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 youve answered the questions, some checks will be made to ensure the configuration will work. For example, the database didnt exist in the previous example, so the command failed and the configuration wasnt saved. If the command passes, you may provide the f[CR]–redof option to force configuration to be redone: .RS .PP f[CR]$ gemstash setup –redof .PD 0 .P .PD Where should files go?

[ti]/.gemstash

.PD 0 .P .PD Cache with what?

MEMORY, memcached

f[B]memcachedf[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[CR][ti]/.gemstash/config.ymlf. .SS Files Storage in Gemstash defaults to f[CR][ti]/.gemstashf unless otherwise specified. You can change this in your config file via the f[CR]:base_pathf key: .IP .EX # [ti]/.gemstash/config.yml


:base_path: [dq]/var/gemstash[dq] .EE .PP When customizing the f[CR]base_pathf[R], the directory must exist, otherwise Gemstash will fail to run. Thus, if you want to use f[CR]/var/gemstashf like in the previous example, make sure to f[CR]mkdir /var/gemstashf[R] and grant access to the directory for the user you run Gemstash with. .SS Database The f[CR]:db_adapterf configuration key specifies what database you will be using. The default f[CR]:db_adapterf is f[CR]sqlite3f[R] (www.sqlite.org/), which will use a database file located within your f[CR]:base_pathf. The database file will always be named f[CR]gemstash.dbf[R]. .PP You may also use f[CR]postgresf[R] (www.postgresql.org/), f[CR]mysqlf[R] (www.mysql.com/), or f[CR]mysql2f[R] (sequel.jeremyevans.net/rdoc/files/doc/opening_databases_rdoc.html#label-mysql2) for your f[CR]:db_adapterf. When using any of these options, you need to specify the f[CR]:db_urlf to point to an existing database. Here is an example configuration to use the f[CR]postgresf[R] adapter: .IP .EX # [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

.EE .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[CR]sqlite3f[R] (for which Gemstash will also create the database for you). .SS Cache Certain things (like dependencies) are cached in memory. This avoids web calls to the gem source, and database calls for private gems. .IP .EX # [ti]/.gemstash/config.yml


:cache_type: memory :cache_max_size: 2000 .EE .PP This configuration uses the default f[CR]memoryf[R] cache, and has increased the f[CR]cache_max_sizef[R] setting from its default of 500 items. .PP The memory cache can optionally be swapped out with a Memcached (memcached.org/) server (or cluster of servers). .PP To use Memcached, use the f[CR]memcachedf[R] f[CR]:cache_typef configuration. .PP Provide the servers as a comma-separated list to the f[CR]:memcached_serversf configuration key: .IP .EX # [ti]/.gemstash/config.yml


:cache_type: memcached :memcached_servers: memcached1.local:11211,memcached2.local:11211 :cache_expiration: 1800 .EE .PP All caching expires in f[CR]cache_expirationf[R] number of seconds. Default is 1800 seconds (30 minutes). This option applies to all caching. .SS Server Gemstash uses Puma (puma.io/) and Rack (rack.github.io/) as the server. Alternate server configurations are not currently supported, but you can take a look at the Puma configuration (github.com/rubygems/gemstash/blob/master/lib/gemstash/puma.rb) and the rackup file (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[CR]:bindf configuration key: .IP .EX # [ti]/.gemstash/config.yml


:bind: tcp://0.0.0.0:4242 .EE .PP This maps directly to the Puma bind flag (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[CR]:puma_threadsf configuration key. The default is f[CR]16f[R]. .SS Protected Fetch Gemstash by default allows unauthenticated access for private gems. Authenticated access is available via the f[CR]:protected_fetchf configuration key. .IP .EX # [ti]/.gemstash/config.yml


:protected_fetch: true .EE .PP More details on protected_fetch are here. .SS Fetch Timeout The default fetch timeout is 20 seconds. Use the f[CR]:fetch_timeoutf configuration key to change it. .IP .EX


:fetch_timeout: 20 .EE .SS Config File Location By default, configuration for Gemstash will be at f[CR][ti]/.gemstash/config.ymlf. This can be changed by providing the f[CR]–config-filef option to the various Gemstash commands: .IP .EX $ 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 .EE .PP When providing f[CR]–config-filef to f[CR]gemstash setupf, the provided file will be output to with the provided configuration. f[B]This will overwritef any existing configuration. If the file doesnt exist when providing f[CR]–config-filef to f[CR]gemstash startf, f[CR]gemstash stopf, f[CR]gemstash statusf, and f[CR]gemstash authorizef, the default configuration will be used. .SS ERB parsed config You may also create a f[CR][ti]/.gemstash/config.yml.erbf file. If present, this will be used instead of f[CR][ti]/.gemstash/config.ymlf. For example, with this you can use environment variables in the config: .IP .EX # [ti]/.gemstash/config.yml.erb


:db_adapter: postgres :db_url: <%= ENV[[dq]DATABASE_URL] %> .EE