<!– Automatically generated by Pandoc –> ." Automatically generated by Pandoc 3.1.8 ." .TH “gemstash-private-gems” “7” “October 8, 2015” “” “” .SH Private Gems Stashing private gems in your Gemstash server requires a bit of additional setup. If you havent read through the Quickstart Guide, you should do that first. By the end of this guide, you will be able to interact with your Gemstash server to store and retrieve your private gems. .SS Authorizing f[B]IMPORTANT NOTE:f Do not use the actual key value in this document, otherwise your Gemstash server will be vulnerable to anyone who wants to try to use the key against your server. Instead of the key value here, use whatever key is generated from running the commands. .PP In order to push a gem to your Gemstash server, you need to first create an API key. Utilize the f[CR]gemstash authorizef command to create the API key: .IP .EX $ gemstash authorize Your new key is: e374e237fdf5fa5718d2a21bd63dc911 .EE .PP This new key can f[CR]pushf[R], f[CR]yankf[R], and f[CR]fetchf[R] gems from your Gemstash server. Run f[CR]gemstash authorizef with just the permissions you want to limit what the key will be allowed to do. You can similarly update a specific key by providing it via the f[CR]–keyf option: .IP .EX $ gemstash authorize push yank –key e374e237fdf5fa5718d2a21bd63dc911 .EE .PP When no permissions are provided (like the first example), the key will be authorized for all permissions. Leave the key authorized with everything if you want to use it to try all private gem interactions: .IP .EX $ gemstash authorize –key e374e237fdf5fa5718d2a21bd63dc911 .EE .PP With the key generated, youll need to tell Rubygems about your new key. If youve pushed a gem to rubygems.org, then you will already have a credentials file to add the key to. If not, run the following commands before modifying the credentials file: .IP .EX $ mkdir -p [ti]/.gem $ touch [ti]/.gem/credentials $ chmod 0600 [ti]/.gem/credentials .EE .PP Add your new key to credentials such that it looks something like this (but make sure not to remove any existing keys): .IP .EX # [ti]/.gem/credentials


:test_key: e374e237fdf5fa5718d2a21bd63dc911 .EE .PP The name f[CR]test_keyf[R] can be anything you want, but you will need to remember it and use it again later in this guide for the f[CR]–keyf option. .SS Creating a Test Gem Youll need a test gem before you can play with private gems on your Gemstash server. If you have a gem you can use, move along to the next section. You can start by instantiating a test gem via Bundler: .IP .EX $ bundle gem private-example .EE .PP Youll need to add a summary and description to the new gems gemspec file in order to successfully build it. Once youve built the gem, you will be ready to push the new gem. .IP .EX $ cd private-example $ rake build .EE .PP You will now have a gem at f[CR]private-example/pkg/private-example-0.1.0.gemf[R]. .SS Pushing If your Gemstash server isnt running, go ahead and start it: .IP .EX $ gemstash start .EE .PP Push your test gem using Rubygems: .IP .EX $ gem push –key test_key –host localhost:9292/private pkg/private-example-0.1.0.gem .EE .PP The f[CR]/privatef portion of the f[CR]–hostf option tells Gemstash you are interacting with the private gems. Gemstash will not let you push, or yank from anything except f[CR]/privatef. .SS Bundling Once your gem is pushed to your Gemstash server, you are ready to bundle it. Create a f[CR]Gemfilef[R] and specify the gem. You will probably want to wrap the private gem in a source block, and let the rest of Gemstash handle all other gems: .IP .EX # ./Gemfile source [dq]http://localhost:9292[dq] gem [dq]rubywarrior[dq]

source [dq]http://localhost:9292/private[dq] do

gem \[dq]private-example\[dq]

end .EE .PP Notice that the Gemstash server points to f[CR]/privatef again when installing your private gem. Go ahead and bundle to install your new private gem: .IP .EX $ bundle .EE .SS Yanking If you push a private gem by accident, you can yank the gem with Rubygems: .IP .EX $ RUBYGEMS_HOST=localhost:9292/private gem yank –key test_key private-example –version 0.1.0 .EE .PP Like with pushing, the f[CR]/privatef portion of the host option tells Gemstash you are interacting with private gems. Gemstash will only let you yank from f[CR]/privatef. Unlike pushing, Rubygems doesnt support f[CR]–hostf for yank (yet), so you need to specify the host via the f[CR]RUBYGEMS_HOSTf[R] environment variable. .SS Protected Fetching By default, private gems and specs can be accessed without authentication. .PP Private gems often require protected fetching. For backwards compatibility this is disabled by default, but can be enabled via f[CR]$ gemstash setupf command. .PP When protected fetching is enabled API keys with the permissions f[CR]allf[R] or f[CR]fetchf[R] can be used to download gems and specs. .PP On the Bundler side, there are a few ways to configure credentials for a given gem source: .PP Add credentials globally: .IP .EX $ bundle config my-gemstash.dev api_key .EE .PP Add credentials in Gemfile: .IP .EX source [dq]https://api_key[at]my-gemstash.dev[dq] .EE .PP However, its not a good practice to commit credentials to source control. A recommended solution is to use Bundlers configuration keys (bundler.io/man/bundle-config.1.html#CONFIGURATION-KEYS), e.g.: .IP .EX $ export BUNDLE_MYGEMSTASH__DEV=api_key .EE .PP Behind the scene, Bundler will pick up the ENV var according to the host name (e.g.\ mygemstash.dev) and add to f[CR]URI.userinfof[R] for making requests. .PP The API key is treated as a HTTP Basic Auth username and any HTTP Basic password supplied will be ignored.