Motor Admin Rails

Low-code Admin panel and Business intelligence Rails engine (no DSL - configurable from the UI).

🤓 Demo App | 👀 Features overview | ⭐ Pro

Installation

Add this line to your application's Gemfile:

gem 'motor-admin'

And then execute:

$ bundle install

Create and run migration:

$ rails motor:install && rake db:migrate

Features

• Customizable CRUD
• Custom actions
• Virtual attributes
• Forms builder
• SQL queries
• Data visualization
• Dashboards
• Email alerts
• Authorization
• Active Storage
• Intelligence search
• I18n
• Optimized for mobile
• Configurations sync between environments
• Authentication
• Multiple databases support
• Audit log
• Live collaboration notes
• Personalized report alerts via Slack

Pro

• Custom styling and logo (white label)
• Multi-factor authentication
• SSO/SAML
• learn more

Customizable CRUD

Everything in the admin panel can be configured using the intuitive settings UI, which can be opened via the icon in the top right corner.

Data displayed on the resource page can be completely customized via SQL queries and dashboards attached to the resource as a tab. Usually, queries used to display resource data should contain {{resource_name_id}} variable.

Learn more about resource customizations

Custom Actions

Custom resource actions can be added via Active Record method call, API endpoint, or custom forms. Also, it's possible to override default create/update/delete actions.

Virtual attributes

Any ActiveRecord model method or attribute can be exposed to the admin panel by adding a new column with the name that matches the method name from the resource model:

class Customer < ApplicationRecord
  has_many :orders

  def lifetime_value
    orders.sum(&:total_price)
  end
end

Forms Builder

Values from the form fields can be used in API path via {field_name} syntax: /api/some-endpoint/{resource_id}/apply.

Learn more about custom forms builder

SQL Queries

