ms-auth

ms-auth is a microservice designed for handling user authentication and authorization. It provides backend functionality for managing users, roles, permissions, and sessions using JWT. The service is developed in Go. PostgreSQL serves as the relational database for user data, and Valkey (or a compatible Redis instance) is used for session management.

For understanding the architecture, see the documentation.

Prerequisites

Before you begin, ensure you have the following dependencies installed:

• Docker and Docker Compose: To run PostgreSQL and Valkey/Redis.
• Goose: For applying database migrations (go install github.com/pressly/goose/v3/cmd/goose@latest).
• oapi-codegen: For generating OpenAPI code (go install github.com/deepmap/oapi-codegen/cmd/oapi-codegen@latest).

1. Running Dependencies

You can run PostgreSQL and Valkey/Redis using Docker Compose. Create a docker-compose.yml file like the following:

version: '3.8'
services:
  valkey:
    container_name: valkey
    hostname: valkey
    image: valkey/valkey:latest
    volumes:
      - ./conf/valkey.conf:/usr/local/etc/valkey/valkey.conf
      - ./valkey-data:/data
    command: [ "valkey-server", "/usr/local/etc/valkey/valkey.conf" ]
    healthcheck:
      test: [ "CMD-SHELL", "valkey-cli ping | grep PONG" ]
      interval: 10s
      timeout: 3s
      retries: 5
    ports:
      - "6379:6379"
  postgres:
    image: postgres:14.1-alpine # Uses PostgreSQL 14.1 Alpine image
    restart: always # Ensures the container restarts if it stops
    environment:
      POSTGRES_USER: postgres # Default user
      POSTGRES_PASSWORD: supersecretpassword # Default password (change for production!)
      POSTGRES_DB: postgres # Default database name
    ports:
      - '5432:5432' # Exposes PostgreSQL on the standard port 5432
    volumes:
      - ./postgres-data:/var/lib/postgresql/data # Persists database data locally
    healthcheck:
      test: pg_isready -U postgres -d postgres # Command to check if PostgreSQL is ready
      interval: 10s # Check every 10 seconds
      timeout: 3s # Wait 3 seconds for the check to respond
      retries: 5 # Try 5 times before marking as unhealthy
volumes:
  postgres-data: # Defines the named volume for data persistence

Start the services in detached mode:

docker-compose up -d

2. Configuration

The application uses environment variables for configuration. Create a .env file in the project root. The required variables are:

# Environment type (development or production)
ENV=dev # or prod

# Address and port where the ms-auth service will listen
ADDRESS=localhost:8090 # Default :8090

# PostgreSQL connection string (Data Source Name)
# Format: postgres://user:password@host:port/database?sslmode=disable
POSTGRES_DSN=postgres://postgres:supersecretpassword@localhost:5432/postgres?sslmode=disable

# Valkey/Redis connection string
# Format: valkey://<user>:<password>@<host>:<port>/<database>
REDIS_DSN=valkey://localhost:6379/0 # Adjust if using authentication or a different database

# Secret key for signing and verifying JWT tokens
JWT_SECRET=your_super_secret_jwt_key

# Optional: Initial admin credentials (defaults to admin/admin)
# ADMIN_USERNAME=admin
# ADMIN_PASSWORD=admin

Important: Replace supersecretpassword and your_super_secret_jwt_key with secure, unique values, especially for a production environment. Ensure the database credentials match your docker-compose.yml setup.

3. Database Migrations

The project uses goose to manage the database schema.

1. Ensure goose is installed:

   go install github.com/pressly/goose/v3/cmd/goose@latest
   

2. Apply the migrations to the running PostgreSQL database. The migrations are located in the ./migrations directory. Make sure the connection string in the command matches the POSTGRES_DSN from your .env file:

   goose -dir ./migrations postgres "postgres://postgres:supersecretpassword@localhost:5432/postgres?sslmode=disable" up
   

4. OpenAPI Code Generation

The project uses OpenAPI to define its API. Go code for handlers and models is generated based on this specification using oapi-codegen. The configuration for generation is likely in config.yaml or a Makefile.

Assuming a Makefile exists similar to the ms-tester example:

make gen

Or, run oapi-codegen directly based on your project's specific OpenAPI definition file (e.g., api/user/v1/user.yaml) and the config.yaml:

# Example command (adjust paths/package names as needed):
oapi-codegen -config config.yaml api/user/v1/user.yaml

This generates the code specified in config.yaml, outputting to ./contracts/user/v1/user.go.

5. Running the Application

Start the ms-auth service using the main package located in the cmd/ms-auth directory:

go run ./cmd/ms-auth/main.go

After starting, the service will be available at the address specified in the ADDRESS variable in your .env file (e.g., http://localhost:8090).