TL;DR

In this tutorial, we will create a user-friendly URL shortener using SpringBoot and Postgres, deployed on FL0 for easy management and control. 🔗✨

Introduction

Nowadays, URLs have become an essential part of our workflow. However, long and complex URLs can be difficult to share or work with.

In this tutorial, we will build a simple-to-use URL shortener that provides a convenient way to transform long URLs into shorter, more manageable links in just one click! 🧑‍💻

We would be using Spring Boot to build our backend, Postgres as our database, both deployed simply using FL0. Then we would go ahead and build the user interface in the form of a simple Chrome Extension, which could call our APIs!

Here’s some internet humor before we get started:

Overview

Before we dive into the code, let’s take a moment to understand the high-level overview of our project.

Our URL shortener will be a Chrome extension designed to provide a seamless and delightful experience for users. Let’s walk through the user journey to get a clear picture:

1. Navigation: The user opens Chrome and visits the webpage he/she wants to shorten using our installed extension.
2. URL Shortening: Upon clicking the extension, it fetches the active tab’s URL and sends it to our shortening service. This service is a Spring Boot application hosted on FL0, which processes the URL and generates a unique path.
3. URL Construction and Copying: The extension takes this unique path, constructs the full shortened URL on the front end, displays it to the user, and it can be copied with a single click.

Here’s a high-level diagram for better understanding:

Step 0: Setting Up the Spring Boot Project

Before we begin, we need to make sure we have the following tools installed:

• Code Editor: In this tutorial, we’ll be using IntelliJ IDEA.
• JDK 17: we need to have JDK 17 installed.
• Docker Desktop (on Mac/Windows): We’ll utilize Docker to containerize our application and simplify deployment.

Now we would go ahead and set up our new Spring Boot project using Spring Initializr 🌱

1. Let’s visit start.spring.io. This is the Spring Initializr, a web-based tool that helps in creating Spring Boot projects quickly.
2. Now, we would need to configure our settings as follows:

Project Metadata: Specify the project metadata such as group, artifact, and version.

Dependencies: Add the following dependencies:

• Spring Web: To build RESTful APIs and handle HTTP requests.
• Spring Data JPA: For working with databases using Object-Relational Mapping (ORM).
• PostgreSQL Driver: To connect our application with a PostgreSQL database.
• Lombok: A library that simplifies Java code by reducing boilerplate.

3. We will select the latest stable Java version (Java 17), choose the project packaging as JAR, and select Gradle as the build tool. 🧑‍💻

4. Click on the “Generate” button to download a zip file containing the project structure and necessary files 🗂️ as shown👇

Setting Up the Project

1. We will extract the downloaded zip file to a preferred location.
2. Now we will open our code editor (IntelliJ IDEA, in our case) and import the project by selecting the extracted folder as the project directory.
3. Once the project is loaded, we would need to download the project dependencies specified in the build.gradle file. This can be done automatically in IntelliJ IDEA by clicking on the Gradle toolbar located on the right side of the editor and selecting the "Refresh" button.
4. Verify that the dependencies are successfully downloaded by checking the Gradle Console for any errors or warnings.

Step 1: Database and Config

In this step, we’ll configure the necessary files and set up the database connection for our user-friendly URL shortener. Let’s get started with the configuration setup!

Postgresql Database Setup

To run our app locally, we would also need postgresql running. So, lets set it up quickly. We create a new folder src/main/resources/local and create a new file local-postgre-docker-compose.yml

version: '3'

services:
  postgres:
    image: postgres
    restart: always
    ports:
      - 5432:5432
    environment:
      POSTGRES_DB: url_shortener
      POSTGRES_USER: user123
      POSTGRES_PASSWORD: pass123
    volumes:
      - db_data:/var/lib/postgresql/data
volumes:
  db_data:

To start our DB, in terminal navigate to the folder containing this file and run the command:

docker-compose -f local-postgre-docker-compose.yml up -d

This will start postgresql database as a docker container and we will be able to connect to it on localhost:5432 using the credentials as mentioned in the above docker file

Configuring Files and Database Connection

1. Open the application.yml file located in the src/main/resources directory. This file allows us to define properties for our application.
2. Add the following properties:

server:
  port: 8080

spring:
  datasource:
    url: jdbc:postgresql://${DB_HOST_NAME:localhost}:${DB_PORT:5432}/${DB_NAME:url_shortener}
    username: ${DB_USERNAME:user123}
    password: ${DB_PASSWORD:pass123}
  jpa:
    hibernate:
      ddl-auto: update

short-url:
  allowed-characters: ${ALLOWED_CHARS:abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789}
  key-length: ${KEY_LENGTH:6}

• The variables written as ${ENV_VARIABLE_NAME:default_value} can be set using environment variables while deployment.
• For local development we can use the default values.
• server.port: The port on which our application will run.
• spring.datasource.url: The URL for connecting to our PostgreSQL database.
• spring.datasource.username and spring.datasource.password: PostgreSQL database credentials.
• short-url.allowed-characters: The characters allowed in the generated keys. Feel free to modify or expand the character set if desired.
• short-url.key-length: The length of the generated keys for short url. We will be using length of 6 characters as key.

Now we can run our application using below command:

./gradlew bootRun

ShortUrlConfig Class

To centralize our configuration properties and make them easily accessible, let’s create a ShortUrlConfig class. This class will be annotated with @ConfigurationProperties(prefix="short-url") to bind the properties from the application.yml file to the corresponding fields in our class. Here's an example:

package com.fl0.urlshortener.config;

import lombok.Getter;
import lombok.Setter;
import org.springframework.boot.context.properties.ConfigurationProperties;
@ConfigurationProperties(prefix = "short-url")
@Getter
@Setter
public class ShortUrlConfig {
    private String allowedCharacters;
    private int keyLength;
}

This will require us to add @ConfigurationPropertiesScan on top of the main application class. So, lets add it to our UrlshortenerApplication :

package com.fl0.urlshortener;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;
@SpringBootApplication
**@ConfigurationPropertiesScan**
public class UrlshortenerApplication {
 public static void main(String[] args) {
  SpringApplication.run(UrlshortenerApplication.class, args);
 }
}

Now that we have our files configured and the database connection established, it’s time to move on to creating the necessary models and repositories.

In this step, we’ll configure the necessary files and set up the database connection for our user-friendly URL shortener. Let’s get started with the configuration setup!

Postgresql Database Setup

To run our app locally, we would also need postgresql running. So, lets set it up quickly. We create a new folder src/main/resources/local and create a new file local-postgre-docker-compose.yml

version: '3'

services:
  postgres:
    image: postgres
    restart: always
    ports:
      - 5432:5432
    environment:
      POSTGRES_DB: url_shortener
      POSTGRES_USER: user123
      POSTGRES_PASSWORD: pass123
    volumes:
      - db_data:/var/lib/postgresql/data
volumes:
  db_data:

To start our DB, in terminal navigate to the folder containing this file and run the command:

docker-compose -f local-postgre-docker-compose.yml up -d

This will start postgresql database as a docker container and we will be able to connect to it on localhost:5432 using the credentials as mentioned in the above docker file

Configuring Files and Database Connection

1. Open the application.yml file located in the src/main/resources directory. This file allows us to define properties for our application.
2. Add the following properties:

server:
  port: 8080

spring:
  datasource:
    url: jdbc:postgresql://${DB_HOST_NAME:localhost}:${DB_PORT:5432}/${DB_NAME:url_shortener}
    username: ${DB_USERNAME:user123}
    password: ${DB_PASSWORD:pass123}
  jpa:
    hibernate:
      ddl-auto: update

short-url:
  allowed-characters: ${ALLOWED_CHARS:abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789}
  key-length: ${KEY_LENGTH:6}

• The variables written as ${ENV_VARIABLE_NAME:default_value} can be set using environment variables while deployment. If not set then the default value will be used.
• For local development we can use the default values.
• server.port: The port on which our application will run.
• spring.datasource.url: The URL for connecting to our PostgreSQL database.
• spring.datasource.username and spring.datasource.password: PostgreSQL database credentials.
• short-url.allowed-characters: The characters allowed in the generated keys. Feel free to modify or expand the character set if desired.
• short-url.key-length: The length of the generated keys for short url. We will be using length of 6 characters as key.

Now we can run our application using below command:

./gradlew bootRun

ShortUrlConfig Class

To centralize our configuration properties and make them easily accessible, let’s create a ShortUrlConfig class. This class will be annotated with @ConfigurationProperties(prefix="short-url") to bind the properties from the application.yml file to the corresponding fields in our class. Here's an example:

package com.fl0.urlshortener.config;

import lombok.Getter;
import lombok.Setter;
import org.springframework.boot.context.properties.ConfigurationProperties;
@ConfigurationProperties(prefix = "short-url")
@Getter
@Setter
public class ShortUrlConfig {
    private String allowedCharacters;
    private int keyLength;
}

This will require us to add @ConfigurationPropertiesScan on top of the main application class. So, lets add it to our UrlshortenerApplication :

