RailsAdmin Deployment & Usage Guide

Prerequisites

Before installing RailsAdmin, ensure you have:

Ruby 2.6, 2.7, 3.0, 3.1, 3.2, or JRuby
Rails application (6.0+ recommended for Webpacker support)
Bundler (gem install bundler)
Database: PostgreSQL, MySQL, or SQLite (ActiveRecord) or MongoDB (Mongoid)
Node.js and Yarn (required for Webpacker asset pipeline)
Git

Installation

RailsAdmin is installed as a gem within your existing Rails application.

1. Add to Gemfile

gem 'rails_admin', '~> 3.0'

For Mongoid support, also include:

gem 'mongoid'
gem 'kaminari-mongoid'

2. Install Dependencies

bundle install

3. Run Installation Generator

rails g rails_admin:install

When prompted, provide a namespace for the admin routes (default: admin). This creates:

config/initializers/rails_admin.rb (global configuration)
Route entry in config/routes.rb

4. Asset Pipeline Configuration

For Webpacker/Webpack (Rails 6+ default): The generator will suggest required changes based on your current setup. Ensure you have required npm packages:

yarn add rails_admin

For Sprockets (legacy): Add to app/assets/javascripts/application.js:

//= require rails_admin

5. Database Setup

If using PaperTrail for audit history:

rails generate paper_trail:install
rails db:migrate

Configuration

Global Configuration

Edit config/initializers/rails_admin.rb:

RailsAdmin.config do |config|
  # Application title
  config.main_app_name = ['My App', 'Admin']
  
  # Models to include/exclude
  config.included_models = ['User', 'Post', 'Comment']
  config.excluded_models = ['SecretModel']
  
  # Pagination
  config.default_items_per_page = 20
  
  # Authentication (example with Devise)
  config.authenticate_with do
    warden.authenticate! scope: :user
  end
  
  config.current_user_method(&:current_user)
  
  # Authorization (example with CanCanCan)
  config.authorize_with :cancancan
  
  # Audit history (requires PaperTrail gem)
  config.audit_with :paper_trail, 'User', 'PaperTrail::Version'
  
  # Parent controller for inheritance
  config.parent_controller = 'ApplicationController'
end

Authentication Setup (Devise)

If using Devise, ensure you have an authenticated user model:

# config/initializers/rails_admin.rb
RailsAdmin.config do |config|
  config.authenticate_with do
    warden.authenticate! scope: :admin
  end
  
  config.current_user_method(&:current_admin)
end

Authorization (CanCanCan)

Create app/models/ability.rb:

class Ability
  include CanCan::Ability

  def initialize(user)
    if user.admin?
      can :access, :rails_admin
      can :manage, :all
    else
      cannot :access, :rails_admin
    end
  end
end

Per-Model Configuration

Configure individual models within the model class:

class Product < ApplicationRecord
  validates :name, presence: true
  
  rails_admin do
    # List view configuration
    list do
      field :name
      field :price
      field :created_at
    end
    
    # Edit form configuration
    edit do
      field :name
      field :description, :text
      field :category do
        label 'Product Category'
      end
    end
    
    # Exclude sensitive fields
    exclude_fields :secret_token
  end
end

Build & Run

Development

Start the Rails server:

rails server

Access the admin interface at:

http://localhost:3000/admin (if you chose default namespace)
http://localhost:3000/YOUR_NAMESPACE (custom namespace)

Production Asset Compilation

Precompile assets before deployment:

RAILS_ENV=production rails assets:precompile

For Webpacker:

RAILS_ENV=production NODE_ENV=production rails webpacker:compile

Deployment

Since RailsAdmin is a Rails engine, deploy your host Rails application using standard Rails deployment methods.

Heroku

# Create app
heroku create myapp-admin

# Set environment
heroku config:set RAILS_ENV=production
heroku config:set RAILS_ADMIN_USERNAME=admin
herover config:set RAILS_ADMIN_PASSWORD=secure_password

# Deploy
git push heroku main

# Run migrations
heroku run rails db:migrate

# Precompile assets (if not using Heroku buildpack)
heroku run rails assets:precompile

Docker

Create Dockerfile:

FROM ruby:3.1
RUN apt-get update -qq && apt-get install -y nodejs postgresql-client
WORKDIR /app
COPY Gemfile* ./
RUN bundle install
COPY . .
RUN bundle exec rails assets:precompile
CMD ["rails", "server", "-b", "0.0.0.0"]

Build and run:

docker build -t myapp .
docker run -p 3000:3000 -e RAILS_ENV=production myapp

Traditional VPS (Ubuntu/NGINX/Passenger)

Deploy code to server
Install dependencies: bundle install --deployment
Precompile assets: bundle exec rails assets:precompile
Run migrations: bundle exec rails db:migrate
Restart Passenger/NGINX

Production Security Checklist

Enable authentication (never leave admin open)
Configure authorization to restrict access
Use HTTPS/SSL
Set config.consider_all_requests_local = false
Configure config.action_dispatch.show_exceptions = true with proper error tracking
Set secure session cookies

Troubleshooting

Webpacker/Asset Issues (Upgrading from 2.x)

If assets fail to load after upgrading:

rails webpacker:install
yarn add rails_admin

Ensure app/javascript/packs/rails_admin.js exists:

import Rails from "@rails/ujs"
import * as ActiveStorage from "@rails/activestorage"
import "channels"

Rails.start()
ActiveStorage.start()

import "rails_admin/src/rails_admin/base"

Authentication Not Working

If you see "You need to sign in" loops:

Verify config.authenticate_with block matches your Devise scope
Check config.current_user_method matches your application's current user method
Ensure routes are not being cached with old settings: rails tmp:cache:clear

Database Connection Errors

For Mongoid users:

Ensure kaminari-mongoid is in Gemfile
Verify MongoDB connection string in config/mongoid.yml

Model Not Appearing

If models don't appear in the sidebar:

Check they're not in excluded_models
Verify model files are loaded (autoloading issues)
For STI models, ensure parent class is included

Export/Import Failures

For CSV/JSON export issues:

Check config.default_items_per_page isn't too high (memory issues)
Verify write permissions to tmp/ directory

How to Deploy & Use sferik/rails_admin