### Install Dependencies and Run Tests

Source: https://github.com/rubygems/gemstash/blob/main/README.md

After cloning the repository, use this command to install dependencies. Then, run this command to execute RuboCop and the test suite.

```bash
bin/setup
```

```bash
rake
```

--------------------------------

### Start Gemstash Server

Source: https://github.com/rubygems/gemstash/blob/main/man/gemstash-debugging.7.md

Use this command to start the Gemstash server. Logs are output directly to standard out.

```bash
$ gemstash start
```

--------------------------------

### Interactive Gemstash Setup

Source: https://github.com/rubygems/gemstash/blob/main/man/gemstash-customize.7.md

Run `gemstash setup` to interactively configure Gemstash. Blank answers use default values. The command checks for cache and database availability.

```bash
$ gemstash setup
Where should files go? [~/.gemstash]
Cache with what? [MEMORY, memcached] **memcached**
What is the comma separated Memcached servers? [localhost:11211]
What database adapter? [SQLITE3, postgres, mysql, mysql2] **postgres**
Where is the database? [postgres:///gemstash]
Checking that the cache is available
Checking that the database is available
The database is not available

```

```bash
`gemstash setup --redo`
Where should files go? [~/.gemstash]
Cache with what? [MEMORY, memcached] **memcached**
What is the comma separated Memcached servers? [localhost:11211]
What database adapter? [SQLITE3, postgres, mysql, mysql2]
Checking that the cache is available
Checking that the database is available
You are all setup!

```

--------------------------------

### Interactive Gemstash Setup

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-customize.7.md

Run `gemstash setup` to interactively configure Gemstash. Blank answers use defaults. The command checks configuration validity before saving.

```bash
$ gemstash setup  
Where should files go? [~/.gemstash]  
Cache with what? [MEMORY, memcached] **memcached**  
What is the comma separated Memcached servers? [localhost:11211]  
What database adapter? [SQLITE3, postgres, mysql, mysql2] 
**postgres**  
Where is the database? [postgres:///gemstash]  
Checking that the cache is available  
Checking that the database is available  
The database is not available  
```

```bash
$ gemstash setup --redo  
Where should files go? [~/.gemstash]  
Cache with what? [MEMORY, memcached] **memcached**  
What is the comma separated Memcached servers? [localhost:11211]  
What database adapter? [SQLITE3, postgres, mysql, mysql2]  
Checking that the cache is available  
Checking that the database is available  
You are all setup!  
```

--------------------------------

### Run Gemstash Interactive Setup

Source: https://context7.com/rubygems/gemstash/llms.txt

Initiates an interactive setup wizard for Gemstash configuration, saving settings to `~/.gemstash/config.yml`. Supports redoing configuration and debug output.

```bash
gemstash setup
```

```bash
gemstash setup --redo
```

```bash
gemstash setup --config-file /etc/gemstash/config.yml
```

```bash
gemstash setup --redo --debug
```

--------------------------------

### Start Gemstash Server

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-debugging.7.md

Run this command to start the Gemstash server and output logs directly to standard output for easier monitoring.

```bash
gemstash start
```

--------------------------------

### Redo Gemstash Setup

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-setup.1.md

If you need to change your Gemstash configuration after the initial setup, use the --redo option. Without it, the command will indicate that setup is already complete.

```bash
gemstash setup --redo
```

--------------------------------

### Show Gemstash Version

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-version.1.md

Use this command to display the installed version of Gemstash. No setup or imports are required.

```bash
gemstash version
```

```bash
gemstash --version
```

```bash
gemstash -v
```

--------------------------------

### Run Gemstash Server

Source: https://github.com/rubygems/gemstash/blob/main/README.md

Execute this command to start the Gemstash server during development.

```bash
bin/gemstash
```

--------------------------------

### Gemstash Configuration File Example

Source: https://github.com/rubygems/gemstash/blob/main/man/gemstash-configuration.5.md

This is an example of a Gemstash configuration file (`config.yml`). It demonstrates how to set various options such as base path, cache type, database adapter, rubygems URL, and server binding.

```yaml
---
: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
:open_timeout: 2
:log_file: gemstash.log

```

--------------------------------

### Install Gemstash

Source: https://github.com/rubygems/gemstash/blob/main/README.md

Install the Gemstash gem using the RubyGems package manager.