package com.fl0.urlshortener;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.ConfigurationPropertiesScan;
@SpringBootApplication
**@ConfigurationPropertiesScan**
public class UrlshortenerApplication {
 public static void main(String[] args) {
  SpringApplication.run(UrlshortenerApplication.class, args);
 }
}

Now that we have our files configured and the database connection established, it’s time to move on to creating the necessary models and repositories.

Step 2: Creating Entity and Repository

Next we’ll define and create the necessary models and repositories for our URL shortener. The models will represent the table structure of our shortened URLs, and the repositories will handle the database operations. Let’s dive in!

ShortUrl Entity

1. Create a new Java class named ShortUrlEntity in a new package com.fl0.urlshortener.entity
2. Define the fields for the ShortUrlEntity entity class:

package com.fl0.urlshortener.entity;

import jakarta.persistence.*;
import lombok.*;

@Entity
@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
@Table(name = "urls")
public class ShortUrlEntity {
    @Id
    @Column(name = "id", nullable = false)
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(unique = true)
    private String key;

    @Column(nullable = false, columnDefinition = "TEXT")
    private String fullUrl;

    @Column(nullable = false)
    private Long clickCount;
}

1. The ShortUrlEntity entity represents a shortened URL and is annotated with @Entity to indicate that it's a JPA entity. The @Table annotation specifies the name of the table in the database.
2. The entity has the following fields:

• id: The primary key generated automatically by the database.
• key: The unique key representing the shortened URL.
• fullUrl: The original full URL that was shortened.
• clickCount: The number of times the shortened URL has been clicked.

ShortUrlRepository

1. Create a new Java interface named ShortUrlRepository in a new package com.fl0.urlshortener.repository
2. Extend the JpaRepository interface and define custom methods for the repository:

package com.fl0.urlshortener.repository;

import com.fl0.urlshortener.entity.ShortUrlEntity;
import org.springframework.data.jpa.repository.JpaRepository;

public interface ShortUrlRepository extends JpaRepository<ShortUrlEntity, Long> {
    ShortUrlEntity findByKey(String key);
    ShortUrlEntity findByFullUrl(String fullUrl);
}

1. The ShortUrlRepository extends the JpaRepository interface provided by Spring Data JPA. It enables us to perform CRUD operations on the ShortUrlEntity easily.
2. We will also define two custom methods:

• findByKey: Retrieves a ShortUrlEntity entity based on the given key.
• findByFullUrl: Retrieves a ShortUrlEntity entity based on the given full URL.

These methods will be used in our service layer to retrieve and manipulate data.

Step 3: Creating DTOs, Utility and Service classes

Now we’ll create the data transfer objects (DTOs), a utility class and service layer. The DTOs will facilitate data transfer, the utility class will provide helpful methods and the service will handle the business logic. Let’s proceed!

DTOs (Data Transfer Objects)

1. Let’s create a new Java class named ShortUrlRequest in the com.example.urlshortener.dto package.
2. Now we will define the fields for the ShortUrlRequest class:

package com.fl0.urlshortener.dto;

import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
public class ShortUrlRequest {
    private String url;
}

1. The ShortUrlRequest DTO represents a request to create a shortened URL. It has a single field, url.
2. We will create another Java class named ShortUrlResponse in the same package.
3. Now we will define the fields for the ShortUrlResponse class:

package com.fl0.urlshortener.dto;

import lombok.Builder;
import lombok.Getter;
import lombok.Setter;

@Getter
@Setter
@Builder
public class ShortUrlResponse {
    private String key;
}

1. The ShortUrlResponse DTO represents the response after creating a shortened URL. It has a single field: key, which holds the unique key as a response.

ShortUrlUtil

We will create a new Java class named ShortUrlUtil in the com.fl0.urlshortener.util package and add the @Component annotation to the ShortUrlUtil class to make it a Spring bean:

package com.fl0.urlshortener.util;

import com.fl0.urlshortener.config.ShortUrlConfig;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

import java.util.Random;

@Component
public class ShortUrlUtil {

    private final ShortUrlConfig config;

    @Autowired
    public ShortUrlUtil(ShortUrlConfig config) {
        this.config = config;
    }

    public String generateUniqueKey() {
        int keyLength = config.getKeyLength();
        String allowedCharacters = config.getAllowedCharacters();

        StringBuilder keyBuilder = new StringBuilder();
        Random random = new Random();

        for (int i = 0; i < keyLength; i++) {
            int randomIndex = random.nextInt(allowedCharacters.length());
            keyBuilder.append(allowedCharacters.charAt(randomIndex));
        }

        return keyBuilder.toString();
    }
}

The ShortUrlUtil class is annotated with @Component to make it a Spring bean. It is also injected with the ShortUrlConfig using constructor injection.

The ShortUrlUtil class provides a single method:

• generateUniqueKey(): Generates a unique key based on the specified length and allowed characters from the configuration.

This method will be used in the service layer.

UrlShortenerService

1. Create a new Java class named UrlShortenerService in the com.fl0.urlshortener.service package.
2. Add the following methods to handle URL shortening and retrieval:

package com.fl0.urlshortener.service;

import com.fl0.urlshortener.dto.ShortUrlRequest;
import com.fl0.urlshortener.dto.ShortUrlResponse;
import com.fl0.urlshortener.entity.ShortUrlEntity;
import com.fl0.urlshortener.repository.ShortUrlRepository;
import com.fl0.urlshortener.util.ShortUrlUtil;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
import org.springframework.web.servlet.view.RedirectView;

@Service
@RequiredArgsConstructor
public class UrlShortenerService {

    private final ShortUrlRepository repository;
    private final ShortUrlUtil util;

    public ShortUrlResponse createShortUrl(ShortUrlRequest request) {
        String fullUrl = request.getUrl();

        ShortUrlEntity existingShortUrl = repository.findByFullUrl(fullUrl);

        if (existingShortUrl != null) {
            return ShortUrlResponse.builder().key(existingShortUrl.getKey()).build();
        } else {
            String newKey = util.generateUniqueKey();
            ShortUrlEntity newEntity = ShortUrlEntity.builder()
                    .key(newKey).fullUrl(fullUrl).clickCount(0L)
                    .build();
            repository.save(newEntity);
            return ShortUrlResponse.builder().key(newKey).build();
        }
    }

    public RedirectView getFullUrl(String key) {
        ShortUrlEntity entityInDb = repository.findByKey(key);
        entityInDb.setClickCount(entityInDb.getClickCount() + 1);
        repository.save(entityInDb);
        return new RedirectView(entityInDb.getFullUrl());
    }
} 

The UrlShortenerService class handles the business logic of URL shortening and retrieval. It relies on the ShortUrlRepository for database operations and the ShortUrlUtil for generating unique keys.

The createShortUrl method checks if the URL already exists in the database.

If it exists, we get the key (the path) of the URL from the database.

Otherwise, it generates a new key, saves it along with the URL in the database, and returns the newly generated key.

The getFullUrl method retrieves the original full URL based on the provided key.

It finds the key in the database, increments the click count, saves the changes, and redirects to the original full URL.

Our application is now equipped with the necessary components to handle the creation and retrieval of shortened URLs.

Step 5: Enabling Cross-Origin Resource Sharing (CORS)

To allow requests from the Chrome extension to our backend API, we need to configure Cross-Origin Resource Sharing (CORS). In this step, we’ll create a CorsConfig class in our Spring Boot application to handle CORS configuration.

1. We create a new Java class named CorsConfig in the com.fl0.urlshortener.config package.

package com.fl0.urlshortener.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.CorsRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class CorsConfig implements WebMvcConfigurer {

    @Override
    public void addCorsMappings(CorsRegistry registry) {
        registry.addMapping("/**")
                .allowedOrigins("*")
                .allowedMethods("GET", "POST");
    }
}

1. The CorsConfig class implements the WebMvcConfigurer interface, allowing us to customize the CORS configuration for our application.
2. With this configuration, our backend will allow requests from the Chrome extension, enabling communication between the extension and the API.
3. Save the CorsConfig class.

We have successfully built the CorsConfig class to handle CORS configuration in our Spring Boot application. This will ensure that our backend API can accept requests from our Chrome extension without any CORS-related issues. ✅

Next, let’s move on to build our Chrome extension. 👨🏻‍💻

Step 6: Building the Chrome Extension

In this step, we’ll create a custom Chrome extension for our URL shortener. The extension will provide a convenient way for users to shorten URLs directly from their browser. Let’s dive into the world of Chrome extension development!

1. We will create a new project named url-shortener-extension.

manifest.json

{
  "manifest_version": 3,
  "name": "URL Shortener",
  "version": "1.0",
  "description": "Shortens URLs with ease!",
  "background": {
    "service_worker": "background.js"
  },
  "action": {
    "default_popup": "popup.html",
    "default_icon": "icon.png"
  },
  "permissions": ["activeTab"],
  "icons": {
    "16": "icon.png",
    "48": "icon.png",
    "128": "icon.png"
  }
}

