Installation with Docker

Goal

The goal of this getting started guide is to help you create a new backend application in under 5 minutes.

The fastest and easiest way to get started with Lumber is to pull the forestadmin/lumber Docker image and then create your backend application plugged to a database (we provide a demo database if needed).

Prerequisites

1. Initializing the database

This step is optional if you already have a running database. If so, skip ahead to step 2.

To import the demo database using our forestadmin/meals-database image, just run:

docker run -p 5432:5432 forestadmin/meals-database

That's all! Your database is running locally in a docker container.

To check if the database is correctly setup, you can use the command psql to connect to your freshly created database.

psql postgres://lumber:secret@localhost:5432/meals

Finally, you should get a prompt where you can type SQL queries or PostgreSQL command line \d to see the available list of tables.

meals=# \d
List of relations
Schema | Name | Type | Owner
--------+----------------------------+----------+--------
public | ar_internal_metadata | table | lumber
public | chef_availabilities | table | lumber
public | chef_availabilities_id_seq | sequence | lumber
public | chefs | table | lumber
public | chefs_id_seq | sequence | lumber
public | customers | table | lumber
public | customers_id_seq | sequence | lumber
public | delivery_men | table | lumber
public | delivery_men_id_seq | sequence | lumber
public | menus | table | lumber
public | menus_id_seq | sequence | lumber
public | menus_products | table | lumber
public | menus_products_id_seq | sequence | lumber
public | orders | table | lumber
public | orders_id_seq | sequence | lumber
public | orders_products | table | lumber
public | orders_products_id_seq | sequence | lumber
public | product_images | table | lumber
public | product_images_id_seq | sequence | lumber
public | products | table | lumber
public | products_id_seq | sequence | lumber
public | schema_migrations | table | lumber
(22 rows)

2. Generate your backend application

The Docker image forestadmin/lumber runs the command lumber generate to create your backend application plugged to a database through an ORM tool (Object-relational mapping).

$ docker run \
-v `pwd`:/usr/src/app \
--init \
-e DATABASE_URL=postgres://lumber:secret@host.docker.internal:5432/meals \
-e APP_HOST=localhost \
-e APP_PORT=3000 \
-e APP_NAME=MySuperApp \
-ti forestadmin/lumber

Line

Description

#1

Run a command in a new Docker container

#2

Create a Docker volume that bind your current working directory (retrieved with the command pwd) to the directory usr/src/app available inside the container and which contains the code of your freshly created backend.

#3

Specify an init process to better intercept signals such as SIGINT and SIGTERM.

#4

Declare an environment variable DATABASE_URL with the value of the database connection string. The database connection string. Syntax: dialect://user:password@host:port/dbname . IMPORTANT: 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.

#5

Declare an environment variable APP_HOST with the value of your backend application hostname.

#6

Declare an environment variable APP_PORT with the value your backend application will listen.

#7

Declare an environment variable APP_NAME with the value of your backend application name.

#8

Keep STDIN open with the option -i and allocate a TTY with -t. Finally, use the Docker Image forestadmin/lumber to run your container.

3. Run your freshly created backend application

$ cd MySuperApp/
$ docker-compose up

Your backend application should now be available at http://localhost:3000.

4. Getting comfortable with the code

The application's code consists of a simple Node.js application.

  • package.json and package-lock.json files are standard files that are the manifest of any Node.js project and contains metadata.

  • Dockerfile and docker-compose.yml files are used by Docker to let you run your application inside a Docker container.

  • bin/ directory contains a file www which instantiates an Express.js web server.

  • middlewares/ is the directory that contains all the Lumber plugins.

  • models/ is the directory that contains all the data model using an ORM (Sequelize or Mongoose).

  • public/ is the directory that contains the public assets.

  • routes/ is a directory which can be used to implement your custom API routes.

├── Dockerfile
├── docker-compose.yml
├── package-lock.json
├── package.json
├── app.js
├── bin/
│   └── www
├── middlewares/
│   └── welcome/
│   ├── index.js
│   └── template.txt
├── models/
│   ├── ar_internal_metadata.js
│   ├── chef_availabilities.js
│   ├── chefs.js
│   ├── customers.js
│   ├── delivery_men.js
│   ├── index.js
│   ├── menus.js
│   ├── menus_products.js
│   ├── orders.js
│   ├── orders_products.js
│   ├── product_images.js
│   ├── products.js
│   └── schema_migrations.js
├── public/
│   └── favicon.png
└── routes/