k-template

A production-ready, modular Rust API template for K-Suite applications, following Hexagonal Architecture principles.

Features

• Hexagonal Architecture: Clear separation between Domain, Infrastructure, and API layers
• Multiple Auth Modes: Session-based, JWT, or both - fully configurable
• OIDC Integration: Connect to any OpenID Connect provider (Keycloak, Auth0, Zitadel, etc.)
• Database Flexibility: SQLite (default) or PostgreSQL via feature flags
• Type-Safe Configuration: Newtypes with built-in validation for all security-sensitive values
• Cargo Generate Ready: Pre-configured for scaffolding new services

Quick Start

Option 1: Use cargo-generate (Recommended)

cargo generate --git https://github.com/GKaszewski/k-template.git

You'll be prompted to choose:

• Project name: Your new service name
• Database: sqlite or postgres
• Session auth: Enable cookie-based sessions
• JWT auth: Enable Bearer token authentication
• OIDC: Enable OpenID Connect integration

Option 2: Clone directly

git clone https://github.com/GKaszewski/k-template.git my-api
cd my-api
cp .env.example .env
# Edit .env with your configuration

Run

# Development (with hot reload via cargo-watch)
cargo watch -x run

# Or simply
cargo run

The API will be available at http://localhost:3000/api/v1/.

Configuration

All configuration is done via environment variables. See .env.example for all options.

Authentication Modes

Set AUTH_MODE to one of:

Mode	Description	Required Features
session	Cookie-based sessions	auth-axum-login
jwt	Bearer token authentication	auth-jwt
both	Try JWT first, fall back to session	auth-axum-login, auth-jwt

OIDC Integration

To enable OIDC login (e.g., "Login with Google"):

1. Enable the auth-oidc feature (enabled by default)
2. Configure your OIDC provider in .env:

   OIDC_ISSUER=https://your-provider.com
   OIDC_CLIENT_ID=your-client-id
   OIDC_CLIENT_SECRET=your-secret
   OIDC_REDIRECT_URL=http://localhost:3000/api/v1/auth/callback
   

3. Users can login via GET /api/v1/auth/login/oidc

Feature Flags

Features are configured in api/Cargo.toml:

[features]
default = ["sqlite", "auth-axum-login", "auth-oidc", "auth-jwt"]

Feature	Description
sqlite	SQLite database support (default)
postgres	PostgreSQL database support
auth-axum-login	Session-based authentication
auth-oidc	OpenID Connect integration
auth-jwt	JWT token authentication
auth-full	All auth features combined

Common Configurations

JWT-only API (stateless):

default = ["sqlite", "auth-jwt"]

OIDC + JWT (typical SPA backend):

default = ["sqlite", "auth-oidc", "auth-jwt"]

Full-featured (all auth methods):

default = ["sqlite", "auth-full"]

API Endpoints

Authentication

Method	Endpoint	Description
POST	/api/v1/auth/login	Login with email/password
POST	/api/v1/auth/register	Register new user
POST	/api/v1/auth/logout	Logout (session mode)
GET	/api/v1/auth/me	Get current user
POST	/api/v1/auth/token	Get JWT for session user
GET	/api/v1/auth/login/oidc	Start OIDC login flow
GET	/api/v1/auth/callback	OIDC callback

Project Structure

k-template/
├── domain/          # Core business logic (no I/O dependencies)
│   └── src/
│       ├── entities.rs       # User entity
│       ├── value_objects.rs  # Email, Password, OIDC newtypes
│       ├── repositories.rs   # Repository interfaces (ports)
│       └── services.rs       # Domain services
│
├── infra/           # Infrastructure adapters
│   └── src/
│       ├── auth/             # Auth backends (OIDC, JWT)
│       └── user_repository.rs
│
├── api/             # HTTP API layer
│   └── src/
│       ├── routes/           # API endpoints
│       ├── config.rs         # Configuration
│       └── state.rs          # Application state
│
├── .env.example     # Configuration template
└── compose.yml      # Docker Compose for local dev

Development

Running Tests

# All tests
cargo test --all-features

# Domain tests only
cargo test -p domain

Database Migrations

# SQLite
sqlx migrate run --source migrations_sqlite

# PostgreSQL  
sqlx migrate run --source migrations_postgres

License

MIT