popup.html

<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" type="text/css" href="popup.css">
</head>
<body>
<div class="container">
    <button id="copyBtn" disabled>Copy url</button>
</div>
<script src="popup.js"></script>
</body>
</html>

popup.css

body {
    background-color: #e6f7ff;
    margin: 5px;
    font-family: Arial, sans-serif;
}

#copyBtn {
    padding: 5px 10px;
    background-color: #1890ff;
    border: none;
    color: white;
    font-size: 1.2em;
    transition: background-color 0.5s ease;
    text-align: center;
    white-space: nowrap;
    text-overflow: ellipsis;
    cursor: pointer;
}

popup.js

let shortenedUrl;

window.onload = function() {
    chrome.tabs.query({active: true, currentWindow: true}, function(tabs) {
        chrome.runtime.sendMessage(
            {message: 'fetchUrl', url: tabs[0].url},
            function(response) {
                shortenedUrl = response.url;
                document.getElementById('copyBtn').disabled = false;
            }
        );
    });javaj
};
document.getElementById('copyBtn').addEventListener('click', function() {
    navigator.clipboard.writeText(shortenedUrl).then(function() {
        console.log('Copying to clipboard was successful!');
        const btn = document.getElementById('copyBtn');
        btn.innerText = 'Success!';
        btn.style.backgroundColor = '#52c41a';
        // Close the popup after 2 seconds
        setTimeout(window.close, 2000);
    }, function(err) {
        console.error('Could not copy text: ', err);
    });
});

background.js

const backendUrl = 'https://localhost:8080';
// Don't forget to replace this url with the actual backend url after deployment

chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
    if (request.message === 'fetchUrl') {
        fetch(backendUrl + 'createUrl', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({ url: request.url })
        })
            .then(response => response.json())
            .then(data => {
                sendResponse({url: backendUrl + data.key});
            })
            .catch(err => console.error('Error: ', err));
        return true;
    }
});

Now lets load the extension in our Chrome browser by following these steps:

1. Open the Chrome browser.
2. Go to chrome://extensions/.
3. Enable the “Developer mode” toggle on the top right corner.
4. Click on the “Load unpacked” button.
5. Select the url-shortener-extension directory.
6. The extension will be loaded and available in the Chrome browser.

We’ve successfully built the Chrome extension for our URL shortener.

Now let’s go ahead and dockerize our application.

Step 7: Dockerizing the App

Now we’ll dockerize our application, making it easy to deploy and run in a containerized environment. Let’s get started!

Dockerfile

We create a new file named Dockerfile in the root directory of our project.

Here we specify the instructions for building the Docker image of our app for deployment.

# Start with a base image containing Java runtime (AdoptOpenJDK)
FROM openjdk:17-jdk-slim AS build

# Set the working directory in the image to "/app"
WORKDIR /app

# Copy the Gradle executable to the image
COPY gradlew ./

# Copy the 'gradle' folder to the image
COPY gradle ./gradle

# Give permission to execute the gradle script
RUN chmod +x ./gradlew

# Copy the rest of the application source code
COPY . .

# Use Gradle to build the application
RUN sh ./gradlew build

# Set up a second stage, which will only keep the compiled application and not the build tools and source code
FROM openjdk:17-jdk-slim

# Set the working directory to '/app'
WORKDIR /app