```bash
gem install gemstash
```

--------------------------------

### Bundle Install with Gemstash

Source: https://github.com/rubygems/gemstash/blob/main/README.md

Install gems using Bundler after configuring Gemstash. This command will fetch gems through your Gemstash server.

```bash
bundle install --path .bundle
```

--------------------------------

### Enable Debug Output for Gemstash Setup

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-setup.1.md

If setup checks fail, use the --debug option to display additional information that can help diagnose the issue. This option has no effect if all checks pass.

```bash
gemstash setup --debug
```

--------------------------------

### Run Gemstash Setup Interactively

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-setup.1.md

Use this command to initiate the interactive configuration process for Gemstash. This is the standard way to set up your Gemstash environment.

```bash
gemstash setup
```

--------------------------------

### Gemfile Example

Source: https://github.com/rubygems/gemstash/blob/main/README.md

A basic Gemfile specifying a source and a gem. When using Gemstash, gems will be fetched through it.

```ruby
source "https://rubygems.org"
gem "rubywarrior"
```

--------------------------------

### Start Gemstash with Environment Variable Authentication

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-multiple-sources.7.md

Start the Gemstash server with authentication credentials set in an environment variable. The variable name is derived from the gem source host.

```bash
GEMSTASH_MY__GEM___SOURCE__LOCAL=user:password gemstash start --config-file config.yml.erb
```

--------------------------------

### Install Gems Through Gemstash

Source: https://github.com/rubygems/gemstash/blob/main/man/gemstash-readme.7.md

Install gems using Bundler after configuring it to use Gemstash. This command will fetch gems from RubyGems.org and cache them in Gemstash.

```bash
$ bundle install --path .bundle
```

--------------------------------

### Run Gemstash Interactively

Source: https://github.com/rubygems/gemstash/blob/main/man/gemstash-readme.7.md

Use this command to start Gemstash during development. The `bin/console` command provides an interactive prompt for experimentation.

```bash
bin/gemstash
```

```bash
bin/console
```

--------------------------------

### Docker Compose Up Command

Source: https://context7.com/rubygems/gemstash/llms.txt

Command to start the Gemstash service defined in docker-compose.yml in detached mode.

```bash
docker-compose up -d
```

--------------------------------

### Bundle Install Without Internet

Source: https://github.com/rubygems/gemstash/blob/main/README.md

Demonstrates bundling without an internet connection after gems have been cached by Gemstash. Ensure your internet is disabled before running.

```bash
# Disable your Internet first!
rm -rf Gemfile.lock .bundle
bundle
```

--------------------------------

### Dockerfile for Gemstash

Source: https://context7.com/rubygems/gemstash/llms.txt

Build a Docker image for Gemstash. This includes installing necessary packages, the gemstash gem, setting up a volume for data, and exposing the default port.

```dockerfile
# Dockerfile
FROM ruby:3.2-alpine

RUN apk add --no-cache build-base sqlite-dev
RUN gem install gemstash

RUN mkdir -p /var/gemstash
VOLUME /var/gemstash

EXPOSE 9292

CMD ["gemstash", "start", "--config-file", "/var/gemstash/config.yml"]
```

--------------------------------

### Systemd Service Management Commands

Source: https://context7.com/rubygems/gemstash/llms.txt

Commands to enable, start, and check the status of the Gemstash systemd service.

```bash
# Enable and start the service
sudo systemctl enable gemstash
sudo systemctl start gemstash
sudo systemctl status gemstash
```

--------------------------------

### Restart Gemstash Server

Source: https://github.com/rubygems/gemstash/blob/main/man/gemstash-multiple-sources.7.md

Commands to stop and start the Gemstash server after configuration changes.

```bash
$ gemstash stop
$ gemstash start
```

--------------------------------

### Stop and Start Gemstash Service

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-deploy.7.md

Recommended commands to stop Gemstash before updating, then update and restart the service.

```bash
$ bundle exec gemstash stop
$ bundle update
$ bundle exec gemstash start
```

--------------------------------

### Configure Bundler Fallback Timeout (Seconds)

Source: https://github.com/rubygems/gemstash/blob/main/README.md

Configure Bundler to fallback to RubyGems.org after a specified timeout if the Gemstash server is unresponsive. This example sets a 3-second timeout.

```bash
bundle config mirror.https://rubygems.org.fallback_timeout 3
```

