Skip to content

Quick Start

Get the 2FA Authentication Service running in 5 minutes with Docker.

Prerequisites

Before starting, ensure you have:

  • Docker and Docker Compose installed
  • 1GB RAM minimum
  • Port 3000 and 3001 available

Don't have Docker?

Install Docker Desktop for your operating system.

Step 1: Clone the Repository

Bash
git clone https://github.com/Ilia01/Aegis2FA.git
cd 2fa

Step 2: Generate JWT Secrets

Generate 4 random secrets for JWT tokens:

Bash
for i in {1..4}; do
  node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
done

Copy the 4 generated strings - you'll need them in the next step.

Step 3: Configure Environment

Create your environment file:

Bash
cp .env.example .env
nano .env  # Or use your preferred editor

Add the 4 secrets you generated:

.env
JWT_ACCESS_SECRET=<paste-first-secret-here>
JWT_REFRESH_SECRET=<paste-second-secret-here>
TEMP_TOKEN_SECRET=<paste-third-secret-here>
DEVICE_TOKEN_SECRET=<paste-fourth-secret-here>

# Database will be created automatically by Docker
DATABASE_URL=postgresql://postgres:postgres@postgres:5432/twofa_db?schema=public

# Redis (already configured for Docker)
REDIS_HOST=redis
REDIS_PORT=6379

TOTP Only (No External Services)

The configuration above is all you need for TOTP 2FA (Google Authenticator). No Twilio, no email service required!

Step 4: Start the Services

Bash
docker-compose up -d

This starts:

  • ✅ PostgreSQL database
  • ✅ Redis cache
  • ✅ Backend API (port 3001)
  • ✅ Frontend demo (port 3000)
  • ✅ Background workers

Step 5: Run Database Migrations

Bash
docker-compose exec backend npx prisma migrate deploy

Step 6: Verify Installation

Check that all services are healthy:

Bash
# Check health endpoint
curl http://localhost:3001/api/health

# Expected response:
# {
#   "status": "healthy",
#   "checks": {
#     "database": "up",
#     "redis": "up",
#     "memory": "ok"
#   }
# }

Visit the frontend demo:

Text Only
http://localhost:3000

Step 7: Test the Service

Register a User

Bash
curl -X POST http://localhost:3001/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "username": "testuser",
    "password": "SecurePass123!"
  }'

Setup TOTP 2FA

  1. Visit http://localhost:3000
  2. Register with the credentials above
  3. Navigate to "Setup 2FA"
  4. Choose "TOTP (Google Authenticator)"
  5. Scan the QR code with your authenticator app
  6. Enter the 6-digit code to complete setup

🎉 Congratulations!

Your 2FA service is now running! You can now integrate it into your application.

Next Steps

Learn how to integrate the 2FA service into your application

Integration Guide

Deploy the service to a cloud platform or your own server

Deployment Guide

Try out all the API endpoints with interactive documentation

API Reference

Configure SMS or Email 2FA

SMS Setup Email Setup

Troubleshooting

Port Already in Use

If ports 3000 or 3001 are already in use, edit docker-compose.yml:

YAML
services:
  backend:
    ports:
      - "3002:3001"  # Change 3001 to 3002
  frontend:
    ports:
      - "3001:3000"  # Change 3000 to 3001

Database Connection Error

Ensure PostgreSQL container is running:

Bash
docker-compose ps postgres
docker-compose logs postgres

If needed, restart the database:

Bash
docker-compose restart postgres

Redis Connection Error

Check Redis status:

Bash
docker-compose exec redis redis-cli ping
# Should return: PONG

View Logs

See what's happening in the backend:

Bash
docker-compose logs -f backend

Clean Up

To stop and remove all containers:

Bash
docker-compose down

To also remove volumes (⚠️ deletes all data):

Bash
docker-compose down -v

Support

Need help? Check out: