Getting started

FlowInquiry back-end is a spring boot application, and it has several components:

Spring Data
Spring REST
Spring Security
Hibernate
Liquibase

FlowInquiry uses Gradle as its build tool and includes the Gradle wrapper in the distribution, so there’s no need to install Gradle separately.

Get the latest sources from GitHub

Access the latest source code for FlowInquiry’s back-end at https://github.com/flowinquiry/flowinquiry-server

Development

Folders organization

scripts Includes useful scripts for validating environment settings, setting up project environment variables, and more
server the FlowInquiry server sources
commons the common codebase for FlowInquiry backend
tools extra tools for FlowInquiry server such as liquibase database migration scripts and more

Configure the application

To run the FlowInquiry backend, users need to provide their input in the local configuration file .env.local. FlowInquiry offers two options for creating this configuration file:

Using Bash Scripts: Users can run provided Bash scripts, which prompt for inputs, validate the information, and then automatically generate the configuration file.
Editing a Template Manually: A template configuration file (.env.local.example) is provided, allowing users to manually edit and create their .env.local file. This option is recommended for Windows users who cannot run Bash scripts.

Creat config file by script

Checking environments

FlowInquiry backend requires Java, Docker is already installed. You can run the valid_checks.sh script located in the scripts folder to verify if your machine is set up to work with FlowInquiry


➜  flowinquiry-server scripts/valid_checks.sh
Running java_check.sh...
Java Version Information:
openjdk version "21.0.5" 2024-10-15 LTS
OpenJDK Runtime Environment Temurin-21.0.5+11 (build 21.0.5+11-LTS)
OpenJDK 64-Bit Server VM Temurin-21.0.5+11 (build 21.0.5+11-LTS, mixed mode, sharing)
 
Java Vendor: Eclipse Adoptium
Java Runtime Environment: OpenJDK Runtime Environment
Java VM Name: OpenJDK 64-Bit Server VM
Java Home: /usr
Java version is 21, which is greater than or equal to 21.
java_check.sh succeeded.
Running docker_check.sh...
docker_check.sh succeeded.
Your environments settings satisfy FlowInquiry's conditions

Setup scripts

You will need to run the following scripts:

scripts/init_git_hooks.sh: Sets up a git hook to automatically format and check code logic each time you commit changes.

scripts/create_secrets.sh: Create secrets stored in the .env.local file, which is used by the FlowInquiry server

💡

You can run the scripts/all.sh script, which will check your environment settings and perform the necessary configurations, eliminating the need to run multiple scripts individually

Sending email

To use FlowInquiry’s email features, such as sending activation emails to users or reminders about upcoming tasks, you’ll need an SMTP account. You can configure this with providers like Gmail, Amazon SES, or any SMTP service. Please note that this email setup is intended for use in a local environment only.

Run the script scripts/mail_config.sh, it will ask you the STMP information, and then it writes all to the local file .env.local


➜  flowinquiry-server git:(main) ✗ scripts/mail_config.sh
Enter your SMTP host: smtp.gmail.com
Enter your SMTP port: 587
Enter your username: username
Enter your password:  password
Does SMTP require STARTTLS (y/n)? y
Please enter the email address that will be used as the sender for outgoing emails: [email protected]
Please enter the base URL that will be used for the email template: http://localhost:3000
Backup of .env.local created as .env.local.backup
Configuration has been saved to .env.local

ℹ️

To use your Google credentials to send a test email, you cannot use your regular email password. Instead, you’ll need to generate an App Password. For detailed instructions, see the guide at https://support.google.com/mail/answer/185833?hl=en

Edit config file manually

Rename the file .env.local.example to .env.local, and edit the file content per instructions inline


#!/bin/bash
 
################################################
# PostgreSQL Configuration
################################################
 
# Password for the PostgreSQL database.
# This is critical for securing database access. Store it securely.
POSTGRES_PASSWORD='choose your own password'
 
# Username for connecting to the PostgreSQL database.
# Required for authentication with the database.
SPRING_DATASOURCE_USERNAME=flowinquiry
 
################################################
# JWT Configuration
################################################
 
# Base64-encoded secret key used for signing and verifying JWT tokens.
# This key is generated from a 50-character random string consisting of A-Z and 0-9.
# For development purposes, a pre-defined string is provided, but it is strongly recommended
# to generate your own unique key, especially for production environments.
# This key is critical for securing authentication and must be stored securely.
JWT_BASE64_SECRET='alBEd1VVQWpuVkxrNEQ4YnFBZmtvUk1pU2NoQ0x2UG92SW00cUZZaGx4UmRzUEUyM0dWR01yQWxPUURud0sxRDNpeVZQY1NtNGNCTElsc25kUEg4TDlySGVt'
 
