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.3.2)

Released: 2026-04-15

RailsPress 1.3.2 focuses on host route-constraint guidance for API onboarding and bearer-token access.

• Updated configuration, API authentication, and troubleshooting docs for apps that mount RailsPress behind admin route constraints.
• Added explicit guidance to allow /railspress/api/* through host constraints so requests reach RailsPress auth.
• Added concrete AdminConstraint diagnostics for resolving 404 API responses before bearer-token auth runs.

Review full patch notes in the CHANGELOG.

Version-Specific Notes

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