API REST for Contacts

Technologies

---

Pre-requisites

• Java 21
• Apache Maven (3.8.7+)
• Docker

---

Getting Started

1. Clone the repository

git clone git@github.com:TechAbraao/contacts.git
cd contacts

2. Configure environment variables

Copy the example file and fill in your values:

cp .env.example .env

Minimal .env example:

## POSTGRESQL ##
POSTGRES_CONTAINER_NAME=contacts_postgres
POSTGRES_PORT=5432
POSTGRES_USER=postgres
POSTGRES_PASSWORD=secret
POSTGRES_DB=contacts_db

## PGADMIN ##
PGADMIN_CONTAINER_NAME=contacts_pgadmin
PGADMIN_PORT=8081
PGADMIN_EMAIL=admin@example.com
PGADMIN_PASSWORD=secret

---

Flow 1 — Run locally (application on host, PostgreSQL on Docker)

Use this flow if you want to run the application directly with Maven, while the database runs in a container.

1. Start the database container

docker compose --env-file .env -f docker/compose/docker-compose-dev.yml up -d

Or with Makefile (Linux/Unix):

make up

Check out more commands by typing make in the terminal. These commands are solely for development assistance.

2. Configure application.yml

Since the application runs on your host machine, it connects to PostgreSQL via localhost:

server:
  port: 8080

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/contacts_db
    username: postgres
    password: secret
    driver-class-name: org.postgresql.Driver

  security:
    jwt:
      secret: secret
    user:
      email: admin@admin.com
      name: admin
      password: admin

3. Run the application

mvn clean install -DskipTests
mvn spring-boot:run

To run with tests:

mvn test

4. Availability

API:

http://localhost:8080/api/

Swagger UI:

http://localhost:8080/swagger-ui/index.html

---

Flow 2 — Run everything with Docker (recommended for production)

Use this flow to run both the application and the database as containers.

1. Build the application JAR

mvn package -DskipTests

2. Build the Docker image

docker build -f docker/dockerfiles/Dockerfile -t contacts .

3. Configure application.yml

Since both services run inside Docker, the application must connect to PostgreSQL using the service name defined in docker-compose-prod.yml (postgres), not localhost:

server:
  port: 8080

spring:
  datasource:
    url: jdbc:postgresql://postgres:5432/contacts_db
    username: postgres
    password: secret
    driver-class-name: org.postgresql.Driver

  security:
    jwt:
      secret: secret
    user:
      email: admin@admin.com
      name: admin
      password: admin

Alternatively, you can keep localhost in application.yml and override the URL via environment variable in docker-compose-prod.yml:

environment:
  SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/contacts_db

4. Start all containers

docker compose --env-file .env -f docker/compose/docker-compose-prod.yml up -d

5. Verify running containers

docker ps

6. View application logs

docker logs contacts_app

7. Availability

API:

http://localhost:8080/api/

Swagger UI:

http://localhost:8080/swagger-ui/index.html