Upgrade to v6

The purpose of this note is to help developers to upgrade their liana from v5 to v6. Please read carefully and integrate the following breaking changes to ensure a smooth update.​

Upgrading to v6

Before upgrading to v5, consider the below breaking changes.

As for any dependency upgrade, it's very important to test this upgrade in your testing environments. Not doing so could result in your admin panel being unusable.

To upgrade to v6, update the version in your Gemfile, then run the following and update your project as shown in the Breaking Changes section below.:

bundle install

In case of a regression introduced in Production after the upgrade, a rollback to your previous liana version 5 is the fastest way to restore your admin panel.

Breaking changes

Easier authentication

The liana version introduces an improved authentication mechanism. The following changes are required:

New environment variable

In your secrets.yml file, set a forest_application_url variable: it must contain your Rails app URL for that environment. Then add the following:

config/initializers/forest_liana.rb
ForestLiana.application_url = Rails.application.secrets.forest_application_url

New CORS condition

Add null_regex = Regexp.new(/\Anull\z/) as a variable and use it in your cors configuration. When using rack cors, it should look like this:

null_regex = Regexp.new(/\Anull\z/)
config.middleware.insert_before 0, Rack::Cors do
allow do
hostnames = [null_regex, 'localhost:4200', 'app.forestadmin.com', 'localhost:3001']
hostnames += ENV['CORS_ORIGINS'].split(',') if ENV['CORS_ORIGINS']
origins hostnames
resource '*',
headers: :any,
methods: :any,
expose: ['Content-Disposition'],
credentials: true
end
end

Enable caching

You need to enable caching on your environment to be able to authenticate to Forest Admin. You can do it by running the following command:

rails dev:cache

You can either enable caching or setup a static clientId as shown in the next step.

Setup a static clientId

This is required if you're running multiple instances of your agent (with a load balancer for exemple) or if you don't want to enable caching on your environment.

First, you will need to obtain a Client ID for your environment by running the following command:

curl -H "Content-Type: application/json" \
-H "Authorization: Bearer FOREST_ENV_SECRET" \
-X POST \
-d '{"token_endpoint_auth_method": "none", "redirect_uris": ["APPLICATION_URL/forest/authentication/callback"]}' \
https://api.forestadmin.com/oidc/reg

Then assign the client_id value from the response (it's a JWT) to a forest_client_id variable in your secret.yml file.

Lastly, add the following:

config/initializers/forest_liana.rb
ForestLiana.forest_client_id = Rails.application.secrets.forest_client_id

Important Notice

Changelogs

This release note covers only the major changes. To learn more, please refer to the changelogs in our different repositories: