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)