Configuration

Configure authors, post images, authentication, and other RailsPress options.

Basic Setup

Running rails generate railspress:install creates an initializer at config/initializers/railspress.rb. Every feature ships disabled, so the generated file is a menu of commented-out toggles: uncomment the ones you want. The blog features section surfaces author tracking, header images, and focal points:

Railspress.configure do |config|
  # === Blog Features (always available) ===

  # Author tracking for posts and content elements.
  # Uncomment to enable:
  # config.enable_authors
  # config.author_class_name = "User"
  # config.author_scope = :admins
  # config.current_author_method = :current_user
  # config.current_author_proc = -> { Current.user }

  # Header images for Posts
  # Uncomment to enable:
  # config.enable_post_images
  # config.enable_focal_points
end

The generated file continues with commented sections for CMS content elements (enable_cms), inline editing, and the JSON API (enable_api). Each block is documented inline and covered in its own section below.

Feature Toggles

enable_authors

Enables author/user association for posts. When enabled, posts can be assigned to authors and the author dropdown appears in the post form.

Railspress.configure do |config|
  config.enable_authors
end

Default: Disabled

enable_post_images

Enables post image uploads for posts. When enabled, posts can have a featured/header image attached via Active Storage.

Railspress.configure do |config|
  config.enable_post_images
end

Default: Disabled

post_image_variants

Declares named Active Storage variants for the post header_image, so views can request @post.header_image.variant(:hero) instead of repeating transformation options. Each variant is registered with format: :webp automatically.

Railspress.configure do |config|
  config.enable_post_images

  config.post_image_variants = {
    hero:  { resize_to_fill: [1920, 1080] },
    card:  { resize_to_fill: [800, 600] },
    thumb: { resize_to_fill: [400, 400] },
    og:    { resize_to_limit: [1200, 630] }
  }
end

The hash keys become variant names; the values are passed straight through to Active Storage, so any transformation it accepts works here.

<%= image_tag @post.header_image.variant(:hero), alt: @post.title %>

Default: {} (no named variants; inline variant(resize_to_limit: [...]) calls still work)

Variants require an image processor. See Active Storage & Image Variants for the gem and native library setup, and Displaying the Header Image for view examples.

enable_focal_points

Enables focal point selection for header images. When enabled, editors can set the focal point (important area) of images to control cropping across different aspect ratios.

Railspress.configure do |config|
  config.enable_post_images    # Required first
  config.enable_focal_points   # Then enable focal points
end

Default: Disabled

Requirements: Must also enable enable_post_images. Requires running migrations for the railspress_focal_points table.

See Image Focal Point System for full documentation including image contexts, per-context overrides, and view helpers.

enable_cms

Enables Blocks -- the copy and images on your site itself (headlines, blurbs, CTAs, hero images). When enabled, you get Content Groups and Content Elements models, admin UI sidebar links, dashboard stats, the cms_element and cms_value view helpers, and the chainable Railspress::CMS API.

Railspress.configure do |config|
  config.enable_cms
end

Default: Disabled

When CMS is disabled, calling cms_element or cms_value in a view raises Railspress::ConfigurationError. CMS routes are not mounted and CMS links do not appear in the admin sidebar.

Inline editing builds on top of CMS. See Inline Editing for how to enable right-click editing of CMS content on public pages.

enable_api

Enables the versioned JSON API and the Agents & API admin screens for key management.

Railspress.configure do |config|
  config.enable_api
end

Default: Disabled

When enabled, API endpoints are available under /railspress/api/v1, and key lifecycle management is available at /railspress/admin/api_keys.

Requirements: API key and bootstrap key secret material is stored with Active Record Encryption. Configure encryption keys in your host app:

Rails.application.config.active_record.encryption.primary_key = ENV.fetch("ACTIVE_RECORD_ENCRYPTION_PRIMARY_KEY")
Rails.application.config.active_record.encryption.deterministic_key = ENV.fetch("ACTIVE_RECORD_ENCRYPTION_DETERMINISTIC_KEY")
Rails.application.config.active_record.encryption.key_derivation_salt = ENV.fetch("ACTIVE_RECORD_ENCRYPTION_KEY_DERIVATION_SALT")

blog_path

The public URL path where your blog posts are displayed on your site. Used to generate "View" links in the admin interface that link to the live post on your frontend.

config.blog_path = "/blog"       # default
config.blog_path = "/articles"   # custom path
config.blog_path = "/news"       # news section

Default: "/blog"

The admin post show page displays a "View" button for published posts that links to #{blog_path}/#{post.slug}.

words_per_minute

Words per minute used for calculating estimated reading time on posts.

config.words_per_minute = 200    # default
config.words_per_minute = 250    # faster readers
config.words_per_minute = 150    # more technical content

Default: 200

inline_editing_check

A proc that determines whether inline editing controls are shown to the current user. Receives the view helper context.

config.inline_editing_check = ->(context) {
  context.controller.current_user&.admin?
}

Default: nil (inline editing disabled)

Requires: enable_cms must be set. Without it, setting this option raises Railspress::ConfigurationError.