--------------------------------

### Configure Bundler Fallback Timeout (Seconds)

Source: https://github.com/rubygems/gemstash/blob/main/man/gemstash-readme.7.md

Configure Bundler to fallback to RubyGems.org after a specified timeout in seconds if the Gemstash server is unresponsive. This example sets a 3-second timeout.

```bash
$ bundle config mirror.https://rubygems.org.fallback_timeout 3
```

--------------------------------

### Add Gemstash to Gemfile

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-deploy.7.md

Add this to your Gemfile to manage Gemstash with Bundler. Run `bundle` to install and `bundle update` to upgrade.

```ruby
# ./Gemfile
source "https://rubygems.org"
gem "gemstash"
```

--------------------------------

### ERB Configuration with Environment Variables

Source: https://context7.com/rubygems/gemstash/llms.txt

Example of a Gemstash configuration file using ERB templating (`config.yml.erb`) to dynamically set database URLs and other settings based on environment variables.

```yaml
# ~/.gemstash/config.yml.erb
---
:db_adapter: postgres
:db_url: "<%= ENV["DATABASE_URL"] %>"
:memcached_servers: "<%= ENV["MEMCACHED_URL"] || "localhost:11211" %>"
:protected_fetch: "<%= ENV["PROTECTED_FETCH"] == "true" %>"
```

--------------------------------

### Gemstash Production Configuration with PostgreSQL and Memcached

Source: https://context7.com/rubygems/gemstash/llms.txt

Example configuration file for Gemstash in a production environment. It specifies database adapter, URL, connection options, cache type, Memcached servers, and security settings.

```yaml
# /etc/gemstash/config.yml
---
:base_path: "/var/gemstash"
:bind: tcp://0.0.0.0:9292
:puma_threads: 32
:puma_workers: 4

# PostgreSQL for reliability
:db_adapter: postgres
:db_url: postgres://gemstash:password@db.example.com/gemstash
:db_connection_options:
  :max_connections: 25
  :pool_timeout: 10

# Memcached cluster for caching
:cache_type: memcached
:memcached_servers: cache1.example.com:11211,cache2.example.com:11211
:cache_expiration: 1800

# Security
:protected_fetch: true
:fetch_timeout: 30
:open_timeout: 5

# Logging
:log_file: :stdout
```

--------------------------------

### Authorize API Key for Gemstash

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-private-gems.7.md

Generates a new API key for Gemstash. The key can be authorized for specific permissions like push, yank, and fetch, or all permissions by default. Use the generated key, not the example.

```bash
$ gemstash authorize
Your new key is: e374e237fdf5fa5718d2a21bd63dc911
```

```bash
$ gemstash authorize push yank --key e374e237fdf5fa5718d2a21bd63dc911
```

```bash
$ gemstash authorize --key e374e237fdf5fa5718d2a21bd63dc911
```

--------------------------------

### Gemstash Heartbeat Health Check

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-deploy.7.md

Example endpoint for a health check that only verifies the server is running, without testing storage or database access.

```bash
/health/heartbeat
```

--------------------------------

### Docker Compose Configuration for Gemstash

Source: https://context7.com/rubygems/gemstash/llms.txt

Define a Docker Compose service for Gemstash. This setup maps ports, mounts volumes for data and configuration, and sets the environment variable for the config file.

```yaml
# docker-compose.yml
version: '3' 
services:
  gemstash:
    build: .
    ports:
      - "9292:9292"
    volumes:
      - gemstash-data:/var/gemstash
      - ./config.yml:/var/gemstash/config.yml:ro
    environment:
      - GEMSTASH_CONFIG=/var/gemstash/config.yml

volumes:
  gemstash-data:
```

--------------------------------

### Interactive Console

Source: https://github.com/rubygems/gemstash/blob/main/README.md

Use this command to launch an interactive console for experimenting with Gemstash.

```bash
bin/console
```

--------------------------------

### Build a Test Gem

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-private-gems.7.md

Creates and builds a new gem for testing private gem functionality. Requires adding a summary and description to the gemspec file.

```bash
$ bundle gem private-example
```

```bash
$ cd private-example
$ rake build
```

--------------------------------

### Configure API Key via Environment Variable

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-private-gems.7.md

