4mgemstash-customize24m(7) 4mgemstash-customize24m(7)
<!– Automatically generated by Pandoc –>
1mCustomizing the Server0m
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. 1mSetup0m 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] 1mmemcached0m What is the comma separated Memcached servers? [local- host:11211] What database adapter? [SQLITE3, postgres, mysql, mysql2] 1mpost-0m 1mgres0m 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 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 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] 1mmemcached0m What is the comma separated Memcached servers? [local- host:11211] 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 configuration file located at ~/.gemstash/config.yml. 1mFiles0m 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. 1mDatabase0m 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/), 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. 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). 1mCache0m Certain things (like dependencies) are cached in memory. This avoids web calls to the gem source, and database calls for private gems. # ~/.gemstash/config.yml --- :cache_type: memory :cache_max_size: 2000 This configuration uses the default memory cache, and has increased the cache_max_size setting from its default of 500 items. The memory cache can optionally be swapped out with a Memcached (http://memcached.org/) server (or cluster of servers). To use Memcached, use the memcached :cache_type configuration. Provide the servers as a comma-separated list to the :memcached_servers configuration key: # ~/.gemstash/config.yml --- :cache_type: memcached :memcached_servers: memcached1.local:11211,memcached2.local:11211 :cache_expiration: 1800 All caching expires in cache_expiration number of seconds. Default is 1800 seconds (30 minutes). This option applies to all caching. 1mServer0m 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/rubygems/gemstash/blob/master/lib/gemstash/puma.rb) and the rackup file (https://github.com/rubygems/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. The number of threads Puma uses is also customizable via the :puma_threads configuration key. The default is 16. 1mProtected Fetch0m 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. 1mFetch Timeout0m The default fetch timeout is 20 seconds. Use the :fetch_timeout con- figuration key to change it. --- :fetch_timeout: 20 1mConfig File Location0m 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. 1mThis will overwrite 22many 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. 1mERB parsed config0m 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 4mgemstash-customize24m(7)