################################################
# Email Configuration (Optional)
################################################
 
# SMTP server address for sending emails. Example: smtp.gmail.com
spring.mail.host=
 
# Port number for SMTP communication. Typically 587 for TLS.
spring.mail.port=
 
# Ensure the SMTP server port is set correctly. Usually this value equals with spring.mail.port
spring.mail.properties.mail.smtp.port=
 
# Email address used for SMTP authentication.
spring.mail.username=
 
# Password or app-specific password for SMTP authentication.
# Sensitive information. Use environment variables or a secret manager.
spring.mail.password=
 
# Enables SMTP authentication. Value true/false
spring.mail.properties.mail.smtp.auth=
 
# The "from" address for outgoing emails.
flowinquiry.mail.from=
 
# Base URL for links in emails, such as password resets or verification emails.
flowinquiry.mail.base_url=
 
# Enables TLS for secure SMTP communication. Value true/false
spring.mail.properties.mail.smtp.starttls.enable=
 
# Ensures TLS is required for SMTP communication. Value true/false
spring.mail.properties.mail.smtp.starttls.required=
 
################################################
# OpenAI Configuration (Optional)
################################################
 
# API key for authenticating with OpenAI services.
# Critical for accessing OpenAI's APIs. Store it securely.
OPEN_AI_API_KEY=
 
# Specifies the OpenAI model to use for processing requests.
# Example: gpt-3.5-turbo.
OPEN_AI_CHAT_MODEL=

Run application

Run postgres database

FlowInquiry uses PostgreSQL as its database and provides pre-configured PostgreSQL settings. You need to run the database before starting the FlowInquiry server. Ensure that Docker is installed on your machine, then run the command docker compose -f docker/services.yml up to start the database


➜  flowinquiry-server git:(main) docker compose -f docker/services.yml up
[+] Running 1/0
 ✔ Container flowinquiry-postgresql-1  Created                                                                                                                                                                        0.0s
Attaching to postgresql-1
postgresql-1  |
postgresql-1  | PostgreSQL Database directory appears to contain a database; Skipping initialization
postgresql-1  |
postgresql-1  | UTC [1] LOG:  starting PostgreSQL 16.3 (Debian 16.3-1.pgdg120+1) on aarch64-unknown-linux-gnu, compiled by gcc (Debian 12.2.0-14) 12.2.0, 64-bit
postgresql-1  | UTC [1] LOG:  listening on IPv4 address "0.0.0.0", port 5432
postgresql-1  | UTC [1] LOG:  listening on IPv6 address "::", port 5432
postgresql-1  | UTC [1] LOG:  listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
postgresql-1  | UTC [1] LOG:  database system is ready to accept connections

️🚫

Be sure to run the scripts/all.sh or scripts/create_secrets.sh script before starting the PostgreSQL database, as they will generate a new PostgreSQL password and store it in the .env.local file, which the PostgreSQL container relies on.

Run flowinquiry server

Gradle

From the root folder, run the command ./gradlew :server:bootRun


➜  flowinquiry-server git:(main) ./gradlew :server:bootRun
Starting a Gradle Daemon, 1 incompatible Daemon could not be reused, use --status for details
 
> Task :server:bootRun
 
:: FlowInquiry 🤓  :: Running Spring Boot 3.3.1 :: Startup profile(s) dev ::
:: https://www.flowinquiry.io ::
 
______ _             _____                  _
|  ___| |           |_   _|                (_)
| |_  | | _____      _| | _ __   __ _ _   _ _ _ __ _   _
|  _| | |/ _ \ \ /\ / / || '_ \ / _` | | | | | '__| | | |
| |   | | (_) \ V  V /| || | | | (_| | |_| | | |  | |_| |
|_|   |_|\___/ \_/\_/\___/_| |_|\__, |\__,_|_|_|   \__, |
                                   | |              __/ |
                                   |_|             |___/
 
 
 
:: FlowInquiry 🤓  :: Running Spring Boot 3.4.0 :: Startup profile(s) dev ::
:: https://www.flowinquiry.io ::
DEBUG 25048 --- [kground-preinit] org.jboss.logging.logProvider:164 : Logging Provider: org.jboss.logging.Slf4jLoggerProvider found via system property
DEBUG 50958 --- [  restartedMain] io.flowinquiry.FlowInquiryApp.logStarting:54 : Running with Spring Boot v3.4.0, Spring v6.2.0

It may take some time before the server APIs are accessible on the default port 8080