Getting Started

Prerequisites

Docker ≥ 20.10 (Download Docker Desktop)
Docker Compose ≥ 2.0 (Usually included with Docker Desktop)(Install instructions)
Maven ≥ 3.6 (Download Maven)
Java 17 (JDK) (Download Java 17)

Verify Installations

You can verify the installations by running the following commands in your terminal:

docker --version
mvn --version
java -version

Important: Ensure that Java 17 is the active version in use. Maven should also be configured to use Java 17 - you can verify this by checking that mvn --version shows Java 17 in its output.

Port Requirements

Make sure the following ports are free and not in use by other services:

3306 – MySQL database
6379 – Redis cache
8080 – Guardian application server
6000 – Mock user/communication service (for development)

If any of these ports are in use, you’ll need to stop the conflicting services or modify the port mappings in docker-compose.yaml.

Quick Start

Clone the repository:

git clone https://github.com/dream-horizon-org/guardian.git
cd guardian

Start Guardian:

./quick-start.sh

This script will:

Build the Guardian application using Maven
Start all required services (MySQL, Redis, Guardian, and mock services) using Docker Compose
Run database migrations and seed initial data

Test the setup with passwordless flow:

The seed data includes a pre-configured tenant (tenant1) and client (client1) for testing.

Initialize passwordless authentication:

curl --location 'localhost:8080/v2/passwordless/init' \
--header 'tenant-id: tenant1' \
--header 'Content-Type: application/json' \
--data '{
    "contacts": [
        {
            "channel": "SMS",
            "identifier": "7878787878"
        }
    ],
    "flow": "SIGNINUP",
    "response_type": "token",
    "client_id": "client1"
}'

Expected response: You’ll receive a JSON response containing a state field. Copy this value for the next step.

Complete authentication (using mock OTP for development):

curl --location 'localhost:8080/v2/passwordless/complete' \
--header 'tenant-id: tenant1' \
--header 'Content-Type: application/json' \
--data '{
    "state": "<paste-state-from-init-response-here>",
    "otp": "999999"
}'