# Copy the jar file from the first stage
COPY --from=build /app/build/libs/*.jar app.jar

# Set the startup command to execute the jar
CMD ["java", "-jar", "/app/app.jar"]

Docker Compose

Now we will create a docker-compose in the project’s root directory.

version: '3.8'
services:
  url-shortener-backend:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8080:8080"

This docker-compose.yml file defines the service url-shortener-backend . The service is based on the configuration in the Dockerfile. It maps the container's port 8080 to the host's port 8080.

Let’s now navigate to the next section and explore hosting our backend and database with FL0!

Step 8: Hosting our Backend and DB with FL0

Now we would go ahead and host our application with the help of FL0

Setting Up FL0 Database

1. In the FL0 dashboard, we would need to create a new project.
2. We need to click on “Create a Postgres database”

3. Once the database is created, FL0 will provide us with the necessary database connection details, including the connection URL, username, and password.

4. Add Database Connection Credentials as Environment Variables in fl0-url-shortener-backend

And…Done ✅

Our project is hosted on FL0 successfully.

Conclusion

In this tutorial successfully built a link shortener chrome extension along with it’s backend and database and hosted it using FL0. 🎉

You may find the repository link here https://github.com/dalefl0/fl0-url-shortener-backend.

Moreover, here’s the link for the Chrome Extension if you want to use it yourself https://github.com/dalefl0/URL-Shortener-Chrome-Extension

You may visit https://fl0.com/ to start building and deploying your applications! 🚀

Building a User-Friendly URL Shortener Using Spring Boot, Postgres, and FL0 was originally published in FL0 Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

TLDR;

In this tutorial, we’ll explore how to seamlessly integrate Stripe payment gateway into our full-stack applications, and effortlessly host them on FL0. 🚀

Introduction

Whether it be an e-commerce or a SaaS application, payment gateways are a central component of our projects. 💳

In this guide, we will explore how to simplify these integrations, specifically focusing on Stripe Checkout for online payment processing.

Stripe’s developer-friendly API ensures secure and efficient transactions while cutting down on our development time.

Just for example, we have taken the case of a SaaS applications payment page.

We would be using NodeJs for the backend and Postgres as our database. On the frontend we are using ReactJs with vite.

Later we would go ahead and effortlessly host our project on FL0. ⬆️

So, let’s start with a pinch of humor:

Overview

🧑‍💻 In this tutorial, we will create a simple demo application where a user could sign up, select their plan, and checkout with their credit card.

For this, we would need to create 2 separate repositories, one for our backend and another one for frontend.

Folder Structure

🗂️ Here’s how both of our folder structures would look like, just for reference:

Now, let’s get started.

Step 1: Setting Up the Backend

For the sake of efficiency, in this tutorial, we’ll leverage the “fl0zone/blog-express-pg-sequelize” template.

Then we would remove any files or folders not important for our project. 🧑‍💻

For a more comprehensive understanding of the tutorial, you may want to refer to this blog post:

https://blog.fl0.com/building-a-software-startup-on-fl0-part-1-f0624174e738

Our template encapsulates a basic Node.js application and a dockerized PostgreSQL database.

Here is the corresponding docker-compose.yaml file for our setup 🐳:

version: "3"
services:
  app:
    build:
      context: .
      target: development
    env_file: .env
    volumes:
      - ./src:/usr/src/app/src
    ports:
      - 8081:80
    depends_on:
      - db
  db:
    image: postgres:14
    restart: always
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: admin
      POSTGRES_DB: my-startup-db
    volumes:
      - postgres-data:/var/lib/postgresql/data
    ports:
      - 5432:5432
volumes:
  postgres-data:

Now we would go ahead and install some essential packages 📦

npm install bcrypt cookie-parser cors jsonwebtoken pg-hstore stripe

Now, we would need to get our Stripe API keys 🔑. For this we would need to create a new account on Stripe.

Here we would be using Test Mode for demo.

Here are the list of environment variables we would need for this project.

.env.example

STRIPE_PUBLISHABLE_KEY=
STRIPE_SECRET_KEY=
POSTGRES_DB_URI=
secretKey=
CLIENT_URL=

Step 2: Creating Database Models

Let’s begin by setting up our database now. 🐘

Since we’re utilizing the Sequelize ORM, we’ll need to create a model for our user data.

Here’s the code for our model 👇

models/userModel.js

module.exports = (sequelize, DataTypes) => {
  const User = sequelize.define(
    "user",
    {
      email: {
        type: DataTypes.STRING,
        unique: true,
        isEmail: true, //checks for email format
        allowNull: false,
      },
      password: {
        type: DataTypes.STRING,
        allowNull: false,
      },
      tier: {
        type: DataTypes.STRING,
        allowNull: true,
      },
    },
    { timestamps: true }
  );
  return User;
};

Step 2: Setting up the Routes

Now, let’s go ahead and create our routes

POST /login - Helps to log in user and store the session

POST /signup - Helps create a new account

POST /create-checkout-session - Generates and Returns the stripe checkout page link

These 3 routes are separated into 2 files as follows:

routes/userRoutes.js

const express = require("express");
const userController = require("../controllers/userController");

const { signup, login } = userController;
const userAuth = require("../middleware/userAuth");
const router = express.Router();
router.post("/signup", userAuth.saveUser, signup);
router.post("/login", login);
module.exports = router;

routes/stripeRoute.js

const express = require("express");
const { updatePlan } = require("../controllers/stripeController");

const router = express.Router();
router.post("/create-checkout-session", updatePlan);
module.exports = router;

Step 3: Setting Up User Profile

🧑‍💻 For setting up the user profile, first we will define a middleware to check if the email address of a new user already exists in the database during signup.

middleware/userAuth.js

//importing modules
const express = require("express");
const db = require("../models");

Then we would go ahead and define our login and signup functions 👇

controllers/userController.js

const bcrypt = require("bcrypt");
const db = require("../models");
const jwt = require("jsonwebtoken");

const User = db.users;
const signup = async (req, res) => {
  try {
    const { email, password } = req.body;
    console.log(email);
    const data = {
      email,
      password: await bcrypt.hash(password, 10),
    };
    //saving the user
    const user = await User.create(data);
    if (user) {
      let token = jwt.sign({ id: user.id }, process.env.secretKey, {
        expiresIn: 1 * 24 * 60 * 60 * 1000,
      });
      res.cookie("jwt", token, { maxAge: 1 * 24 * 60 * 60, httpOnly: true });
      console.log("user", JSON.stringify(user, null, 2));
      console.log(token);
      return res.status(201).send(user);
    } else {
      return res.status(409).send("Details are not correct");
    }
  } catch (error) {
    console.log(error);
  }
};

// Login Authentication
const login = async (req, res) => {
  try {
    const { email, password } = req.body;
    const user = await User.findOne({
      where: {
        email: email,
      },
    });
    if (user) {
      const isSame = await bcrypt.compare(password, user.password);
      if (isSame) {
        let token = jwt.sign({ id: user.id }, process.env.secretKey, {
          expiresIn: 1 * 24 * 60 * 60 * 1000,
        });
        res.cookie("jwt", token, { maxAge: 1 * 24 * 60 * 60, httpOnly: true });
        //send user data
        return res.status(201).send(user);
      } else {
        return res.status(401).send("Authentication failed");
      }
    } else {
      return res.status(401).send("Authentication failed");
    }
  } catch (error) {
    console.log(error);
  }
};
module.exports = {
  signup,
  login,
};

Step 4: Setting Up Stripe Checkout

This is where we will integrate Stripe Checkout into our application.

We will use the Stripe API to manage payments and handle user subscriptions.

The following code creates a new Stripe checkout session. 💳

We will provide it with the payment method type, the product data, and the quantity.

We also need to specify the URLs where the user will be redirected upon a successful payment or if they cancel the transaction.

And, the server will respond back with the URL for the Stripe Session if everything is fine. ✅

controllers/stripeController.js

const db = require("../models");
const Stripe = require("stripe");

const User = db.users;
require("dotenv").config();
const stripe = Stripe(process.env.STRIPE_SECRET_KEY);
const updatePlan = async (req, res) => {
  try {
    const { email, product } = req.body;
    const session = await stripe.checkout.sessions.create({
      payment_method_types: ["card"],
      line_items: [
        {
          price_data: {
            currency: "usd",
            product_data: {
              name: product.name,
            },
            unit_amount: product.price * 100,
          },
          quantity: product.quantity,
        },
      ],
      mode: "payment",
      success_url: `${process.env.CLIENT_URL}/success`,
      cancel_url: `${process.env.CLIENT_URL}/`,
    });
    //find a user by their email
    const user = await User.findOne({
      where: {
        email: email,
      },
    });
    if (user) {
      await user.update({ tier: product.name });
      return res.send({ url: session.url });
    } else {
      return res.status(401).send("User not found");
    }
  } catch (error) {
    console.log(error);
  }
};
module.exports = {
  updatePlan,
};

At last, we would need to add all our routes to our entry point, which is server.js

server.js

const cors = require("cors");
const express = require("express");
require("dotenv").config();
const cookieParser = require("cookie-parser");
const db = require("./models");
const userRoutes = require("./routes/userRoutes");
const PORT = process.env.PORT || 8080;
const stripeRoute = require("./routes/stripeRoute");
const app = express();

// Middlewares
app.use(express.json());
app.use(express.urlencoded({ extended: true }));
app.use(cookieParser());
app.use(cors());

// Routes
app.use("/api/v1/users", userRoutes);
app.use("/api/v1/stripe", stripeRoute);
app.listen(PORT, () => {
  console.log("Server started at port 8080");
  try {
    db.sequelize.sync({ force: true }).then(() => {
      console.log("db has been re sync");
    });
  } catch (error) {}
});

And we are done with the backend ✅

Now let’s go ahead and try to deploy it on FL0. 🔼

Step 5: Deploying with FL0

🚀 For deploying our project to FL0 we will start with pushing our repo to a new GitHub repository first.

This is the link to our repository for reference: https://github.com/dalefl0/stripe-fl0-backend

Now we would head on to app.fl0.dev to start deploying.

• Here we would need to create a new project, let’s name it stripe-fl0 for example.
• Now we would need to create a new Postgres instance. With Fl0, this takes less than 30 seconds! ⏳

• After we have our database all set up, we would need to go ahead and deploy our backend in the same project.

• After the backend is deployed we would need to import our database connection string as shown above ☝️

🙌 Now we have our backend up and running.

Time for the UI ✨

Step 6: Setting up the Frontend

For setting up the frontend we would get started with the template-react-vite. ⚡️

This includes everything we need to get our React-Vite project up and running.

Now we would go ahead and install a few packages.

npm install @heroicons/react axios react-router-dom
npm install postcss tailwindcss autoprefixer --save-dev

Step 7: Setting up the Frontend

To build our UI components quickly we would take help of the Pricing Section Component and Sign-in and Registration Component from tailwind UI.

For the sake of brevity, we will only look at the important functions of the frontend.

The complete project could be found at: https://github.com/dalefl0/stripe-fl0-frontend

Now, we would need to add a function to handle stripe checkouts

src/components/PricingPlans.jsx

...

const handleCheckout = (product) => {
    axios
      .post(
        `https://stripe-fl0-backend-dev.fl0.io/api/v1/stripe/create-checkout-session`,
        {
          email,
          product,
        }
      )
      .then((res) => {
        if (res.data.url) {
          setTier(product.name);
          localStorage.setItem("tier", product.name);
          window.location.href = res.data.url;
        }
      })
      .catch((err) => navigate("/cancel"));
  };
  
...

This function calls our backend’s /create-checkout-session route, receives a link, and redirects the user to the checkout page. 📄

Apart from this, we need to also connect our signup and login pages to respective routes and store the user data in localstorage.

Step 8: Deploying the Frontend

For frontend we would need to again create a new repository and deploy it in the same project in a similar manner.

We would then need to add the VITE_APP_API_BASE_URL environment variable to the frontend deployment which should be set to the URL of our backend.

We would also need to set the CLIENT_URL environment variable in the backend to the hosted URL of the frontend.

Once done, our FL0 project would look like this 👇

Now, let’s go ahead and try our application using this live demo link: https://stripe-fl0-frontend-q8oo-dev.fl0.io/

Wrapping up

Thanks for sticking by till the end!

In this tutorial, we learnt how to build payment pages by integrating Stripe Checkout easily into our full-stack applications. 🎉

We also did blazingly-fast deployments of our project using FL0.

To get started with building your own applications with payment capabilities, head on to fl0.com 🚀

Building Seamless Payment Interfaces with Stripe and FL0 was originally published in FL0 Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

TLDR;

By the end of this guide, we will have a fully functioning Slack bot that can answer our questions about FL0 and its features using AI 🤖✨.

Introduction

The advent of OpenAI’s API has empowered countless developers to create sophisticated chatbots without breaking a sweat 🧑‍💻.

We’ve noticed that there’s a considerable amount of curiosity within the developer community regarding the workings and features of FL0. This gave us the idea to build a simple chatbot using the GPT API.

In this article, we would be building a slack chatbot named FL0Bot which could answer questions regarding FL0. 💬

We would be using NodeJs for our backend and Postgres as database. Then we would be deploying our application effortlessly with the help of FL0 🚀.

As we prepare to embark on this journey, let’s kick things off with a little humor. Here’s an xkcd comic strip to lighten the mood 👇

Getting Started

Let’s start with building our chatbot 💬.

To speed up things, in this tutorial we would be using the “fl0zone/blog-express-pg-sequelize” template.

You may refer to this blog for more details regarding the tutorial 👇

https://blog.fl0.com/building-a-software-startup-on-fl0-part-1-f0624174e738

In this template we have our basic NodeJs application and postgres database dockerized.

Here’s our docker-compose.yaml file for the same 🐳

version: "3"
services:
  app:
    build:
      context: .
      target: development
    env_file: .env
    volumes:
      - ./src:/usr/src/app/src
    ports:
      - 8081:80
    depends_on:
      - db
  db:
    image: postgres:14
    restart: always
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: admin
      POSTGRES_DB: my-startup-db
    volumes:
      - postgres-data:/var/lib/postgresql/data
    ports:
      - 5432:5432
volumes:
  postgres-data:

Folder Structure

Before we get started, here’s a look at our final project folder structure for reference 📂

And here’s a high level overview of what we are gonna build 👀

Now, let’s delve into the code 🧑‍💻

Step 1: Project Setup

After we have created our new project using the above template, we would first need to install a few packages.

npm install axios @slack/bolt openai uuid

Now, we would need to get our OpenAI API key 🔑.

For this, we would need to create our account at platform.openai.com.

After this, we would select the “API” option, and click on “View API Keys” in account options.

Now, we would need to go ahead and create a new API key as shown below 👇

Step 2: Config Setup

We would create a .env.example file to list the environment variables just for reference 👇

NODE_ENV=development
DATABASE_URL=postgres_url
BOT_SYSTEM=system_prompt
OPENAI_API_KEY=open_api_key
SLACK_WEBHOOK=slack_webhook

Then, we would need to go ahead and add these variables to our already present config file 📝

src/config/index.js

module.exports = {
  "local": {
    "use_env_variable": "DATABASE_URL",
    "openai_api_key": "OPENAI_API_KEY",
    "bot_system" : "BOT_SYSTEM",
    "slack_webhook" : "SLACK_WEBHOOK",
    synchronize: true
  },
  "development": {
    "use_env_variable": "DATABASE_URL",
    "openai_api_key": "OPENAI_API_KEY",
    "bot_system" : "BOT_SYSTEM",
    "slack_webhook" : "SLACK_WEBHOOK",
    synchronize: true
  },
  "production": {
    "use_env_variable": "DATABASE_URL",
    "openai_api_key": "OPENAI_API_KEY",
    "bot_system" : "BOT_SYSTEM",
    "slack_webhook" : "SLACK_WEBHOOK",
    synchronize: true
  }
}

Step 3: Creating Models

Now let’s get started with setting up our database. As we are using sequelize ORM, we would need to create models for our postgres database 🐘.

Here we would need to create a Chat in which we would be storing all the communication between the Fl0Bot and User.

Everytime a new request is made, we SELECT the recent chats from this database and send it for reference to the Fl0Bot. 💬

src/models/chat.js

'use strict';
const { Sequelize, DataTypes } = require('sequelize');

module.exports = (sequelize) => {
  const Chat = sequelize.define(
    'Chat',
    {
      chat_id: {
        type: DataTypes.UUID,
        primaryKey: true,
        defaultValue: Sequelize.UUIDV4,
      },
      person_id: {
        type: DataTypes.STRING,
        allowNull: false,
      },
      role: {
        type: DataTypes.STRING,
      },
      content: {
        type: DataTypes.STRING(10000)
      },
      time_created: {
        type: DataTypes.DATE,
        defaultValue: DataTypes.NOW,
      },
      time_updated: {
        type: DataTypes.DATE,
        defaultValue: DataTypes.NOW,
      },
    },
    {
      tableName: 'chats', // Specify the table name explicitly if different from the model name
      timestamps: false, // Disable timestamps (createdAt, updatedAt)
      hooks: {
        beforeValidate: (chat, options) => {
          // Update the time_updated field to the current timestamp before saving the record
          chat.time_updated = new Date();
        },
      },
    }
  );
  return Chat;
};

Step 4: Creating the Chat Bot

Now let’s move on to writing the code for our ChatBot! 🤖

First we would create our handleAppMention function.

Here we’re parsing the text message, excluding any mentions, then looking for an existing user chat session or creating one if it doesn’t exist.

We’re fetching the last five chat messages to maintain the context of the conversation. 💬✨

Here we’re leveraging OpenAI’s API to get a completion response to the user’s input. 🤖

We are also adding a system in the conversation which is in the config.bot_system. This provides GPT the context about Fl0.

Example GPT System Prompt

You are a bot that answers queries only around a specific product: fl0 and you will tell nothing about any other product or tools. FL0 is a platform for easily deploying your code as containers. Just push code to your repo and FL0 will build and deploy your app to a fully managed infrastructure complete with databases, logging, multiple environments and lots more!

src/index.js

async function handleAppMention({event}) {
const mentionRegex = /<@[\w\d]+>/g; // Regex pattern to match the mention
  const msg = event.text.replace(mentionRegex, '');
  const person_id = event.user;
  const query = msg;
  try {
    const userExists = await Chat.findOne({ where: { person_id: person_id }, raw: true });
    if (!userExists) {
      const dbChat = await Chat.create({ person_id: person_id, role: 'system', content: process.env[config.bot_system] });
    }
    const chats = await Chat.findAll({ where: { person_id }, order: [['time_created', 'DESC']], limit: 5, raw: true });
    const chatsGpt = chats.map((item) => ({ role: item.role, content: item.content }));
    chatsGpt.push({ role: 'user', content: query });
    const response = await openai.createChatCompletion({
      model: 'gpt-3.5-turbo',
      messages: chatsGpt,
    });
    await Chat.bulkCreate([
      { person_id, role: 'user', content: query },
      { person_id, role: 'assistant', content: response.data.choices[0].message.content }
    ]);
    await axios.post(process.env[config.slack_webhook], {text: response.data.choices[0].message.content});
    return response.data.choices[0].message.content
  } catch (error) {
    console.log("ERROR",error)
    return 'Failed to process chat';
  }
}

🚗 Coming to our routes, we’ve set up an endpoint (/slack/action-endpoint) for Slack's action-events, in response to app_mention events.

And we are returning the response from handleAppMention function.

This response would be sent back by our Slack Bot.

src/index.js

const express = require('express')
const { sequelize, Chat } = require('./models');

const process = require('process');
const env = process.env.NODE_ENV || 'development';
const config = require(__dirname + '/config/index.js')[env];
const axios = require('axios');

const app = express()
app.use(express.json());

const { Configuration, OpenAIApi } = require("openai");
const configuration = new Configuration({
  apiKey: process.env[config.openai_api_key],
});
const openai = new OpenAIApi(configuration);
const port = process.env.PORT ?? 3000;
app.post('/slack/action-endpoint', async (req, res) => {
  const { challenge } = req.body;
  if (challenge) {
    res.status(200).send(challenge);
  } else {
      try {
        switch(req.body.event.type) {
          case 'app_mention':
            const response = handleAppMention(req.body)
            res.status(200).json({ message: 'Success' });
            break
          default:
            res.status(400).json({ message: 'Bad Request' });
            break
        }
      } catch (error) {
        console.error(`Error processing Slack event: ${error}`);
        res.status(500).json({ message: error });
      }
  }
});
app.listen(port, async () => {
  console.log(`Example app listening on port ${port}`)
  try {
    await sequelize.sync({ force: false });
    await sequelize.authenticate();
    sequelize.options.dialectOptions.ssl = false;
    await sequelize.sync({ force: true});
    console.log('Connection has been established successfully.');
  } catch (error) {
    console.error('Unable to connect to the database:', error);
  }
});

Step 5: Deploying with Fl0

Now that we have a functional API and database, its time to deploy them to a server! 🚀

In this tutorial, we’re utilizing FL0, a platform expertly designed for straightforward deployment of dockerized NodeJS applications, fully integrated with a database.

We would just need to push our repo to GitHub.🫸

Now we would be deploying our project just by “Connecting our GitHub account" and selecting our project.

Then we would be adding our environment variables listed in .env.example file.

You may find a detailed process of deployment in this blog 👉 https://blog.fl0.com/building-a-software-startup-on-fl0-part-1-f0624174e738

Step 6: Setting up Slack App

Now that our project is set up, let’s create our Slack App.

We would visit https://api.slack.com/apps and click on Create New App.

We would name our bot “FL0Bot” 😁

In the Event Subscriptions section, we would enable events, set the request URL, and subscribe to bot events: app_mention

We would also need to get our webhook and pass it as an environment variable to our FL0 hosting.

Conclusion

So, there we have it — a completely operational chatbot tailored to answer questions about FL0 and its features, built using NodeJs, Postgres, and OpenAI's GPT, and seamlessly deployed with FL0!

Here’s the link to our repository for reference ➡️ Visit FL0Bot Repo

The power of OpenAI’s APIs and quick deployments with FL0, make it effortless to build our own AI bots 🚀🎉.

Head on to fl0.com to start building your own bots 🧑‍💻.

Building a Slack ChatBot with GPT API, NodeJs, and FL0 was originally published in FL0 Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

This article extends from where we left off, but adds a critical element: debugging!

Before continuing, please have a read of the previous article or clone the example repository (be sure to check out the branch called multi-stage-dockerfile)!

We’re going to cover the following:

1. Updating package.json with a debug script
2. Creating a debug version of our docker-compose.yml file
3. Attaching a debugger to the container
4. Automating Visual Studio Code to start and stop containers

Deploying to the cloud

If you want a really simple way to deploy your container to a scalable infrastructure, check out FL0! It’s a platform that makes it as simple as possible to go from code to cloud, complete with dev/prod environments, databases and more. All you have to do is commit your code and FL0 will handle the rest.

FL0 - backend engineering, supercharged

Creating the debug script

Open up package.json and take a look at the scripts section. There’s currently a start and a start:dev option. Our Dev script uses Nodemon to watch for changes and reload the server as needed. Nodemon also accepts a flag called --inspectto run in debug mode. If you’re interested in some thrilling reading, learn more in the Node.js docs!

Open up your package.json file and add a new script called start:debug.

{
  ...
  "scripts": {
    ...
    "start:debug": "nodemon -r dotenv/config --inspect=0.0.0.0 src/index.js",
  },
  ...
}

It’s the same as our start:dev script, but we pass the --inspect flag and the IP address 0.0.0.0, meaning we are allowing debugger connections from any IP address.

Note: If you try and run this script in your terminal, you’ll get an error that the database can’t be found. It needs to be run with Docker Compose so that the database is also provisioned.

Creating a debug Docker Compose file

Docker Compose has a great feature called overrides which allows you to have multiple docker-compose.yml files in your codebase, one overriding parts of the other. This means you can have a base docker-compose.yml and a docker-compose.debug.yml file that overrides things like the port and the start command. Let’s go and set that up!

Create a new file in your repo called docker-compose.debug.yml and paste in the following:

version: '3.4'

services:
  app:
    ports: 
     - 3000:80
     - 9229:9229
    command: ["npm", "run", "start:debug"]

You can see it’s pretty minimal. All it does is override the ports and command section of our main file. And the command we’re running is our newly created start:debug command! The port 9229 is the default port for debugging with Node.js, and we map that from the container to our host machine so that our IDE can connect properly.

If we ran docker compose up right now it would only use our original YAML file. But if we run the following, it will use both files:

$ docker compose -f docker-compose.yml -f docker-compose.debug.yml up

Go ahead and try that out! In the terminal output you should see a couple of important lines that indicate Node was started in debug mode successfully:

[nodemon] starting `node -r dotenv/config --inspect=0.0.0.0 src/index.js`
Debugger listening on ws://0.0.0.0:9229/51b990e4-17fd-40ef-9a4c-784f033329d2

If you see that, we’re kicking goals! If not, maybe scroll through Instagram for a while and see if it fixes itself. If you’re really stuck, leave a comment below and I’ll get back to you!

Attaching a debugger to the container

While there are lots of available debuggers, we’re going to focus on Visual Studio Code (VSC) in this article. With your containers up and running in Debug mode, create a folder and file in the root of your repo called .vscode/launch.jsonand add this content:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        
        
    ]
}

With this file open, click cmd+shift+p (ctrl+shift+p) to open the command palette and select an option called Debug: Add Configuration.... From the list, select Node.js: Attach to Remote Program.

You should see some JSON added to your launch.json file. Modify the file as follows:

1. Set the address property to “localhost” as we have mapped port 9229 from our container to our host machine
2. Set the remoteRoot property to /usr/src/app as this is our Dockerfile’s WORKDIR and contains all our source code (inside the container)
3. Set a new property called restart so that when we make a code change and nodemon restarts the server, we don’t lose our debugger connection

Your file should look like this:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "address": "localhost",
            "localRoot": "${workspaceFolder}",
            "name": "Attach to Remote",
            "port": 9229,
            "remoteRoot": "/usr/src/app",
            "request": "attach",
            "skipFiles": [
                "<node_internals>/**"
            ],
            "type": "node",
            "restart": true
        }
    ]
}

Once you save the file you’ll see an option in the Debug panel to launch your configuration. Go ahead and click it! Just be sure your containers are running in debug mode first.

If all goes well you should see an orange bar at the bottom of VSC. Open index.js and set a couple of breakpoints in the request handlers:

In your browser, load up http://localhost:3000/. If your debugger is working, it should pause at the breakpoints you just set. Congratulations, you just attached a debugger to a Docker container! But don’t get overly attached just yet, we still have more to do…

Automating Visual Studio Code to start and stop containers

What we’ve got so far is great, but it requires some manual steps. Starting our containers, running the debugger, disconnecting the debugger, stopping the containers. If you’re happy with this…that’s fine! It definitely gives you the most control. But if you’d like to automate these steps, read on…

Create a new file in your .vscode folder called tasks.json and update it to look like this:

{
    // See https://go.microsoft.com/fwlink/?LinkId=733558
    // for the documentation about the tasks.json format
    "version": "2.0.0",
    "tasks": [
        {
            "type": "docker-compose",
            "label": "docker-compose: debug",
            "dockerCompose": {
                "up": {
                    "detached": true,
                    "build": true
                },
                "files": [
                    "${workspaceFolder}/docker-compose.yml",
                    "${workspaceFolder}/docker-compose.debug.yml"
                ]
            }
        },
        {
            "type": "docker-compose",
            "label": "docker-compose: down",
            "dockerCompose": {
                "down": {}
            }
        }
    ]
}

The first task called docker-compose: debug will start our containers using the docker-compose.debug.yml configuration, and the second will stop them again. Creating tasks like this means we can call them from our launch.json configuration. Open up your launch config and add a couple of new lines:

{
    ...
    "configurations": [
        {
            ...
            "preLaunchTask": "docker-compose: debug",
            "postDebugTask": "docker-compose: down"
        }
    ]
}

These new lines will run before and after the debugger starts, meaning our containers will start and stop automatically! Go ahead and try it out, but make sure your containers are stopped first. Check out the video below to see it in action.

James Harrison on Twitter: "Debugging a Node.js app running inside a Docker container complete with hot-reloading and auto start/stop! pic.twitter.com/g22mGOrhOo / Twitter"

Debugging a Node.js app running inside a Docker container complete with hot-reloading and auto start/stop! pic.twitter.com/g22mGOrhOo

Thanks for reading! I’d love to hear your questions, suggestions and feedback so please don’t hesitate to leave a comment.

The best way to debug a Node.js app running in a Docker container was originally published in FL0 Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

Here’s the list of things we wanted to make sure our Dockerfile could do:

1. Run locally with dev dependencies
2. Hot-reload when code is changed on our machine
3. Build a production-ready version that excludes dev dependencies
4. Produce in a reasonably small container image file size
5. Edit: Debugging with breakpoints!

Seems simple enough, right? Well there are a lot of blog posts out there for each one of those dot points, but we aim to put them all together in a simple guide.

Getting Started

Example Repository

We’re going to use the fl0zone/blog-express-pg-sequelize from a previous blog post as our starting point. Check out that code, and make sure to use the branch called building-deploying-30-mins!

And if you want to skip ahead to the answers, you can find the completed code from this article in the same repo on the multi-stage-dockerfile branch.

Environment Variables

Copy the .env.example file in the root of the repo and call it .env.

Deploying to the cloud

If you want a really simple way to deploy your container to a scalable infrastructure, check out FL0! It’s a platform that makes it as simple as possible to go from code to cloud, complete with dev/prod environments, databases and more. All you have to do is commit your code and FL0 will handle the rest.

FL0 - backend engineering, supercharged

The Basics

Our sample repository already has a basic docker-compose.yml file which is currently being used to spin up a local Postgres database. To run our app, use these commands:

$ npm install
$ docker compose up -d
$ npm run start:dev

Verify your app is working by visiting http://localhost:3000/ in your browser.

Now, instead of running our app on our local machine, we want to run it inside a Docker container. Let’s start by creating a file called Dockerfile in the root of the repository:

# Use a Node.js base image so we don't have to install a bunch of extra things
FROM node:16

WORKDIR /usr/src/app

# Copy the package.json and package-lock.json files over
# We do this FIRST so that we don't copy the huge node_modules folder over from our local machine
# The node_modules can contain machine-specific libraries, so it should be created by the machine that's actually running the code
COPY package*.json ./

# Now we run NPM install, which includes dev dependencies
RUN npm install

# Copy the rest of our source code over to the image
COPY ./src ./src

EXPOSE 80

# Run our start:dev command, which uses nodemon to watch for changes
CMD [ "npm", "run", "start:dev" ]

The comments in the file explain each step. It’s a pretty simple Dockerfile!

Next, in order to use this Dockerfile we need to modify our docker-compose.yml and add a new service called app that uses the Dockerfile.

version: '3'
services:
  app:
    build: .
    env_file: .env
    ports: 
     - 3000:80
    depends_on:
     - db
  db:
    image: postgres:14
    restart: always
    environment:
      POSTGRES_USER: ${PGUSER}
      POSTGRES_PASSWORD: ${PGPASSWORD}
      POSTGRES_DB: ${PGDATABASE}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    ports:
      - 5432:5432
volumes:
  postgres-data:

As you can see, it specifies the current directory as the build context (which means it reads our new Dockerfile), passes in the .env file we already have, maps port 3000 of our local machine to port 80 of the Docker container and makes sure the db service is already running before starting.

Two last change to make, and they’re both to our .env file.

1. The PORT variable needs to be set to 80 instead of 3000, because our Dockerfile exposes 80 and then gets mapped to 3000 on our local machine with the docker-compose.yml file.
2. The DATABASE_URL needs to be updated to point to the db service instead of localhost. This is because comms between our app and database is now happening between two containers, not from our machine into a Docker image.

Make sure your .env file looks like this:

NODE_ENV=local
PORT=80
PGUSER=admin
PGPASSWORD=admin
PGDATABASE=my-startup-db
DATABASE_URL=postgres://admin:admin@db:5432/my-startup-db

Let’s test it out! Open up a terminal and run the following command:

$ docker compose up

Verify it’s working by reloading http://localhost:3000/ in your browser.

Hot-Reloading

This is great, but if you make a change to your code you will see that the Docker image isn’t being updated. This is because we copied the source code over, and there is one copy on our local machine and another in the Docker image.

To fix this, we can mount a volume on our Docker image so that our local machine and container both share the same code. Update your docker-compose.yml file to look like this, noticing the volumes section:

version: '3'
services:
  app:
    build: .
    env_file: .env
    ports: 
     - 3000:80
    volumes:
      - ./src:/usr/src/app/src
    depends_on:
     - db
  db:
    image: postgres:14
    restart: always
    environment:
      POSTGRES_USER: ${PGUSER}
      POSTGRES_PASSWORD: ${PGPASSWORD}
      POSTGRES_DB: ${PGDATABASE}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    ports:
      - 5432:5432
volumes:
  postgres-data:

Now, if we make a change to our source code, we can refresh the browser and see the changes updated instantly! Run this to make the changes take effect:

$ docker compose up --build

Building for Production

The solution we have so far is great for working locally, but there are a couple of problems if we want to use this for Production. The image size is way too big. Run docker container ls -s to see your app container is probably around 800mb). The other problem is that we ran npm install, which includes dev dependencies and things we may not want to ship.

One of the great things about Docker is its ability to have multi-stage builds inside a single Dockerfile. This means we can keep our Development build, and do some optimization for production. And what’s even better is we can copy files from one “stage” into another. Here’s what we’ll do:

1. Keep our “Development” stage as-is
2. Create a new “Builder” stage that extends from the “Development” stage but removes the node_modules folder and runs an NPM clean install with production-only dependencies
3. Create a “Production” stage using a much smaller Docker image and copy the built files across from the “Builder” stage

Open up your Dockerfile and alter it to look like this:

# Use a Node.js base image so we don't have to install a bunch of extra things
FROM node:16 as development

WORKDIR /usr/src/app

# Copy the package.json and package-lock.json files over
# We do this FIRST so that we don't copy the huge node_modules folder over from our local machine
# The node_modules can contain machine-specific libraries, so it should be created by the machine that's actually running the code
COPY package*.json ./

# Now we run NPM install, which includes dev dependencies
RUN npm install

# Copy the rest of our source code over to the image
COPY ./src ./src

EXPOSE 80

# Run our start:dev command, which uses nodemon to watch for changes
CMD [ "npm", "run", "start:dev" ]

# "Builder" stage extends from the "development" stage but does an NPM clean install with only production dependencies 
FROM development as builder
WORKDIR /usr/src/app
RUN rm -rf node_modules
RUN npm ci --only=production
EXPOSE 80
CMD [ "npm", "start" ]
 
# Final stage uses a very small image and copies the built assets across from the "builder" stage
FROM alpine:latest as production
RUN apk --no-cache add nodejs ca-certificates
WORKDIR /root/
COPY --from=builder /usr/src/app ./
CMD [ "node", "src/index.js" ]

We now have three FROM statements, each extending on from the last. Each stage has a different CMD as well, so we can run with watch mode turned on in Development but use Node directly in Production.

If we were to build this Dockerfile now, it would execute all three stages. Which is great except when we want to run something in Development. To do that, we need to change our docker-compose.yml file to specify which target to build. Open it up and change it to look like this:

version: '3'
services:
  app:
    build:
      context: .
      target: development
    env_file: .env
    ports: 
     - 3000:80
    volumes:
      - ./src:/usr/src/app/src
    depends_on:
     - db
  db:
    image: postgres:14
    restart: always
    environment:
      POSTGRES_USER: ${PGUSER}
      POSTGRES_PASSWORD: ${PGPASSWORD}
      POSTGRES_DB: ${PGDATABASE}
    volumes:
      - postgres-data:/var/lib/postgresql/data
    ports:
      - 5432:5432
volumes:
  postgres-data:

The build section which now specifies a context of the current directory, and a target of our Development stage.

Go ahead and try it out! Run docker compose up again and notice the hot-reloading works. If you want to try out your production build, you can run this:

$ docker build . -t my-startup:latest

And check this out…the image size of the Development stage is 884MB vs 73.7MB for Production! That’s going to be way faster to work with and deploy.

Debugging with Breakpoints

To take this a step further and debug the code inside your container with an IDE, see my follow-up article The best way to debug a Node.js app running in a Docker container.

The best way to debug a Node.js app running in a Docker container

Deploying

Speaking of deploying, how can we easily get this application up and running in a cloud environment in a scalable way, complete with database? Well if you’re using FL0, you can just commit your code and the platform will handle the rest! Check out the FL0 docs on how to get setup.

The perfect multi-stage Dockerfile for Node.js apps was originally published in FL0 Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.

The app we’ll build is going to be basic, but it will contain the essential components you need to extend it for your own project. It will include:

1. A database for storing our startup’s products
2. An API endpoint for retrieving those products
3. A well-structured codebase including an ORM for managing database migrations, sample data and configuration.
4. Tools for managing the database, including separate Dev and Production environments

If all goes well, you should be up and running in less than half an hour!

Sample Repository

You’ll find the completed codebase at this link on the building-deploying-30-mins branch.

GitHub - fl0zone/blog-express-pg-sequelize

Prerequisites

This article will be fairly detailed with step-by-step instructions and code snippets where possible. However, it does expect you have…

• A Github account
• A FL0 account

And the following technologies installed on your machine…

• NodeJS + NPM
• Git
• Docker Desktop

If you have any questions on the setup or if you think there are any steps missing in this article, please drop a comment for us below!

Codebase Setup

Let’s start by setting up a local repository with the Express starter code. Open up a terminal window and run the following commands:

$ mkdir my-startup && cd my-startup
$ npm init --yes
$ npm i express
$ npm i --save-dev nodemon dotenv

These commands do the following:

1. Create a new folder called “my-startup” and navigate into that folder
2. Initialize the folder as an NPM project so we can install dependencies
3. Install Express as a dependency, Nodemon (a tool for auto-reloading the server when changes are detected) and Dotenv (for loading variables from a .env file)

To get a basic Express server running, create a new folder called src and a file inside called index.js and paste in the following code:

// src/index.js

const express = require('express')
const app = express()
const port = process.env.PORT ?? 3000;

app.get('/', (req, res) => {
  res.send('Hello World!')
})

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`)
})

Edit your package.json file and add the following start and start:dev commands:

{
  "name": "my-startup",
  "version": "1.0.0",
  ...
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start:dev": "nodemon -r dotenv/config src/index.js",
    "start": "node src/index.js"
  },
  ...
}

Checkpoint: The First Endpoint

Try out your app by running npm run start:dev and visiting http://localhost:3000 in your browser. See the words “Hello World”? Let’s keep going!

Before we move on to the next section, initialize your folder as a Git repo and save your changes:

$ git init
$ echo "node_modules\n.env" > .gitignore
$ git add .
$ git commit -m "Set up Express framework"

The above commands achieve the following:

1. Initialize the local Git repo (we will connect it to Github later)
2. Ignore the node_modules folder so it isn’t added to Git
3. Add all the other files to the Git stage
4. Commit the staged changes to the repo

Adding the Database

In this section we’ll create a local Postgres database and install Sequelize to manage it.

In the root of your codebase, create a file called docker-compose.yml and add the following content:

version: '3'
services:
  db:
    image: postgres:14
    restart: always
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: admin
      POSTGRES_DB: my-startup-db
    volumes:
      - postgres-data:/var/lib/postgresql/data
    ports:
      - 5432:5432
volumes:
  postgres-data:

A Docker Compose file tells Docker what containers to spin up and how they should be configured. Our file contains a single service - db. It runs an image called postgres (version 14) and sets some configuration like the username and password for the database.

Set environment variables

Our Docker Compose file is set up to create a database with username admin, password of admin and database name of my-startup-db. We will need to tell our app how to connect to the database, so let’s do that now. Create a file in the root of your repo called .env and add the following content:

NODE_ENV=local
DATABASE_URL=postgres://admin:admin@localhost:5432/my-startup-db

The DATABASE_URL variable will be used when we set up Sequelize.

Checkpoint: Database in a container

Before we continue, run the following command and verify your Postgres container starts correctly!

$ docker compose up

If you see a message like this, you’re good to go!

2023-01-23 23:58:33.091 UTC [1] LOG:  database system is ready to accept connections

Connecting with Sequelize

Sequelize is the most popular Javascript Object Relational Mapping )(ORM) framework. Other alternatives include TypeORM and Prisma. You can use any of these with FL0, but in this article we’ll choose Sequelize.

First let’s install Sequelize and the Postgres client for NodeJS, then use the Sequelize CLI tool to initialize our project:

$ npm install sequelize pg
$ cd src
$ npx sequelize-cli init --config=config/index.js

The npx sequelize-cli init command bootstraps our project with a few folders and files:

• config: a place to store connection details for our database
• migrations: A folder for storing database migration scripts, used to apply changes to the schema
• models: Every table in the database will be defined as a “model” and stored in this folder
• seeders: We can bootstrap our tables with sample data by adding scripts to this folder

Next, let’s alter the src/config/index.js file to point to our database. Replace its content with the following:

module.exports = {
  "local": {
    "use_env_variable": "DATABASE_URL"
  },
  "development": {
    "use_env_variable": "DATABASE_URL"
  },
  "production": {
    "use_env_variable": "DATABASE_URL"
  }
}

This tells Sequelize to read from the .env file we created earlier. To test our connection, alter the index.js file to look like this:

const express = require('express')
const { sequelize } = require('./models');
const app = express()
const port = process.env.PORT ?? 3000;

app.get('/', (req, res) => {
  res.send('Hello World!')
})

app.listen(port, async () => {
  console.log(`Example app listening on port ${port}`)
  try {
    await sequelize.authenticate();
    await sequelize.sync({ force: true});
    console.log('Connection has been established successfully.');
  } catch (error) {
    console.error('Unable to connect to the database:', error);
  }
})

These changes import the sequelize object from our new src/models/index.js file and attempt to connect to the database.

Checkpoint:

Run npm run start:dev and make sure you can see a message that says “Connection has been established successfully”. If you see any errors:

1. Make sure your database container is still running with docker compose up
2. Make sure your environment variables are loaded properly. You can verify this by adding console.log(JSON.stringify(process.env)) to your src/index.js file and looking for the DATABASE_URL key

Now is a good time to commit your changes!

$ git add . && git commit -m "Set up Sequelize connection" 

Creating the first database models

Now that Sequelize is set up we can start populating the database with some tables and values. Let’s use the Sequelize CLI tool to create our first model. Run the following script in your Terminal from the src folder:

$ npx sequelize-cli model:generate --name=Product --attributes=sku:string,name:string,description:text,isPublished:boolean,imageURL:string,price:decimal,weight:decimal

This will automatically generate src/models/product.js and a corresponding file in the migrations folder. Next, we’ll define some seed data to populate the Product table with some information:

$ npx sequelize-cli seed:generate --name=products

Open the created file under the seeders folder and replace it with the following content:

'use strict';

/** @type {import('sequelize-cli').Migration} */
module.exports = {
  async up(queryInterface, Sequelize) {
    await queryInterface.bulkInsert('Products', [{
      sku: 'STR0001',
      name: 'Three-lobed fidget spinner',
      description: 'A fidget spinner is a toy that consists of a ball bearing in the center of a multi-lobed (typically two or three) flat structure made from metal or plastic designed to spin along its axis with pressure. Fidget spinners became trending toys in 2017, although similar devices had been invented as early as 1993.[1]',
      imageURL: 'https://upload.wikimedia.org/wikipedia/commons/thumb/f/f3/Fidget_spinner_red%2C_cropped.jpg/1280px-Fidget_spinner_red%2C_cropped.jpg',
      isPublished: true,
      price: 12.95,
      weight: 0.1,
      createdAt: new Date(),
      updatedAt: new Date(),
    },
    {
      sku: 'STR0002',
      name: 'World-map stress ball',
      description: 'A stress ball or hand exercise ball is a malleable toy, usually not more than 7 cm in diameter, which is squeezed in the hand and manipulated by the fingers, ostensibly to relieve stress and muscle tension or to exercise the muscles of the hand. Patrick Hummel is widely understood to have created the stress ball in central Indiana in the mid-1980s.',
      imageURL: 'https://upload.wikimedia.org/wikipedia/commons/thumb/7/76/Earth_globe_stress_ball.jpg/220px-Earth_globe_stress_ball.jpg',
      isPublished: true,
      price: 4.99,
      weight: 0.05,
      createdAt: new Date(),
      updatedAt: new Date(),
    },
    {
      sku: 'STR0003',
      name: 'Metallic slinky',
      description: 'The Slinky is a precompressed[clarification needed] helical spring toy invented by Richard James in the early 1940s. It can perform a number of tricks, including travelling down a flight of steps end-over-end as it stretches and re-forms itself with the aid of gravity and its own momentum, or appear to levitate for a period of time after it has been dropped. These interesting characteristics have contributed to its success as a toy in its home country of the United States, resulting in many popular toys with slinky components in a wide range of countries.',
      imageURL: 'https://upload.wikimedia.org/wikipedia/commons/thumb/f/f3/2006-02-04_Metal_spiral.jpg/200px-2006-02-04_Metal_spiral.jpg',
      isPublished: true,
      price: 15.45,
      weight: 0.2,
      createdAt: new Date(),
      updatedAt: new Date(),
    }
  ], {});
  },

  async down(queryInterface, Sequelize) {
  }
};