Set an environment variable to provide your API key. Bundler automatically picks up this variable based on the host name, treating the API key as the HTTP Basic Auth username. This is a recommended approach for managing credentials securely.

```bash
$ export BUNDLE_MYGEMSTASH__DEV=api_key
```

--------------------------------

### Enable Protected Fetching

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-private-gems.7.md

Run this command to enable protected fetching for private gems. This is disabled by default for backward compatibility.

```bash
$ gemstash setup
```

--------------------------------

### Set API Key via Environment Variable

Source: https://github.com/rubygems/gemstash/blob/main/man/gemstash-private-gems.7.md

Use an environment variable to provide the API key, which is a recommended secure method. Bundler automatically picks up the ENV var based on the host name.

```bash
export BUNDLE_MYGEMSTASH__DEV=api_key
```

--------------------------------

### Configure ~/.gem/credentials for Gemstash

Source: https://github.com/rubygems/gemstash/blob/main/man/gemstash-private-gems.7.md

Sets up the credentials file for Rubygems to use with your Gemstash server. Ensure the key value is kept secure and not shared publicly.

```bash
$ mkdir -p ~/.gem
$ touch ~/.gem/credentials
$ chmod 0600 ~/.gem/credentials
```

```yaml
# ~/.gem/credentials
---
:test_key: e374e237fdf5fa5718d2a21bd63dc911
```

--------------------------------

### Gemstash Health Check Response

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-deploy.7.md

Example JSON response for a successful health check from a Gemstash instance. This checks storage and database access.

```json
{
  "status": {
    "heartbeat": "OK",
    "storage_read": "OK",
    "storage_write": "OK",
    "db_read": "OK",
    "db_write": "OK"
  }
}
```

--------------------------------

### Configure Bundler Mirror (Older Versions)

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-mirror.7.md

Use this command to configure Bundler to mirror gems from http://rubygems.org and https://my.gem-source.local through your Gemstash server. This method requires manual URL encoding for custom sources.

```bash
$ bundle config mirror.http://rubygems.org http://localhost:9292
$ bundle config mirror.https://my.gem-source.local http://localhost:9292/upstream/$(ruby -rcgi -e 'puts CGI.escape("https://my.gem-source.local")')
```

--------------------------------

### Gemfile with Authentication for Multiple Sources

Source: https://github.com/rubygems/gemstash/blob/main/man/gemstash-multiple-sources.7.md

Specify authentication credentials (username:password or API key) directly in the Gemfile for private gem sources. Ensure proper URL escaping.

```ruby
# ./Gemfile
require "cgi"
source "http://localhost:9292"

source "http://localhost:9292/upstream/#{CGI.escape("user:password@my.gem-source.local")}" do
  gem "my-gem"
end

source "http://localhost:9292/upstream/#{CGI.escape("api_key@my-other.gem-source.local")}" do
  gem "my-other-gem"
end
```

--------------------------------

### Configure Bundler Mirror (Bundler 1.11.0+)

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-mirror.7.md

For Bundler versions 1.11.0 and later, mirroring is simplified. Bundler automatically sends headers to Gemstash to indicate the correct upstream source, making configuration easier.

```bash
$ bundle config mirror.http://rubygems.org http://localhost:9292
$ bundle config mirror.https://my.gem-source.local http://localhost:9292
```

--------------------------------

### Gemfile with Authenticated Multiple Sources

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-multiple-sources.7.md

Configure authenticated gem sources directly in the Gemfile using basic authentication or API keys. Ensure proper URL encoding for sensitive information.

```ruby
require "cgi"
source "http://localhost:9292"

source "http://localhost:9292/upstream/#{CGI.escape("user:password@my.gem-source.local")}" do
  gem "my-gem"
end

source "http://localhost:9292/upstream/#{CGI.escape("api_key@my-other.gem-source.local")}" do
  gem "my-other-gem"
end
```

--------------------------------

### Configure ~/.gem/credentials

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-private-gems.7.md

Adds a new API key to the Rubygems credentials file. Ensure the key name (e.g., :test_key) is remembered for later use.

```yaml
# ~/.gem/credentials
---
:test_key: e374e237fdf5fa5718d2a21bd63dc911
```

--------------------------------

### Bundle Without Internet Connection

Source: https://github.com/rubygems/gemstash/blob/main/man/gemstash-readme.7.md

