luismachadoreis/heimdall-server repository overview

src/
├── auth/
│   ├── domain/           # Business logic and entities
│   │   ├── User.ts       # User entity with business rules
│   │   └── UserDomain.ts # Domain services
│   ├── application/      # Use cases and application services
│   │   ├── LoginUseCase.ts
│   │   ├── SignupUseCase.ts
│   │   └── ...
│   ├── infrastructure/   # External concerns (database, etc.)
│   │   ├── UserRepository.ts           # Repository interface
│   │   ├── DynamoDBUserRepository.ts   # DynamoDB implementation
│   │   ├── PostgresUserRepository.ts   # PostgreSQL implementation
│   │   └── UserRepositoryFactory.ts    # Factory for database selection
│   └── api/             # Controllers and routes
│       ├── AuthController.ts
│       ├── AdminController.ts
│       └── AuthRoutes.ts
├── commons/
│   └── infrastructure/   # Shared infrastructure components
│       └── Datasource.ts # Database configuration and connection
├── app.ts              # Express app configuration
├── server.ts           # Development server
└── lambda.ts           # AWS Lambda handler

# Clone the repository
git clone https://github.com/luismr/heimdall.git
cd heimdall/heimdall-server

# Install dependencies
npm install

# Setup environment variables
cp .env.example .env

# Application Configuration
JWT_SECRET=your-super-secret-jwt-key
USERS_TABLE=HeimdallUsers
PORT=4000
NODE_ENV=development

# Signup Protection (required for creating new users)
SIGNUP_ACCESS_TOKEN=your-signup-access-token
SIGNUP_SECRET_TOKEN=your-signup-secret-token

# Database Selection
DB_TYPE=dynamodb  # Options: 'dynamodb' or 'postgres'

# AWS Credentials (required for DynamoDB)
AWS_ACCESS_KEY_ID=your-access-key-id
AWS_SECRET_ACCESS_KEY=your-secret-access-key
AWS_REGION=us-east-1

# PostgreSQL Configuration (required if DB_TYPE=postgres)
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=heimdall
POSTGRES_PASSWORD=your-secure-password
POSTGRES_DB=heimdall
POSTGRES_SSL=false

# Create DynamoDB table using AWS CLI
aws dynamodb create-table \
  --table-name HeimdallUsers \
  --attribute-definitions AttributeName=username,AttributeType=S \
  --key-schema AttributeName=username,KeyType=HASH \
  --provisioned-throughput ReadCapacityUnits=5,WriteCapacityUnits=5

CREATE DATABASE heimdall;
CREATE USER heimdall WITH ENCRYPTED PASSWORD 'your-secure-password';
GRANT ALL PRIVILEGES ON DATABASE heimdall TO heimdall;

# Run all pending migrations
npm run typeorm:migration:run

# Revert the last applied migration
npm run typeorm:migration:revert

# Create a new empty migration (for development)
npm run typeorm:migration:create -- -n YourMigrationName

# Generate a migration from entity changes (for development)
npm run typeorm:migration:generate -- -n YourMigrationName

# Build the Docker image with GitHub token
docker build -t heimdall-server . --build-arg GITHUB_TOKEN=your_github_token

# Build with a specific tag
docker build -t heimdall-server:1.0.0 . --build-arg GITHUB_TOKEN=your_github_token

# If you have the token in an environment variable
docker build -t heimdall-server . --build-arg GITHUB_TOKEN=${GITHUB_TOKEN}

# Run the container
docker run -d \
  -p 4000:4000 \
  --name heimdall \
  --env-file .env \
  heimdall-server

# View container logs
docker logs -f heimdall

# Stop the container
docker stop heimdall

# Remove the container
docker rm heimdall

version: '3.8'
services:
  app:
    build: .
    ports:
      - "4000:4000"
    env_file: .env
    depends_on:
      - postgres
    
  postgres:
    image: postgres:17-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: heimdall
      POSTGRES_PASSWORD: your-secure-password
      POSTGRES_DB: heimdall
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop all services
docker-compose down

# Start development server with hot reload
npm run dev

# The API will be available at http://localhost:4000

# Start serverless offline
npm run serverless:dev

# The API will be available at http://localhost:4000

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

X-Access-Token: your-signup-access-token
X-Secret-Token: your-signup-secret-token

{
  "username": "johndoe",
  "password": "securepassword123"
}

{
  "username": "johndoe",
  "roles": ["ROLE_USER"],
  "blocked": false
}

{
  "username": "johndoe",
  "password": "securepassword123"
}

{
  "user": {
    "username": "johndoe",
    "roles": ["ROLE_USER"],
    "blocked": false
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Authorization: Bearer <access-token>

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

{
  "message": "Logged out successfully"
}

Authorization: Bearer <admin-access-token>