The code above inserts three sample products for us to work with. To import the data, make sure your app is running with npm run start:dev and then in a new terminal window run:

$ npx sequelize-cli db:seed:all --config=src/config/index.js

Hopefully you see some output that looks like this!

== 20230124200930-products: migrating =======
== 20230124200930-products: migrated (0.031s)

Connecting the Database and API

Now that we have a database with some product records, it’s time to create an API to expose this information. Update src/index.js with the following content:

const express = require('express')
const { sequelize, Product } = require('./models');
const app = express()
const port = process.env.PORT ?? 3000;

app.get('/', (req, res) => {
  res.send('Hello World!')
})

app.get('/products', async (req, res) => {
  const products = await Product.findAll();
  res.json(products);
})

app.listen(port, async () => {
  console.log(`Example app listening on port ${port}`)
  try {
    await sequelize.authenticate();
    await sequelize.sync({ force: true});
    console.log('Connection has been established successfully.');
  } catch (error) {
    console.error('Unable to connect to the database:', error);
  }
})

Notice the new /products route, and the Product object being imported from the Sequelize model file. Verify this is working by hitting http://localhost:3000/products and ensuring you see the product data returned as JSON.

Commit your changes and continue reading!

$ git add . && git commit -m "Created GET /products endpoint"

Deploying the app

Now that we’ve got a working API and database we can deploy it to a server! In this article we’re using FL0, a platform that makes it really easy to deploy NodeJS apps to a containerized infrastructure, complete with database.

Pushing to Github

Up until now we’ve been committing changes to a local repo that only exists on our machine. Let’s link that to a Github repo so it can be stored in the cloud. In Github, create a new empty repo with no license or .gitignore file. If all goes well, you should see a screen like this:

We need to follow the steps under the heading “…or push an existing repository from the command line”. Note: I haven’t included the commands here because they will be specific to your own repo and may use HTTPS instead of SSH like mine does. It’s better to copy+paste from the Github page than this article for this step.

If successful, you should be able to refresh the Github page and see your code:

Configuring FL0

In FL0, create a new empty project and then add a Postgres database. You can call it anything you like.

Next, add a new Service and connect to your Github account:

You should see a window asking you to authorize FL0 to connect to your account:

When you are returned to FL0, your repos will be available to deploy through the user interface. Click the “Connect” button to continue. On the next page, you have the option to specify a Service Name and set Environment Variables. This is where we need to insert our Database URL.

Click the “+ Environment Variables” button and in the popup window that appears, select “Import database credentials”:

Make sure you see a row called DATABASE_URL before continuing.

Save your changes and click the “Deploy” button!