Queries can include embedded variables via {{variable}} syntax (mustache). {{#variable}} ... {{/variable}} syntax allows to decide if conditions inside the scope should be included in the query.

Data Visualization

Data from the SQL query can be represented as: table, number, line chart, bar chart, pie chart, funnel, markdown.

Dashboards

SQL queries can be organized into dashboards to create a convenient representation of the data.

Email Alerts

Query data can be sent via email periodically using the alerts feature. Interval of the alert email can be specified using natural language, e.g., every day at midnight, every Monday at 8 PM, every weekday at 6AM and 6PM, every minute.

Sender address can be specified using MOTOR_ALERTS_FROM_ADDRESS environment variable.

Intelligence Search

Intelligence search can be opened via the top right corner button or using Cmd + K shortcut.

Authorization

Motor Admin allows to set row-level and column-level permissions via cancan gem. Admin UI permissions should be defined in app/models/motor/ability.rb file in Motor::Ability class. See Motor Admin guide and CanCan documentation to learn how to define user permissions.

Active Storage

Motor Admin is configured by default to perform uploads to the provider you configured in your storage.yml file for Active Storage. If you are using large uploads within Motor Admin you will need to enable direct uploads by setting the following ENV variable.

MOTOR_ACTIVE_STORAGE_DIRECT_UPLOADS_ENABLED=true

Note: At the moment, this will enable direct uploads globally

I18n

Motor Admin can use Rails ActiveRecord i18n keys to render resource translations:

es:
  activerecord:
    models:
      customer:
        one: Cliente
        other: Clientes
    attributes:
      customer:
        name: Nombre
    scopes:
      customer:
        enabled: Activado

Optimized for Mobile

Configurations Sync

All admin panel configurations are automatically stored in the config/motor.yml file. It's recommended to include this file in the application git repository to always have the admin panel configurations in sync across different local and remote environments.

It's possible to sync local development admin panel configurations with remote production application via rake motor:sync task:

MOTOR_SYNC_REMOTE_URL=https://remote-app-url/ MOTOR_SYNC_API_KEY=secure-random-string rake motor:sync

Authentication

Admin panel can be secured with 'Basic authentication' by specifying MOTOR_AUTH_USERNAME and MOTOR_AUTH_PASSWORD environment variables.

Alternatively, it can be secured with devise or any other authentication library used by the application:

authenticate :admin_user do
  mount Motor::Admin => '/admin'
end

Development

Prerequisites

• Ruby 3.3.1 (see .ruby-version)
• Node.js (v18+ recommended)
• Yarn package manager
• SQLite3 (for development)

Quick Start

Option 1: Docker (Recommended)

The easiest way to get started is using Docker:

docker-compose up

This will:

• Install all Ruby and Node.js dependencies (only if needed)
• Build frontend assets (only if needed)
• Generate required gzipped assets
• Start the Rails server on http://localhost:3000

Smart Setup: The Docker setup is intelligent - it only installs dependencies and builds assets when needed, making subsequent runs much faster.

Optional Helper Commands:

./bin/docker-dev start    # Same as docker-compose up
./bin/docker-dev build    # Force rebuild image
./bin/docker-dev clean    # Clean up Docker resources
./bin/docker-dev logs     # View application logs
./bin/docker-dev shell    # Open shell in container

Option 2: Manual Setup

Use the provided setup script:

./bin/dev-setup

Then start the server:

DATABASE_TYPE=sqlite rails server

Option 3: Manual Step-by-Step

1. Install dependencies:

   bundle install
   cd ui && yarn install && cd ..

2. Build frontend assets:

   cd ui && yarn run build:dev && cd ..

3. Generate gzipped assets:

   find ui/dist -name "*.js" -o -name "*.css" -o -name "*.svg" | xargs -I {} gzip -k {}

4. Setup database:

   rake app:db:create app:db:setup

5. Start server:

   DATABASE_TYPE=sqlite rails server

Development Modes

Production-like Development

This mode serves pre-built assets from disk (recommended for most development):

DATABASE_TYPE=sqlite rails server

Hot Reloading Development

For frontend development with live reloading:

1. Start webpack dev server:

   cd ui && yarn serve

2. In another terminal, start Rails server:

   MOTOR_DEVELOPMENT=true DATABASE_TYPE=sqlite rails server

Docker Profiles

The docker-compose.yml includes several profiles for different scenarios:

Default Profile (Production-like)

docker-compose up
# Starts on http://localhost:3000

Development Profile (Hot Reloading)

docker-compose --profile dev up dev
# Starts on http://localhost:3001
# Webpack dev server on http://localhost:9090

With PostgreSQL

docker-compose --profile postgres up app postgres

With MySQL

docker-compose --profile mysql up app mysql

Frontend Development

Building Assets

• Development build: cd ui && yarn run build:dev
• Production build: cd ui && yarn run build:prod
• Test build: cd ui && yarn run build:test

Asset Structure

• Source files: ui/src/
• Built assets: ui/dist/
• Webpack config: ui/webpack.config.js

Important Notes

1. Asset Location: Motor Admin serves assets directly from ui/dist/, not from a public/ folder. The gem's asset serving is handled by the Motor::Assets module.

2. Gzipped Assets: The Rails app expects gzipped versions of assets when not in development mode. Always run the gzip command after building assets.

3. Asset Manifest: The ui/dist/manifest.json file maps asset names to their hashed filenames.

4. Icons: SVG icons are served from ui/dist/icons/ and also need gzipped versions.

5. Public Folder: If a public/ folder is created during development, it should NOT be committed to version control. It's added to .gitignore to prevent accidental inclusion.

Database Support

Motor Admin Rails supports multiple databases:

• SQLite (default): DATABASE_TYPE=sqlite
• PostgreSQL: Set up connection in config/database.yml
• MySQL: Set up connection in config/database.yml
• SQL Server: Requires activerecord-sqlserver-adapter gem

Environment Variables

Key environment variables for development:

• DATABASE_TYPE: Database type (sqlite, postgresql, mysql)
• MOTOR_DEVELOPMENT: Enable development mode (hot reloading)
• RAILS_ENV: Rails environment (development, test, production)
• RAILS_LOG_LEVEL: Logging level (debug, info, warn, error)

Troubleshooting

Common Issues

1. 500 errors for assets: Missing gzipped versions

   find ui/dist -name "*.js" -o -name "*.css" -o -name "*.svg" | xargs -I {} gzip -k {}

2. node-sass errors: Use Node.js 18+ and ensure sass package is installed

   cd ui && yarn add -D sass && yarn remove node-sass

3. Missing Babel plugins: Install required plugins

   cd ui && yarn add -D @babel/plugin-syntax-dynamic-import

4. ActiveRecord errors: Ensure database is set up correctly

   rake app:db:create app:db:setup

Asset Debugging

To debug asset issues:

1. Check if assets exist: ls -la ui/dist/
2. Check manifest: cat ui/dist/manifest.json
3. Check gzipped versions: ls -la ui/dist/*.gz ui/dist/icons/*.gz
4. Check Rails logs for asset request errors

Docker Issues

• Build cache issues: Use docker-compose build --no-cache
• Permission issues: Ensure files are readable by the docker user
• Port conflicts: Check if ports 3000/3001/9090 are available

Testing

Run the test suite:

bundle exec rspec

For frontend testing:

cd ui && yarn test  # if test script exists

Contributing

When contributing:

1. Ensure all tests pass
2. Build and test assets work correctly
3. Update documentation if needed
4. Follow existing code style and patterns

Additional Resources

• Motor Admin Documentation
• Rails Guides
• Vue.js Documentation
• Webpack Documentation

License

Motor Admin is licensed under the MIT license.