Installation

Requirements

• Ruby on Rails >= 6.1
• Ruby >= 3.2
• 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

Update Avo

avo:update resolves every Avo gem in your bundle, core plus any add-on, and updates them together with bundle update --conservative, so the other gems in your lockfile stay where they are.

bin/rails avo:update

Use it rather than bundle update avo, which moves core alone and leaves each add-on pinned where it was.

Commit and push the update

Since avo >= v4.3.10

With AVO_UPDATE_PUSH=1 the task also commits the updated Gemfile.lock and pushes it to the current branch's upstream, so a scheduled job or an agent can keep the gems current on its own.

AVO_UPDATE_PUSH=1 bin/rails avo:update

Before it touches any gem, the task checks that it runs inside a Git repository, that no tracked file has uncommitted changes (untracked files are fine), and that the current branch has an upstream. If one of them fails, it stops and your bundle stays as it was.

The commit carries Gemfile.lock and nothing else, with the message Update Avo gems. When the update leaves the lockfile unchanged, nothing is committed or pushed. Any failing step stops the task and says what it left behind, for example that the commit is available locally when the push fails.

WARNING

AVO_UPDATE_PUSH=1 pushes to the current branch's upstream. Run it on a branch you are happy to push to, not on the one you deploy from.

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.