Demonstrates bundling gems when the internet connection is disabled, relying on the cached gems in Gemstash. Ensure Gemstash is running.

```bash
$ # Disable your Internet first!
$ rm -rf Gemfile.lock .bundle
$ bundle
```

--------------------------------

### Configure Bundler Fallback Timeout (Boolean)

Source: https://github.com/rubygems/gemstash/blob/main/README.md

Configure Bundler to fallback to RubyGems.org if the Gemstash server is unresponsive. Setting this to 'true' enables the fallback mechanism.

```bash
bundle config mirror.https://rubygems.org.fallback_timeout true
```

--------------------------------

### Configure API Key in Gemfile

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-private-gems.7.md

Include the API key directly in the source URL within your Gemfile. Note that this is generally not recommended for security reasons as it may lead to credentials being committed to source control.

```ruby
source "https://api_key@my-gemstash.dev"
```

--------------------------------

### Bundle with Multiple Gem Sources in Gemfile

Source: https://github.com/rubygems/gemstash/blob/main/man/gemstash-multiple-sources.7.md

Configure your Gemfile to use multiple gem sources, including custom upstream sources. Use CGI.escape for URLs with special characters or credentials.

```ruby
# ./Gemfile
require "cgi"
source "http://localhost:9292"
gem "rubywarrior"

source "http://localhost:9292/upstream/#{CGI.escape("https://my.gem-source.local")}" do
  gem "my-gem"
end

source "http://localhost:9292/upstream/my-other.gem-source.local" do
  gem "my-other-gem"
end
```

--------------------------------

### Configure Bundler Credentials for Private Gems

Source: https://context7.com/rubygems/gemstash/llms.txt

Configure Bundler credentials globally or use an environment variable to authenticate with Gemstash when fetching private gems. Embedding credentials in the Gemfile is not recommended for version control.

```bash
# Configure Bundler credentials globally
bundle config my-gemstash.example.com e374e237fdf5fa5718d2a21bd63dc911

# Or use environment variable (recommended)
export BUNDLE_MYGEMSTASH__EXAMPLE__COM=e374e237fdf5fa5718d2a21bd63dc911
bundle install
```

```ruby
# Or embed credentials in Gemfile (not recommended for version control)
source "http://e374e237fdf5fa5718d2a21bd63dc911@localhost:9292/private" do
  gem "my-private-gem"
end
```

--------------------------------

### Specify Gemstash Config File

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-setup.1.md

To use a configuration file at a custom location, provide the --config-file option followed by the desired file path. Remember to use this option for all subsequent Gemstash commands.

```bash
gemstash setup --config-file <file>
```

--------------------------------

### ERB Parsed Config with Environment Variables

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-customize.7.md

Create a `~/.gemstash/config.yml.erb` file to use ERB for dynamic configuration, allowing environment variables to be used for settings like database URLs.

```yaml
# ~/.gemstash/config.yml.erb
---
:db_adapter: postgres
:db_url: <%= ENV["DATABASE_URL"] %>
```

--------------------------------

### Configure Memcached Server

Source: https://github.com/rubygems/gemstash/blob/main/man/gemstash-customize.7.md

Use Memcached by setting `:cache_type` to `memcached` and listing servers in `:memcached_servers`. Configure expiration time with `:cache_expiration`.

```yaml
# ~/.gemstash/config.yml
---
:cache_type: memcached
:memcached_servers: memcached1.local:11211,memcached2.local:11211
:cache_expiration: 1800

```

--------------------------------

### Bundle with Multiple Gem Sources in Gemfile

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-multiple-sources.7.md

Specify multiple gem sources in your Gemfile, using the /upstream prefix for additional sources. Use CGI.escape for URLs containing special characters or authentication details.

```ruby
require "cgi"
source "http://localhost:9292"
gem "rubywarrior"

source "http://localhost:9292/upstream/#{CGI.escape("https://my.gem-source.local")}" do
  gem "my-gem"
end

source "http://localhost:9292/upstream/my-other.gem-source.local" do
  gem "my-other-gem"
end
```

--------------------------------

### Configure Global API Key

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-private-gems.7.md

Add API key credentials globally for your Gemstash source using the bundle config command. This method avoids committing sensitive information directly into your Gemfile.

```bash
$ bundle config my-gemstash.dev api_key
```

--------------------------------

### Configure PostgreSQL Database in Gemstash

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-customize.7.md