This will trigger a new build to begin. Click on your new Service and navigate to the Deployments tab to see how it’s progressing:

Once complete, go to the Overview tab and copy the URL:

Open it up in a browser and you should see the familiar “Hello World” message! Add a /products onto the end and you should see…nothing…yet! This is because our new FL0 database is still empty and we need to run the Seed script to insert the sample data.

Pointing the Sequelize CLI at FL0

Earlier we created a .env file that contained a DATABASE_URL variable instructing Sequelize to connect to our Docker container. Let’s edit the file to include a new variable, our FL0 database URL. You can find the Database URL in FL0 under the Connection Info tab of the Postgres resource.

Copy the .env and call it .env.dev and updated it as follows:

NODE_ENV=development
DATABASE_URL=<YOUR FL0 DATABASE_URL>

Adding this will let us run the Sequelize CLI against different environments. Try this:

$ npx dotenv-cli -e .env.dev -- npx sequelize-cli db:seed:all --config=src/config/index.js

Notice the dotenv-cli -e .env.dev option telling Sequelize to use FL0 instead of our local container. Go back to your browser and check the /products URL again. Hopefully you see some product JSON! Using FL0’s deployment features you can easily replicate your container to the Production environment with a completely separate database.

And there you have it folks, the building blocks for a successful NodeJS project! With the knowledge and skills you’ve gained from this article, you’re ready to bring your next big idea to life. We’d love to hear what you’re building in the comments below! We hope this article brought a smile to your face and a little inspiration to help tackle help your next project. Until next time, happy coding!

Building and deploying a NodeJS + Postgres API in less than 30 minutes was originally published in FL0 Engineering on Medium, where people are continuing the conversation by highlighting and responding to this story.