I don't like dealing with databases, and I don't like doing tutorials with no idea of what's going on.

Somehow, in someway, something always goes wrong.

This tutorial has two goals:

• show how to set up an express app with a mongo database running in Docker
• explain what is happening in the Docker configs

The banner image was made with DreamStudio. I should really learn how to do prompt engineering.

What we'll be building

In this tutorial, we'll be building a simple todo app. The server is built with express, and the database will be MongoDB. The key is that the whole app will be dockerized, making dealing with the database easier, but we'll still be able to make changes to our server for development.

I won't get into the details of how Docker works internally (I don't think I could even begin to do that!) but rather make all the configuration needed understandable.

We'll look over

• the app itself
• the Dockerfile in the app
• the docker-compose.yml file

A github repo with all the code can be found here.

Prereqs

The only things you need to have installed are Node (which if you're reading this, you probably have), and Docker.

The easiest way to get started with Docker is by installing Docker Desktop.

How the app works

The app is pretty simple.

There is only one view route /. When a user hits /, the app lists out all the todos in the database.

Whenever the user adds a new todo, deletes a todo, or deletes all the todos, a request is made to the appropriate route, the action is done (like add a new todo), and the app redirects them to / page, where all the todos, including the one just added, are displayed.

This app is just a clone of this repo with some minor modifications.

Dockerizing

Here are our main building blocks for getting set up with Docker:

• the Dockerfile
• the docker-compose.yaml

Dockerfile: our app

The first building block is the Dockerfile. This is a set of instructions that tells Docker how to build our image

Ours looks like this:

FROM node:18
WORKDIR /app
COPY package*.json .
RUN npm install
COPY . .
CMD [ "npm", "run", "start:dev" ]

Let's break it down.

FROM node:18
First we use the node 18 image. This is an express app, so we need node.

WORKDIR /app
The next line sets the working directory to /app. We don't have an /app directory in our source, but Docker creates one inside of the container. This is sort of like a mkdir and cd command in one. It creates a new directory and sets that as our working directory.

COPY package*.json .
The COPY command copies contents from your local machine to the working directory in the container.

Its syntax is like this:

COPY <src> <dest>

This command copies the package.json and package-lock.json files to the container.

RUN npm install
Pretty straightfoward — in the container's working directory, run npm install.

COPY . .
As we've seen from the previous copy command, this copies the contents of our local machine into the container. This particular command, however, copies all the contents of repo (unless we have a .dockerignore file).

CMD [ "npm", "run", "start:dev" ]
Now we start the app! You'll commonly see these commands expressed as an array like this.

The command npm run start:dev is defined in our package.json:

{
  "name": "dcoker-todo",
  "scripts": {
    "start": "node app.js",
    "start:dev": "nodemon -L app.js"
}

docker-compose.yaml: running everything

Now we get to the good stuff — actually running our express app with a Mongo database.

Docker terminology can be a bit tricky at times, so let's recap.

In the previous section, we used a Dockerfile to create an image. An image defines our container. A container is an instance of an image running. In this section, we are going to use compose to build an application that's composed of multiple containers.

Before we run our app, there is one thing we need to so first; set up an .env.

PORT=3000
MONGODB_URI=mongodb://db:27017
MONGODB_USER=admin
MONGODB_PASSWORD=admin
MONGODB_DATABASE=todos

The only value that isn't arbitrary is MONGODB_URI. We'll look at that later.

We need to set up a docker-compose.yml, this tells the compose command how to structure our application.

It can be a bit overwhelming at first

# version: "3.8" no longer needed
volumes:
  db:

services:
  app:
    container_name: todo_app
    build: .
    ports:
      - "3000:3000"
    environment:
      - PORT=${PORT}
      - MONGODB_URI=${MONGODB_URI}
      - MONGODB_DATABASE=${MONGODB_DATABASE}
    volumes:
      - .:/app
      # if you comment out the line below, you will have to run npm install locally
      - /app/node_modules
    depends_on:
      - db
    links:
      - db

  db:
    container_name: mongodb
    image: mongo:latest
    restart: always
    volumes:
      - db:/data/db
    command: mongod
    environment:
      MONGO_INITDB_ROOT_USERNAME: ${MONGODB_USER}
      MONGO_INITDB_ROOT_PASSWORD: ${MONGODB_PASSWORD}
      MONGO_INITDB_DATABASE: ${MONGODB_DATABASE}
    ports:
      - 27017:27017

The big picture

Let's break it down.

# version: "3.8" no longer needed
volumes:
services:

version:
You'll often see version number at the top, but this is no longer needed.

The version number is the version of the docker-composer.yml file NOT the version of Compose.

In June 2023 they are updating docker compose to v2. This tutorial is assuming you're using v2 (I'm on v2.10.2).

volumes:
Volumes are how data is persisted outside of the container. So when you tear down the container, the data (i.e. our todos) will still be there.

services:
These are the container in your app.

Now, let's dig into volumes more.

volumes

volumes:
  db:

That's it! No, really. All we have to do is define a volume called db, and we're good to go. We could add extra configuration, but we don't need to do that for this tutorial.

What does matter, however, is that we have to use the name db everywhere to reference this volume. That will matter for our services, and it matters for our .env file above. That's why MONGODB_URI has to connect to mongodb://db:27017. The db has to match the name of the volume. The port number is the default port.

note: often, services is defined at the top of the file and volumes below. The ordering makes no difference.

services

services:
  app:
  db:

We have two containers — app and db.

services:app

services:
  app:
    container_name: todo_app
    build: .
    ports:
      - "3000:3000"
    environment:
      - PORT=${PORT}
      - MONGODB_URI=${MONGODB_URI}
      - MONGODB_DATABASE=${MONGODB_DATABASE}
    volumes:
      - .:/app
      - /app/node_modules
    depends_on:
      - db
    links:
      - db

container_name:
Just a name!

build: .
This tells docker which image to use to build the container. In this case, it's our Dockerfile we defined above.

ports:
    - "3000:3000"

This says to map port 3000 on our machine to port 3000 in the container (i.e. we can access the app by going to localhost:3000)

environment:
  - PORT=${PORT}
  - MONGODB_URI=${MONGODB_URI}
  - MONGODB_DATABASE=${MONGODB_DATABASE}

The sets the environment variables within the app from our .env file. So when we do

var port = process.env.PORT || 3000;
app.listen(port, ...)

The PORT is injected to the container from our .env file.

volumes:
    - .:/app
    - /app/node_modules

This is probably one of the more confusing parts of the set up.

As said before, volumes are ways to persist data. With the first definition, the . directory is mapped to /app in the container. Remember, /app from the Dockerfile? That's our working directory where everything is installed. It essentially replaces /app in our container with ..

The second definition is trickier. Notice that there is no :, which means there is no mapping. This definition will mount /app/node_modules to the previous mapping, i.e. your host. As a side effect, it creates an empty node_modules!

This means that the node_modules in the container is being used.

<Aside>

If you were to remove this definition, the app wouldn't work unless you ran npm install on the host (i.e. your machine).

You would also want to add a .dockerignore ignore to your repo like this:

node_modules
npm-debug.log

</Aside>

The answer here explains it well.

depends_on:
  - db
links:
  - db

These last two go hand-in-hand for our case. The depends_on definition means that Docker will wait for the db service, defined below, to start first. The links definition enables the two services to communicate. We want our app container to be able to talk to our database container.

services:db

services:
  # app: goes here
  db:
    container_name: mongodb
    image: mongo:latest
    restart: always
    volumes:
      - db:/data/db
    command: mongod
    environment:
      MONGO_INITDB_ROOT_USERNAME: ${MONGODB_USER}
      MONGO_INITDB_ROOT_PASSWORD: ${MONGODB_PASSWORD}
      MONGO_INITDB_DATABASE: ${MONGODB_DATABASE}
    ports:
      - 27017:27017

We defined our app service, now we have to define a service for our database.

We already defined this as a volume, but we also need to define it as a service (i.e. a container). The name of the service, needs to match the name of the volume.

container_name: mongodb
Again, just a name!

image: mongo:latest
Unlike the build command in our previous service, image tells Docker to pull down a prebuilt image; in this case, mongodb.

restart: always
Restarts the service if something happens.

volumes:
    - db:/data/db

Another volume! We know that : means we are mapping something. In this case, we are mapping the volume defined at the top of our file to the directory /data/db in the container, which is the default storage location. Remember that a mapping essentially replaces the right hand side. So when the container starts, /data/db is replaces by the volume that Docker created to persist our data.

command: mongod
The command to start the database.

environment:
  MONGO_INITDB_ROOT_USERNAME: ${MONGODB_USER}
  MONGO_INITDB_ROOT_PASSWORD: ${MONGODB_PASSWORD}
  MONGO_INITDB_DATABASE: ${MONGODB_DATABASE}

I think that this is one of the coolest things! We can set a default username, password, and database when the container starts. These environment variables are specific to mongo, and there is more information in the docs.

What's cool is that we can define these in our .env and use them to connect to the database with our server, like this:

mongoose
  .connect(`${process.env.MONGODB_URI}`, {
    dbName: `${process.env.MONGODB_DATABASE}`,
    user: `${process.env.MONGODB_USER}`,
    pass: `${process.env.MONGODB_PASSWORD}`,
    useNewUrlParser: true,
    useUnifiedTopology: true,
    useFindAndModify: false,
  })

This let's us keep our code DRY!

ports:
  - 27017:27017

Another mapping; this time for mongo's default port.

Running it.

If you clone the repo, all you have to do it is run it:

docker compose up

That should do it!

A little extra

Ok, that's a lot of output. We really only want to see the output of our app. We can run:

docker compose up --attach app

to get output only from our app container. It will look something like this:

todo_app  | 
todo_app  | > dcoker-todo@1.0.0 start:dev
todo_app  | > nodemon -L app.js
todo_app  | 
todo_app  | [nodemon] 2.0.22
todo_app  | [nodemon] to restart at any time, enter `rs`
todo_app  | [nodemon] watching path(s): *.*
todo_app  | [nodemon] watching extensions: js,mjs,json
todo_app  | [nodemon] starting `node app.js`
todo_app  | Successfully connected to the server at 'http://localhost:3000/'
todo_app  | Connected to todos as admin

Of course, todos and admin will be whatever you set them as in the .env.

Additionally, after you shut down the container, you'll still want to run

docker compose down

to stop the mongodb container.

Let me know if it works, and I hope it help!