Set `:db_adapter` to `postgres` and provide the `:db_url` in `~/.gemstash/config.yml` for PostgreSQL connections. Includes optional Sequel connection options.

```yaml
# ~/.gemstash/config.yml
---
:db_adapter: postgres
:db_url: postgres:///gemstash
:db_connection_options: # Sequel.connect options
  :connect_timeout: 10
  :read_timeout: 5
  :timeout: 30
```

--------------------------------

### Systemd Service Configuration for Gemstash

Source: https://context7.com/rubygems/gemstash/llms.txt

Configure Gemstash to run as a systemd service. Ensure the user and group exist and the working directory is set correctly. The environment variable GEMSTASH_CONFIG points to the configuration file.

```ini
# /etc/systemd/system/gemstash.service
[Unit]
Description=Gemstash gem server
After=network.target

[Service]
Type=simple
User=gemstash
Group=gemstash
WorkingDirectory=/var/gemstash
Environment=GEMSTASH_CONFIG=/etc/gemstash/config.yml
ExecStart=/usr/local/bin/gemstash start
ExecStop=/usr/local/bin/gemstash stop
Restart=on-failure

[Install]
WantedBy=multi-user.target
```

--------------------------------

### Push Private Gem to Gemstash

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-private-gems.7.md

Pushes a built gem to the Gemstash server. The `--host` option must include `/private` to target the private gem repository.

```bash
$ gem push --key test_key --host http://localhost:9292/private pkg/private-example-0.1.0.gem
```

--------------------------------

### Specify Gemstash Configuration File

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-authorize.1.md

If you are not using the default Gemstash configuration file location, specify the path to your config file using the --config-file option.

```bash
gemstash --config-file FILE
```

--------------------------------

### Configure Bundler to Use Gemstash as Mirror

Source: https://context7.com/rubygems/gemstash/llms.txt

Configures Bundler to use Gemstash as a mirror for `rubygems.org`, enabling caching of gem requests. Includes setting a fallback timeout.

```bash
# Configure mirror for rubygems.org
bundle config mirror.https://rubygems.org http://localhost:9292

# Configure fallback timeout (seconds) if Gemstash is unavailable
bundle config mirror.https://rubygems.org.fallback_timeout 3
```

--------------------------------

### Gemfile with Gemstash Sources

Source: https://context7.com/rubygems/gemstash/llms.txt

Configure your Gemfile to use Gemstash as the default source, which proxies to rubygems.org. Private gems can be sourced from a specific path.

```ruby
# ./Gemfile

# Use Gemstash as the default source (proxies to rubygems.org)
source "http://localhost:9292"
gem "rails"
gem "puma"

# Private gems require the /private path
source "http://localhost:9292/private" do
  gem "my-private-gem"
end
```

--------------------------------

### Gemfile with Environment Variable Authentication

Source: https://github.com/rubygems/gemstash/blob/main/man/gemstash-multiple-sources.7.md

Configure your Gemfile to use a gem source without embedded credentials, relying instead on environment variables for authentication. The ENV variable name follows a specific format.

```ruby
# ./Gemfile
source "http://localhost:9292"

source "http://localhost:9292/upstream/my.gem-source.local" do
  gem "my-gem"
end
```

--------------------------------

### Download Gems from Gemstash

Source: https://context7.com/rubygems/gemstash/llms.txt

Download gem files directly from Gemstash. This includes cached gems and private gems, with authentication support if `protected_fetch` is enabled.

```bash
# Download a cached gem
curl http://localhost:9292/gems/rails-7.0.0.gem -o rails-7.0.0.gem

# Download a private gem (with auth if protected_fetch enabled)
curl -u "e374e237fdf5fa5718d2a21bd63dc911:"
  http://localhost:9292/private/gems/my-gem-1.0.0.gem -o my-gem-1.0.0.gem
```

--------------------------------

### Gem Specs Endpoints

Source: https://context7.com/rubygems/gemstash/llms.txt

Access gem specification indexes, including all specs, latest specs, prerelease specs, and individual gem information.

