Configuring Gemfast

This document covers the configuration options of Gemfast in depth.

Table of Contents

File Locations

Gemfast has a few different configuration files that it uses. The locations for these files are:

  • The service configuration file: /etc/gemfast/gemfast.hcl
  • The ACL configuration file: /opt/gemfast/etc/gemfast/gemfast_acl.csv
  • The casbin auth_model configuration file: /opt/gemfast/etc/gemfast/auth_model.conf

Most users will only need to interact with the service configuration file.

Configuration

Server

Gemfast server configuration.

Name Description Default
license_key License key purchased from gemfast.io nil
port Port the gemfast server listens on 2020
log_level Log level for the gemfast server info
dir Base directory for gemfast data /var/gemfast
gem_dir Directory where gems are stored /var/gemfast/gems
db_dir Directory where the database file is stored /var/gemfast/db
acl_path Path to the acl configuration file /opt/gemfast/etc/gemfast/gemfast_acl.csv
auth_model_path Path to the auth_model configuration file /opt/gemfast/etc/gemfast/auth_model.conf
private_gems_namespace The namespace where private gems will be accessed private
ui_disabled Disable the Gemfast UI false
metrics_disabled Disable Gemfast prometheus metrics false

Configured in /etc/gemfast/gemfast.hcl

license_key            = ""
port                   = 2020
log_level              = "info|trace|debug|warn"
dir                    = "/var/gemfast"
gem_dir                = "/var/gemfast/gems"
db_dir                 = "/var/gemfast/db"
acl_path               = "/opt/gemfast/etc/gemfast/gemfast_acl.csv"
auth_model_path        = "/opt/gemfast/etc/gemfast/auth_model.conf"
private_gems_namespace = "private"
ui_disabled            = false
metrics_disabled       = false

Caddy

Caddy configuration is only applicable to Gemfast .deb packages. The Gemfast Docker image does not include Caddy.

Name Description Default
port Port caddy will listen on 443
host The hostname for the gemfast service https://localhost
metrics_disabled Disable caddy metrics false
admin_api_enabled Enable the caddy admin API false

Configured in /etc/gemfast/gemfast.hcl

caddy {
  port              = 443
  host              = "https://localhost"
  metrics_disabled  = false
  admin_api_enabled = false
}

Mirror

Mirror configuration enables a gem mirror upstream that downloads and caches gems from an upstream rubygems server.

Name Description Default
enabled Enable or disabled mirroing true
upstream The upstream server to mirror https://rubygems.org

Configured in /etc/gemfast/gemfast.hcl

mirror {
  enabled  = true
  upstream = "https://rubygems.org"
}

Auth

Gemfast currently supports three authentication strategies, none, local, and github.

None

auth "none" {}

Local

Name Description Default
bcrypt_cost Controls the bcrypt cost when hashing passwords 10
allow_anonymous_read Enable unauthenticated users to install private gems false
secret_key Use a predetermined JWT Secret instead of a generated one ""
secret_key_path Path where the JWT Secret is stored "/opt/gemfast/etc/gemfast/.jwt_secret_key"
admin_password Use a predetermined admin instead of a generated one ""
default_user_role The default role for a user if one is not specified "read"
auth "local" {
  bcrypt_cost          = 10
  allow_anonymous_read = false
  secret_key           = "" # generated by default
  secret_key_path      = "/opt/gemfast/etc/gemfast/.jwt_secret_key"
  admin_password       = "" # generated by default
  default_user_role    = "read|write|admin"
  user {
    username           = ""
    password           = ""
    role               = "read"
  }
}

Local

Name Description Default
allow_anonymous_read Enable unauthenticated users to install private gems false
secret_key Use a predetermined JWT Secret instead of a generated one ""
secret_key_path Path where the JWT Secret is stored "/opt/gemfast/etc/gemfast/.jwt_secret_key"
default_user_role The default role for a user if one is not specified "read"
github_client_id GitHub client ID from the registered GitHub App ""
github_client_secret GitHub client secret from the registered GitHub App ""
github_user_orgs The GitHub organization(s) a user must be a member of ""
auth "github" {
  allow_anonymous_read = false
  secret_key           = "" # generated by default
  secret_key_path      = "/opt/gemfast/etc/gemfast/.jwt_secret_key"
  default_user_role    = "read|write|admin"
  github_client_id     = ""
  github_client_secret = ""
  github_user_orgs     = ""
}

Filter

Filter configuration enables the ability to allow-list or deny-list gems from being uploaded to or downloaded by the Gemfast server. It works by matching an array of regular expressions against the name of a .gem file.

Name Description Default
enabled Enable or disabled gem filtering true
action The action to take when a regex is matched. Values: allow | deny deny
regex Array of regular expressions to match against a gem name []

Configured in /etc/gemfast/gemfast.hcl

filter {
  enabled = false
  action  = "deny"
  regex   = []
}

CVE

CVE settings enable the ability to block gems from being downloaded or uploaded if they have a registered CVE of a certain severity. The CVE database used is stored on disk as a git repository and updated automatically in the background by the Gemfast service.

Name Description Default
enabled Enable or disabled gem filtering based on CVE severity true
max_severity The action to take when a regex is matched. Values: low | medium | high high
ruby_advisory_db_dir Directory where the ruby advisory db is stored /opt/gemfast/share/gemfast

Configured in /etc/gemfast/gemfast.hcl

cve {
  enabled              = false
  max_severity         = "high"
  ruby_advisory_db_dir = "/opt/gemfast/share/gemfast"
}

Basic Setup
Deploying Gemfast