Installation

Table of contents

1. Requirements
2. Step 1: Add the Gems
3. Step 2: Run the Install Generator
4. Step 3: Mount the Engine (if not auto-mounted)
5. Step 4: Configure Authentication
6. Step 5: Create Your First Resource
7. Step 6: Build CSS and Start the Server
8. Tailwind CSS Setup
   1. How it works
   2. Manual setup (without the generator)
   3. Troubleshooting
9. Dependencies

---

Requirements

• Ruby >= 3.3 (tested on 3.3, 3.4, and 4.0)
• Rails >= 8.0.4 (tested on 8.0 and 8.1)
• tailwindcss-rails >= 4.3
• The default rails new JavaScript setup: importmap with Stimulus. IronAdmin installs importmap-rails itself; its layout loads the admin JavaScript with javascript_importmap_tags and registers its Stimulus controllers on window.Stimulus, which bin/rails stimulus:install sets up.

On Rails 8.0, keep the json gem below 3.0 (gem "json", "< 3"). Active Support 8.0 passes quirks_mode: to JSON, which json 3.0 rejects with an ArgumentError. Rails 8.1 is not affected.

Step 1: Add the Gems

Add IronAdmin and tailwindcss-rails to your Gemfile:

gem "iron_admin"
gem "tailwindcss-rails"

Then run:

bundle install

Step 2: Run the Install Generator

rails generate iron_admin:install

This creates:

File	Purpose
config/initializers/iron_admin.rb	Main configuration (title, auth, theme)
app/iron_admin/resources/	Directory for resource definitions
app/iron_admin/dashboards/	Directory for dashboard definitions
app/iron_admin/dashboards/admin_dashboard.rb	Default dashboard class

It also:

• Mounts the engine at /admin in config/routes.rb
• Adds the IronAdmin CSS import to app/assets/tailwind/application.css

Step 3: Mount the Engine (if not auto-mounted)

In config/routes.rb:

Rails.application.routes.draw do
  mount IronAdmin::Engine => "/admin"
end

Step 4: Configure Authentication

Edit config/initializers/iron_admin.rb:

IronAdmin.configure do |config|
  config.title = "My App Admin"

  config.authenticate do |controller|
    unless controller.session[:user_id]
      controller.redirect_to "/login"
    end
  end

  config.current_user do |controller|
    User.find_by(id: controller.session[:user_id])
  end
end

Step 5: Create Your First Resource

rails generate iron_admin:resource User

This creates app/iron_admin/resources/user_resource.rb. IronAdmin automatically infers fields from your model’s database schema.

Step 6: Build CSS and Start the Server

rails tailwindcss:build
bin/rails server

Visit /admin and your admin panel is ready.

For development with live CSS recompilation, use bin/dev (which runs tailwindcss:watch alongside the Rails server via foreman).

There is a known issue in tailwindcss-rails v4 where bin/dev exits immediately after starting. If this happens, edit Procfile.dev and change the CSS line to css: bin/rails tailwindcss:watch[always].

Tailwind CSS Setup

IronAdmin uses Tailwind CSS v4 for all styling via the tailwindcss-rails gem. Understanding how the CSS pipeline works will help you troubleshoot any styling issues.

How it works

1. IronAdmin ships with @source directives at app/assets/tailwind/iron_admin/engine.css inside the gem. These tell the Tailwind compiler where to scan for CSS utility classes used by the engine’s views, components, and helpers.

2. When tailwindcss:build runs, it first executes tailwindcss:engines. This task detects IronAdmin’s engine CSS and creates a bridge file at app/assets/builds/tailwind/iron_admin.css containing an @import that points to the engine’s CSS.

3. Your app/assets/tailwind/application.css must import this bridge file:

   @import "tailwindcss";
   @import "../builds/tailwind/iron_admin";
   

4. The Tailwind compiler processes application.css, follows the imports, scans all the engine’s source files via the @source directives, and generates the final app/assets/builds/tailwind.css with all necessary utility classes.

5. The engine’s layout references stylesheet_link_tag "tailwind", which serves this compiled CSS file.

Manual setup (without the generator)

If you didn’t use the install generator, or the import line is missing:

1. Verify tailwindcss-rails is in your Gemfile and installed

2. Add the import to app/assets/tailwind/application.css:

   @import "tailwindcss";
   @import "../builds/tailwind/iron_admin";
   

3. Build the CSS:

   rails tailwindcss:build
   

4. Verify the build output:

   ls -la app/assets/builds/tailwind.css
   # Should be ~30KB+ (not ~6KB which indicates no utility classes)
   

Troubleshooting

Styles not loading (unstyled admin panel)

This almost always means the Tailwind compiler didn’t scan IronAdmin’s source files. Check:

1. The @import "../builds/tailwind/iron_admin" line exists in app/assets/tailwind/application.css
2. The bridge file exists at app/assets/builds/tailwind/iron_admin.css (run rails tailwindcss:build to regenerate it)
3. The compiled CSS at app/assets/builds/tailwind.css is large enough (~30KB+, not ~6KB)

Bridge file not generated

If app/assets/builds/tailwind/iron_admin.css doesn’t exist after running rails tailwindcss:build:

• Ensure tailwindcss-rails >= 4.3 is installed (bundle info tailwindcss-rails). Older versions have no tailwindcss:engines task, so they never write the bridge file.
• Ensure iron_admin is properly loaded (check bundle info iron_admin)
• Try running rails tailwindcss:engines directly

Styles disappear after bundle update

The bridge file uses an absolute path to the gem’s CSS. After updating the gem (which changes the gem path), run rails tailwindcss:build to regenerate it.

Dependencies

IronAdmin depends on the following gems (installed automatically):

Gem	Version	Purpose
rails	>= 8.0.4	Framework
view_component	>= 4.0, < 5	UI components
turbo-rails	>= 2.0.6	Hotwire Turbo
stimulus-rails	>= 1.3	Hotwire Stimulus
importmap-rails	>= 2.0	Loads the admin JavaScript (javascript_importmap_tags)
pagy	>= 43.7.1, < 44	Pagination
haml-rails	>= 2.0	Template engine
heroicon	>= 1.0	SVG icons
csv	>= 3.2.8	CSV import and export (not a default gem since Ruby 3.4)
ostruct	>= 0.6	Action event objects (not a default gem since Ruby 4.0)

Peer dependency (must be added to your Gemfile manually):

Gem	Version	Purpose
tailwindcss-rails	>= 4.3	Tailwind CSS compilation (tailwindcss:engines writes the IronAdmin bridge file)