Install in Lumber

Now that you have followed the first steps of our sign-up process, let's install Forest Admin using Lumber.

Goals

The goal of this guide is to create a new backend application (using Lumber) dedicated to your Admin API. This API has everything you need to get started with Forest Admin and allows you to extend it with virtually no limitations.

The fastest and easiest way to do this is to use Docker with the image forestadmin/lumber-forestadmin.

What is Lumber?

Lumber is an open-source web framework built on top of Express.js by Forest Admin's team. It comes with a powerful CLI that helps you create your backend application in minutes.

As its core, Lumber has been designed with a modular architecture that leverages a set of plugins. For example, it takes one command to get a REST API, a GraphQL API or a fully operational Admin Panel like Forest Admin.

Install using Docker

1. Generate your admin backend

You need a live database to follow this guide. If you don't have one, check out this page.

Edit the DATABASE_URL below to match your database credentials, then run the command:

docker run \
-v `pwd`:/usr/src/app --init \
-e DATABASE_URL=postgres://user:password@host.docker.internal:5432/database_name \
-e APP_NAME=MySuperAdmin \
-e FOREST_EMAIL=you@your-company.com \
-e FOREST_TOKEN=wuY29tIiwiZXhwIjoxNDI2NDIwODAwLCJodHRwOi8vdG9wdG... \
-ti forestadmin/lumber-forestadmin

where DATABASE_URL is your database connection string. Use the following syntax: dialect://user:password@host:port/dbname.

If your database is running locally on your host machine, use host.docker.internal instead of localhost to refer your host machine IP from your container.

Other available options are:

Option

Description

-e APPLICATION_HOST

The hostname of your admin backend app. Default is localhost.

-e APPLICATION_PORT

The port of your admin backend app. Default is 3310.

-e DATABASE_SSL

Does your database require SSL. Default is false.

-e FOREST_PASSWORD

If this is not filled, your Forest Admin password will be asked interactively.

Wrap your password in double quotes if it contains special characters.

2. Run your admin backend application

After the step 1, a new directory named with your APP_NAME has been created (MySuperAdmin in this example).

cd MySuperAdmin
docker-compose up

That's it! Your project should be available on app.forestadmin.com/projects.

Install using NPM

Requirements: the following steps require ≥ v8.12.0 and ≥ v6.10

If you'd rather not use Docker, follow these simple steps:

1. Install lumber-cli

npm install -g lumber-cli -s

If you encounter a NPM permission issue, read How to prevent errors when installing Lumber.

2. Generate your app

Use the newly installed lumber-cli to generate your app.

You need a live database before running this command: your database credentials are required

lumber generate "MySuperAdmin" -c "postgres://user:password@host.docker.internal:5432/my_database"

where:

  • postgres is your database engine (other options are mysql, mongodb, mssql,..)

  • user is your database user

  • password is your database password

  • host.docker.internal is your database host

  • 5432 is your database port (defaults are 5432 for postgres, 3306 for mysql and 27017 for mongodb)

  • my_database is your database name

  • MySuperAdmin is your app's name

The -c (or --connectionUrl) option allows you to provide your database connection url. If you don't provide it, the terminal will ask you interactively to prompt them.

Other options are available for the lumber generate command:

Option

Description

-H, --application-host

The port of your admin backend app. Default is 3310.

-p, --application-port

The hostname of your admin backend app. Default is localhost.

-S, --ssl

Does your database require SSL. Default is false.

-s, --schema

(SQL only) Your schema if it is custom. Default is public.

--authentication-database

(Mongo only) Your authSource if it is custom. Default is admin.

Then navigate to your newly created app folder and install npm dependencies.

cd "MySuperAdmin"
npm install -s

3. Install the Forest Admin plugin

Now that Lumber has generated an app dedicated to your back office, let's create your Forest Admin back office!

From your app's folder (MySuperAdmin/), install the lumber-forestadmin npm package.

npm install lumber-forestadmin -s --save

Install the Forest Admin plugin using Lumber

lumber install lumber-forestadmin --email you@your-company.com --projectName MySuperAdmin

If you don't provide one of the following options in the abovelumber install command, you will be prompted for your password interactively:

Option

Description

-t, --token

Your Forest Admin token.

-P, --password

Your Forest Admin password.

4. Launch your Forest Admin

Your Forest Admin back office is ready to be used. Launch your node server and follow the terminal instructions:

npm start

That's it! Your project should be available on app.forestadmin.com/projects.