```APIDOC
## GET /specs.4.8.gz

### Description
Retrieves all gem specifications in a gzipped format.

### Endpoint
`/specs.4.8.gz`

### Request Example
```bash
curl http://localhost:9292/specs.4.8.gz -o specs.4.8.gz
```

## GET /latest_specs.4.8.gz

### Description
Retrieves the latest gem specifications in a gzipped format.

### Endpoint
`/latest_specs.4.8.gz`

### Request Example
```bash
curl http://localhost:9292/latest_specs.4.8.gz -o latest_specs.4.8.gz
```

## GET /prerelease_specs.4.8.gz

### Description
Retrieves prerelease gem specifications in a gzipped format.

### Endpoint
`/prerelease_specs.4.8.gz`

### Request Example
```bash
curl http://localhost:9292/prerelease_specs.4.8.gz -o prerelease_specs.4.8.gz
```

## GET /info/[gem_name]

### Description
Retrieves information about a specific gem.

### Endpoint
`/info/[gem_name]`

### Request Example
```bash
curl http://localhost:9292/info/rails
```

## GET /names

### Description
Retrieves a list of all available gem names.

### Endpoint
`/names`

### Request Example
```bash
curl http://localhost:9292/names
```
```

--------------------------------

### Configure Bundler to Use Gemstash

Source: https://github.com/rubygems/gemstash/blob/main/README.md

Configure Bundler to use Gemstash as a mirror for RubyGems.org. This tells Bundler to fetch gems from your local Gemstash server first.

```bash
bundle config mirror.https://rubygems.org http://localhost:9292
```

--------------------------------

### Enable Protected Fetch for Private Gems

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-customize.7.md

Set the `:protected_fetch` configuration key to `true` in `~/.gemstash/config.yml` to enable authenticated access for private gems.

```yaml
# ~/.gemstash/config.yml
---
:protected_fetch: true
```

--------------------------------

### Manage Gemstash API Keys

Source: https://context7.com/rubygems/gemstash/llms.txt

Manages API keys for private gem operations, including creation, updating, removal, and listing. Keys can have specific permissions like `push`, `yank`, and `fetch`.

```bash
# Create a new key with all permissions
gemstash authorize
# Output: Your new key is: e374e237fdf5fa5718d2a21bd63dc911
```

```bash
gemstash authorize push yank
```

```bash
gemstash authorize push --name deploy-key
```

```bash
gemstash authorize push yank --key e374e237fdf5fa5718d2a21bd63dc911
```

```bash
gemstash authorize --remove --key e374e237fdf5fa5718d2a21bd63dc911
```

```bash
gemstash authorize --list
```

--------------------------------

### Display Gemstash Version

Source: https://context7.com/rubygems/gemstash/llms.txt

Shows the current Gemstash version. Can be invoked using `version`, `-v`, or `--version` flags.

```bash
gemstash version
# Output: Gemstash version 2.7.1
```

```bash
gemstash -v
```

```bash
gemstash --version
```

--------------------------------

### Specify Custom Config File Location

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-customize.7.md

Use the `--config-file` option with Gemstash commands to specify an alternative location for the configuration file. This is useful for managing different configurations or when the default `~/.gemstash/config.yml` is not suitable.

```bash
$ gemstash setup --config-file ./gemstash-config.yml
```

```bash
$ gemstash authorize --config-file ./gemstash-config.yml
```

```bash
$ gemstash start --config-file ./gemstash-config.yml
```

```bash
$ gemstash stop --config-file ./gemstash-config.yml
```

```bash
$ gemstash status --config-file ./gemstash-config.yml
```

--------------------------------

### Configure Server Bind Address

Source: https://github.com/rubygems/gemstash/blob/main/man/gemstash-customize.7.md

Change the server binding address and port by setting the `:bind` key in `~/.gemstash/config.yml`. This corresponds to the Puma bind flag.

```yaml
# ~/.gemstash/config.yml
---
:bind: tcp://0.0.0.0:4242

```

--------------------------------

### Push Gems via API

Source: https://context7.com/rubygems/gemstash/llms.txt

Programmatically push gems to your Gemstash private repository using the HTTP API.

```APIDOC
## POST /private/api/v1/gems

### Description
Pushes a gem file to the private repository.

### Endpoint
`/private/api/v1/gems`

### Headers
- **Authorization** (string) - Required - The API key for authentication.

### Request Body
- The gem file content should be sent as binary data.

### Request Example
```bash
curl -X POST \
  -H "Authorization: e374e237fdf5fa5718d2a21bd63dc911" \
  --data-binary @my-gem-1.0.0.gem \
  http://localhost:9292/private/api/v1/gems
