Upgrading RailsPress

Guide for upgrading the RailsPress engine between versions.

Quick Upgrade

# 1. Update the gem
$ bundle update railspress-engine

# 2. Copy new migrations
$ rails railspress:install:migrations

# 3. Run migrations
$ rails db:migrate

# 4. Restart your server

Step-by-Step Guide

1. Update the Gem

If using a version constraint in your Gemfile:

gem "railspress-engine", "~> 1.0"

Run:

$ bundle update railspress-engine

If using a git source:

gem "railspress-engine", git: "https://github.com/aviflombaum/railspress-engine", branch: "main"

2. Copy New Migrations

RailsPress includes a rake task to copy engine migrations to your application:

$ rails railspress:install:migrations

This copies any new migrations from the engine to your db/migrate/ folder. Existing migrations are skipped (matched by migration name, not timestamp).

Check what was copied:

$ ls -la db/migrate/*railspress*

3. Review Migration Changes

Before running migrations, review them for any data implications:

# See pending migrations
$ rails db:migrate:status

# Preview a specific migration
$ cat db/migrate/TIMESTAMP_create_railspress_exports.rb

4. Run Migrations

$ rails db:migrate

For production, consider running migrations separately from deployment:

$ RAILS_ENV=production rails db:migrate

5. Check Configuration

New versions may add configuration options. Review the initializer:

Railspress.configure do |config|
  config.enable_authors
  config.author_class_name = "User"
  config.author_display_method = :name

  config.enable_post_images
end

Check the Configuration guide for new options.

6. Restart Application

# Development
$ rails restart

# Production (example with Puma)
$ pumactl restart

Migration Internals

How Engine Migrations Work

RailsPress migrations live in railspress/db/migrate/. When you run railspress:install:migrations, Rails copies them to your app with new timestamps.

Engine migration:

railspress/db/migrate/20241218000001_create_railspress_categories.rb

Becomes in your app:

db/migrate/20241224123456_create_railspress_categories.railspress.rb

The .railspress suffix tracks the migration origin.

Migration Naming Convention

RailsPress uses a fixed timestamp prefix pattern:

New migrations increment the suffix (000007, 000008, etc.).

Checking Migration Status

# See all migrations and their status
$ rails db:migrate:status

# Filter to RailsPress migrations
$ rails db:migrate:status | grep railspress

Rolling Back

If needed, rollback a specific migration:

# Rollback last migration
$ rails db:rollback

# Rollback to specific version
$ rails db:migrate:down VERSION=20241224123456

Troubleshooting

"Migration already exists"

If the rake task reports migrations already exist, they've been copied before. Check:

$ ls db/migrate/*railspress*

Schema Mismatch

If your schema differs from expected migrations:

# Check current schema
$ rails db:schema:dump
$ cat db/schema.rb | grep railspress

# Compare with engine migrations
$ ls railspress/db/migrate/

Missing Tables

If RailsPress tables are missing:

# Re-copy all migrations
$ rails railspress:install:migrations

# Run pending
$ rails db:migrate

Duplicate Migrations

If you have duplicate migrations (same content, different timestamps):

1. Check which are already run: rails db:migrate:status
2. Delete the unrun duplicate
3. If both are run, the second likely failed silently

Latest Release Notes (v1.4.1)

Released: 2026-07-15

RailsPress 1.4.1 is a documentation and installer refinement release. It clarifies how to set up Active Storage image variants and surfaces the opt-in author, post-image, and focal-point settings in the generated initializer. It requires no migrations, configuration changes, or host importmap changes: just update the gem and restart.

• Installer configuration guidance: the generated RailsPress initializer now surfaces author_scope and the opt-in post-image and focal-point settings as commented examples, so the available toggles are visible right after install.
• Active Storage variant setup documentation: the installation, configuration, and troubleshooting guides now explain the required image_processing gem, processor gem, native dependency, and optional processor selection for resized or converted images.
• CI action maintenance: updated GitHub Actions checkout and cache actions to their current major versions.

See the v1.4.1 release notes or the full CHANGELOG.

Version-Specific Notes

Upgrading to 1.4.1 (from 1.4.0)

RailsPress 1.4.1 refines installer guidance and documentation only. There are no migrations, configuration, or host importmap changes.

$ bundle update railspress-engine

Your existing config/initializers/railspress.rb is untouched by the upgrade. If you want the newly surfaced commented settings (author_scope, enable_post_images, enable_focal_points) as a reference, compare against a freshly generated initializer or see Basic Setup. If your app requests resized or converted images, review Active Storage & Image Variants to confirm an image processor is installed.

Upgrading to 1.4.0 (from 1.3.x)

RailsPress 1.4.0 adopts Lexxy's first stable release (0.9.24) and refreshes its dependency set. There are no migrations or host importmap changes.

$ bundle update railspress-engine lexxy

Keep import "railspress" in your host JavaScript entrypoint if you use host-page RailsPress features such as inline editing. No other changes are required.

Upgrading to 1.3.0

This release adds the versioned JSON API and AI-agent onboarding flow, plus new admin key management screens.

Key additions:

• /railspress/api/v1 endpoints for posts, post imports, categories, tags, and prime handshake.
• Agent bootstrap token exchange flow (rpb_* to rp_*).
• Agents & API admin screen at /railspress/admin/api_keys.
• Two new encrypted key tables: railspress_api_keys and railspress_agent_bootstrap_keys.

Upgrade checklist:

$ bundle update railspress-engine
$ rails railspress:install:migrations
$ rails db:migrate

Required API setup:

1. Configure Active Record Encryption keys in your host app.
2. Enable API in config/initializers/railspress.rb with config.enable_api.
3. Set an API actor method/proc (for example config.current_api_actor_method = :current_user).
4. Create a bootstrap or direct API key from /railspress/admin/api_keys.

Upgrading to 1.2.0 (from 1.0.0+)

This release improved Lexxy dependency and importmap behavior for host apps.

• Lexxy dependency moved to an open lower bound (>= 0.9.0.beta).
• Engine-managed importmap and JS entrypoint now handle Lexxy loading.
• Install generator no longer adds a manual host lexxy importmap pin.
• Inline editor rendering and rubyzip compatibility fixes were included.

$ bundle update railspress-engine lexxy
$ rails railspress:install:migrations
$ rails db:migrate

Upgrading to 1.0.0

New: Blocks (Content Element CMS), Inline Editing, and content transfer

New configuration:

Railspress.configure do |config|
  config.enable_cms
  config.inline_editing_check = ->(ctx) { ctx.controller.current_user&.admin? }
end

Upgrading to 0.1.x

Initial release. Run full install:

$ rails generate railspress:install
$ rails db:migrate

CI/CD Considerations

Automated Upgrades

In CI, ensure migrations run before tests:

- name: Setup database
  run: |
    rails railspress:install:migrations
    rails db:create db:migrate

Production Deployments

For zero-downtime deploys, run migrations before deploying new code if they're additive (new tables, new columns with defaults).

For destructive migrations (removing columns), deploy code first, then migrate.

# Typical deploy sequence
$ git pull origin main
$ bundle install
$ rails railspress:install:migrations
$ rails db:migrate
$ rails assets:precompile
# restart app

Getting Help

• Check the Configuration guide for configuration options
• Check the Import & Export guide for import/export features
• Review engine source: bundle show railspress