Installation

Requirements

• Ruby on Rails >= 6.1
• Ruby >= 3.1
• api_only set to false. More here.
• propshaft or sprockets gem
• Have the secret_key_base defined in any of the following ENV["SECRET_KEY_BASE"], Rails.application.credentials.secret_key_base, or Rails.application.secrets.secret_key_base

Zeitwerk autoloading is required.

When adding Avo to a Rails app that was previously a Rails 5 app you must ensure that it uses zeitwerk for autoloading and Rails 6.1 or higher defaults.

# config/application.rb
config.autoloader = :zeitwerk
config.load_defaults 6.1 # 6.1 or higher, depending on your rails version

Installing Avo

1. One-command install

Use this app template for a one-liner install process.

Run this command which will run all the required steps to install Avo in your app.

bin/rails app:template LOCATION='https://avohq.io/app-template'

Let an LLM do it for you

Working with an AI coding assistant (Claude, Cursor, Copilot, etc.)? Paste this prompt and let it handle the install:

Install and configure Avo in this Rails app by following
https://docs.avohq.io/4.0/installation.html — run the install steps,
wire up the initializer and routes, then generate my first resource.

2. Manual, step by step.

1. Add the appropriate Avo gem to the Gemfile

# Avo Community
gem "avo", ">= 4.0.0"

# If you're on a paid plan, add the feature gems included in your license.
source "https://packager.dev/avo-hq/" do
  # all or some of these
  gem "avo-authorization", ">= 4.0.0"
  gem "avo-advanced_search", ">= 4.0.0"
  gem "avo-advanced_file_uploads", ">= 4.0.0"
  gem "avo-record_reordering", ">= 4.0.0"
  gem "avo-menu_editor", ">= 4.0.0"
  gem "avo-menu", ">= 4.0.0"
  gem "avo-dashboards", ">= 4.0.0"
  gem "avo-http_resource", ">= 4.0.0"
  gem "avo-dynamic_filters", ">= 4.0.0"
  gem "avo-nested", ">= 4.0.0"
  gem "avo-collaboration", ">= 4.0.0"
  gem "avo-forms", ">= 4.0.0"
  gem "avo-kanban", ">= 4.0.0"
  gem "avo-api", ">= 4.0.0"
  gem "avo-reactive_fields", ">= 4.0.0"
  gem "avo-notifications", ">= 4.0.0"
end

INFO

Please use this guide to find the best authentication strategy for your use-case.

2. Run bundle install.
3. Run bin/rails generate avo:install to generate the initializer and add Avo to the routes.rb file.
4. Generate an Avo Resource

INFO

This will mount the app under /avo path. Visit the link to see the result.

3. In popular Rails starter kits

We have integrations with the most popular starter kits.

Bullet Train

Avo comes pre-installed in all new Bullet Train applications.

If you have a Bullet Train app and you'd like to add Avo, please use this template.

bin/rails app:template LOCATION=https://v3.avohq.io/templates/bullet-train.template

Jumpstart Pro

To install Avo in a Jumpstart Pro app use this template.

bin/rails app:template LOCATION=https://v3.avohq.io/templates/jumpstart-pro.template

Install from GitHub

You may also install Avo from GitHub but when you do that you must compile the assets yourself. You do that using the rake avo:build-assets command. When pushing to production, make sure you build the assets on deploy time using this task.

# Rakefile
Rake::Task["assets:precompile"].enhance do
  Rake::Task["avo:build-assets"].execute
end

INFO

If you don't have the assets:precompile step in your deployment process, please adjust that with a different step you might have like db:migrate.

Mount Avo to a subdomain

You can use the regular host constraint in the routes.rb file.

constraint host: 'avo' do
  mount_avo at: '/'
end

Next steps

Please follow the next steps to ensure your app is secured and you have access to all the features you need.

1. Set up authentication and tell Avo who is your current_user. This step is required for the authorization feature to work.
2. Set up authorization. Don't let your data be exposed. Give users access to the data they need to see.
3. Set up licensing.