Development Guide

This guide explains how to set up and run the SaaS Auth API in development mode.

Prerequisites

Before you start, make sure you have the following installed:

• Go 1.24.1 or later
• Docker and Docker Compose
• Git
• PostgreSQL client (optional, for direct database access)
• Redis client (optional, for direct cache access)

Getting the Code

git clone https://github.com/yersonargotev/saas-auth-api.git
cd saas-auth-api

Development Environment Setup

Using Docker Compose (Recommended)

The project includes a Docker Compose configuration for development that provides:

• Hot reloading using Air
• PostgreSQL database
• Redis cache

To start the development environment:

docker-compose -f docker-compose.dev.yml up

This will:

1. Build the development Docker image
2. Start PostgreSQL and Redis services
3. Run database migrations automatically
4. Start the API with hot reloading at http://localhost:3000

Local Development (Without Docker)

If you prefer to run the application directly on your machine:

1. Install Go dependencies:

   go mod download

2. Install Air for hot reloading (optional):

   go install github.com/air-verse/air@latest

3. Set up PostgreSQL and Redis locally or use existing instances.

4. Create a .env file with your configuration (see Configuration section).

5. Run the application with Air for hot reloading:

   air

   Or without hot reloading:

   go run cmd/api/main.go

Configuration

The application uses a configuration file located at config/config.yaml. You can override these settings using environment variables:

app:
  name: saas-auth-api
  version: 0.1.0
  env: development
  port: 3000

database:
  host: localhost
  port: 5432
  user: postgres
  password: postgres
  name: saas_auth
  sslmode: disable
  max_open_conns: 20
  max_idle_conns: 5
  conn_max_lifetime: 30m

redis:
  host: localhost
  port: 6379
  password: ""
  db: 0

jwt:
  secret: supersecretkey-change-in-production
  access_ttl: 15m
  refresh_ttl: 24h

auth:
  password_salt: change-this-in-production
  api_key_prefix: sk-
  api_key_length: 32
  rate_limit:
    enabled: true
    requests: 100
    duration: 1m

Environment variable mapping:

• APP_ENV → app.env
• APP_PORT → app.port
• DB_HOST → database.host
• DB_PORT → database.port
• DB_USER → database.user
• DB_PASSWORD → database.password
• DB_NAME → database.name
• REDIS_HOST → redis.host
• REDIS_PORT → redis.port
• REDIS_PASSWORD → redis.password
• JWT_SECRET → jwt.secret

Database Migrations

Migrations are automatically run when the application starts. The migration files are located in the migrations directory.

To manually run migrations, you can use the golang-migrate CLI tool:

# Install the migration tool
go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest

# Run migrations
migrate -path ./migrations -database "postgres://postgres:postgres@localhost:5432/saas_auth?sslmode=disable" up

Testing

Running Unit Tests

go test ./tests/unit/...

Running Integration Tests

go test ./tests/integration/...

Running End-to-End Tests

go test ./tests/e2e/...

API Documentation

You can view the API documentation in the Swagger UI by accessing /docs endpoint when running the application.

Development Workflow

1. Create a new branch for your feature or bugfix:

   git checkout -b feature/my-feature

2. Make your changes and write tests.

3. Run tests to make sure everything works:

   go test ./...

4. Commit your changes with a descriptive message:

   git commit -m "Add my new feature"

5. Push your branch and create a pull request.

Troubleshooting

Common Issues

1. Connection refused to PostgreSQL or Redis

   • Make sure the services are running
   • Check if the host and port are correct in the configuration
   • Verify that no firewall is blocking the connections

2. Hot reloading not working

   • Check if Air is installed and configured correctly
   • Make sure the .air.toml file exists in the project root

3. JWT token issues

   • Verify that the JWT secret is set correctly
   • Check the token expiration times in the configuration

4. Database migration failing

   • Check the database connection settings
   • Make sure the database user has the necessary permissions
   • Look for syntax errors in the migration files

Logs and Debugging

In development mode, the application logs are verbose and include detailed information about requests, database queries, and errors. You can adjust the log level in the configuration file.

To enable additional debugging information, set the following environment variable:

APP_ENV=development

Code Structure

The project follows a clean architecture approach with the following structure:

• cmd/api: Application entry point
• config: Configuration files
• docs: API documentation
• internal: Application core
  • apiKey: API key management
  • auth: Authentication service
  • role: Role and permission management
  • user: User management
• migrations: Database migration files
• pkg: Shared packages
  • config: Configuration loading
  • database: Database connection and repositories
  • logger: Logging utilities
  • middleware: HTTP middlewares
  • validator: Input validation
• tests: Test suite
  • e2e: End-to-end tests
  • integration: Integration tests
  • unit: Unit tests