Accessing Configuration Programmatically

Railspress.authors_enabled?        # => true/false
Railspress.post_images_enabled?    # => true/false
Railspress.focal_points_enabled?   # => true/false
Railspress.cms_enabled?            # => true/false
Railspress.api_enabled?            # => true/false
Railspress.author_class            # => User (the actual class)
Railspress.available_authors       # => ActiveRecord::Relation
Railspress.author_display_method   # => :name
Railspress.current_author_method   # => :current_user
Railspress.current_api_actor_method # => :current_user
Railspress.blog_path               # => "/blog"
Railspress.words_per_minute        # => 200

Active Storage & Image Variants

Header images use Active Storage. If your app does not already have it, install it and run the migration:

$ bin/rails active_storage:install
$ bin/rails db:migrate

Configure your storage service in config/storage.yml and set config.active_storage.service in your environment files.

Image variants

When your application uses resized header images or passes a variant: option to rp_featured_image_url, Active Storage also needs an image-processing backend. RailsPress supplies image_processing >= 2.0.3 as a runtime dependency; the host application chooses and installs the processor gem and its native library. Choose one processor:

# Recommended for Rails 8.1.3.1+ applications
gem "ruby-vips", "~> 2.2", ">= 2.2.1"

# Or use ImageMagick instead
# gem "mini_magick", "~> 5.0"

Install the matching system package in development, test, and production: libvips 8.13+ for ruby-vips, or ImageMagick for mini_magick. Rails selects a processor from your application defaults; set it explicitly when needed:

config.active_storage.variant_processor = :vips       # libvips
# config.active_storage.variant_processor = :mini_magick # ImageMagick

Header images can be displayed without variants; this setup is only required when your application requests resizing or format conversion. If variants fail to generate, see Troubleshooting.

Author Configuration

These options are only relevant when enable_authors is called.

author_class_name

The class name of your user/author model as a string.

config.author_class_name = "User"        # default
config.author_class_name = "Admin"       # custom model
config.author_class_name = "Author"      # dedicated author model

current_author_method

The controller method that returns the currently signed-in user. This integrates with your authentication system (Devise, Clearance, custom auth, etc.).

config.current_author_method = :current_user   # default (Devise)
config.current_author_method = :current_admin  # admin-specific
config.current_author_method = :logged_in_user # custom auth

author_scope

Limits which users appear in the author dropdown. Accepts a Symbol (scope name) or a Proc.

# Use a scope defined on the User model
config.author_scope = :authors           # calls User.authors
config.author_scope = :active            # calls User.active

# Use a Proc for complex logic
config.author_scope = ->(klass) { klass.where(role: "writer") }

author_display_method

The method called on author objects to display their name in dropdowns and post listings.

config.author_display_method = :name       # default
config.author_display_method = :full_name
config.author_display_method = :email
config.author_display_method = :display_name

current_api_actor_method

When API is enabled, this method identifies the signed-in actor allowed to create, rotate, and revoke keys.

config.current_api_actor_method = :current_user   # default
config.current_api_actor_method = :current_admin  # admin-only auth

current_api_actor_proc

Use this proc instead of current_api_actor_method when your app resolves identity via request-scoped objects such as Current.

config.current_api_actor_proc = -> { Current.user }

public_base_url

Optional canonical host used when RailsPress generates API and agent instruction snippets in admin.

config.public_base_url = "https://blog.example.com"

If public_base_url is not set, RailsPress resolves the instruction host from Rails.application.routes.default_url_options and then falls back to the current request host.

Example Configurations

Minimal Setup (No Authors)

Railspress.configure do |config|
  config.enable_post_images
end

With Devise Authentication

Railspress.configure do |config|
  config.enable_authors
  config.enable_post_images
  config.author_class_name = "User"
  config.current_author_method = :current_user
  config.author_display_method = :email
end

With API + Agent Access

Railspress.configure do |config|
  config.enable_authors
  config.enable_post_images
  config.enable_api
  config.current_author_method = :current_user
  config.current_api_actor_method = :current_user
  config.public_base_url = "https://blog.example.com"
end

With Scoped Authors

class User < ApplicationRecord
  scope :writers, -> { where(role: %w[writer editor admin]) }

  def display_name
    "#{first_name} #{last_name}"
  end
end

Railspress.configure do |config|
  config.enable_authors
  config.author_class_name = "User"
  config.author_scope = :writers
  config.author_display_method = :display_name
end

Adding Authentication

RailsPress does not include authentication. Protect the admin area by configuring your application controller:

class ApplicationController < ActionController::Base
  # If using Devise
  before_action :authenticate_user!, if: :railspress_admin?

  private

  def railspress_admin?
    request.path.start_with?("/railspress/admin")
  end
end

Or override the RailsPress base controller:

Rails.application.config.to_prepare do
  Railspress::Admin::BaseController.class_eval do
    before_action :authenticate_user!
    before_action :require_admin!

    private

    def require_admin!
      redirect_to root_path unless current_user&.admin?
    end
  end
end