```
```

--------------------------------

### Configure Default Gemstash Source

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-multiple-sources.7.md

Edit the Gemstash configuration file to change the default gem source URL. Remember to restart the Gemstash server after making changes.

```yaml
---
:rubygems_url: https://my.gem-source.local
```

--------------------------------

### List Gemstash Authorizations

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-authorize.1.md

View existing authorizations using the --list flag. You can filter the list by providing a --name or --key.

```bash
gemstash authorize --list
```

--------------------------------

### Gem Dependencies API

Source: https://context7.com/rubygems/gemstash/llms.txt

Retrieve gem dependency information, primarily used by Bundler to resolve gem versions.

```APIDOC
## GET /api/v1/dependencies

### Description
Queries gem dependencies for specified gems.

### Endpoint
`/api/v1/dependencies`

### Query Parameters
- **gems** (string) - Required - A comma-separated list of gem names to get dependencies for.

### Request Example
```bash
curl "http://localhost:9292/api/v1/dependencies?gems=rails,puma"
```

### Response
#### Success Response (200)
- The response format depends on the requested format (e.g., JSON or default).

#### Response Example (JSON)
```json
{
  "rails": [
    { "name": "actionmailer", "requirements": ">= 7.0.0" },
    { "name": "actionpack", "requirements": ">= 7.0.0" }
  ],
  "puma": [
    { "name": "async", "requirements": "~> 2.0" }
  ]
}
```
```

--------------------------------

### Configure Gemstash Bind Address

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-customize.7.md

Update the `:bind` configuration key in `~/.gemstash/config.yml` to change the network interface and port Gemstash listens on. This value corresponds to the Puma bind flag.

```yaml
# ~/.gemstash/config.yml
---
:bind: tcp://0.0.0.0:4242
```

--------------------------------

### Download Gems

Source: https://context7.com/rubygems/gemstash/llms.txt

Directly download gem files from Gemstash, including cached gems and private gems (with authentication if enabled).

```APIDOC
## GET /gems/[gem_file_name]

### Description
Downloads a cached gem file.

### Endpoint
`/gems/[gem_file_name]`

### Request Example
```bash
curl http://localhost:9292/gems/rails-7.0.0.gem -o rails-7.0.0.gem
```

## GET /private/gems/[gem_file_name]

### Description
Downloads a private gem file. Requires authentication if `protected_fetch` is enabled in configuration.

### Endpoint
`/private/gems/[gem_file_name]`

### Request Example (with authentication)
```bash
curl -u "e374e237fdf5fa5718d2a21bd63dc911:" \
  http://localhost:9292/private/gems/my-gem-1.0.0.gem -o my-gem-1.0.0.gem
```
```

--------------------------------

### Configure Memory Cache Settings

Source: https://github.com/rubygems/gemstash/blob/main/man/gemstash-customize.7.md

Customize the memory cache by setting `:cache_type` to `memory` and adjusting `:cache_max_size` in `~/.gemstash/config.yml`. The default `cache_max_size` is 500.

```yaml
# ~/.gemstash/config.yml
---
:cache_type: memory
:cache_max_size: 2000

```

--------------------------------

### Gemfile with Multiple Upstream Sources

Source: https://context7.com/rubygems/gemstash/llms.txt

Configure your Gemfile to use Gemstash to cache gems from multiple upstream gem servers, including those with URL encoding and authentication.

```ruby
# ./Gemfile
require "cgi"

# Default source (proxies to configured rubygems_url)
source "http://localhost:9292"
gem "rails"

# Additional upstream with full URL encoding
source "http://localhost:9292/upstream/#{CGI.escape("https://my.gem-source.local")}" do
  gem "internal-gem"
end

# Upstream without scheme (https:// assumed)
source "http://localhost:9292/upstream/gems.example.com" do
  gem "another-gem"
end

# Authenticated upstream source
source "http://localhost:9292/upstream/#{CGI.escape("user:password@private.gems.local")}" do
  gem "secure-gem"
end
```

--------------------------------

### Check Gemstash Server Status

Source: https://github.com/rubygems/gemstash/blob/main/docs/gemstash-debugging.7.md

Use this command to check the current status of the Gemstash server. This command passes through to pumactl for status checking.

```bash
gemstash status
```