Application Skeleton

A fullstack application skeleton with authentication, database, and API documentation out of the box. Use this as a starting point for new web applications.

Tech Stack

• Backend: Spring Boot 3.4, Java 21, PostgreSQL 17, Flyway
• Frontend: Next.js 15, React 19, TypeScript, Tailwind CSS
• Auth: OAuth2/OIDC (via Spring Security + NextAuth.js)
• API Docs: Swagger UI / OpenAPI
• Containerization: Docker with multi-stage builds
• i18n: German and English

Getting Started

Prerequisites

• Docker and Docker Compose
• Java 21 (for local backend development)
• Node.js 22 and pnpm (for local frontend development)

Run with Docker Compose

docker compose up

This starts (using the development override with port mappings):

• PostgreSQL on localhost:${DB_PORT:-5432}
• Backend on localhost:${BACKEND_PORT:-9081}
• Frontend on localhost:${FRONTEND_PORT:-4001}
• Mock OAuth2 Server on localhost:${MOCK_OAUTH2_PORT:-8888}

Environment Variables

Database

Variable	Description	Default
DB_NAME	Database name	appdb
DB_USER	Database user	appuser
DB_PASSWORD	Database password	-
DB_PORT	Exposed DB port	5432

Backend

Variable	Description	Default
BACKEND_PORT	Exposed backend port	9081
SPRING_DATASOURCE_URL	JDBC connection URL	jdbc:postgresql://db:5432/${DB_NAME}
SPRING_DATASOURCE_USERNAME	DB username	${DB_USER}
SPRING_DATASOURCE_PASSWORD	DB password	${DB_PASSWORD}
OIDC_JWK_SET_URI	OIDC JWK Set URI	http://localhost:8888/default/jwks

Frontend

Variable	Description	Default
FRONTEND_PORT	Exposed frontend port	4001
BACKEND_URL	Backend API base URL	http://backend:8080
OIDC_ISSUER_URI	OIDC provider issuer URL	-
OIDC_CLIENT_ID	OAuth2 client ID	-
OIDC_CLIENT_SECRET	OAuth2 client secret	-
AUTH_SECRET	NextAuth session secret	-
AUTH_URL	Frontend base URL	http://localhost:4001

Project Structure

application-skeleton/
├── backend/                  # Spring Boot REST API
│   └── src/main/java/com/openelements/app/
│       ├── Application.java  # Main entry point
│       ├── SecurityConfig.java
│       ├── OpenApiConfig.java
│       ├── health/           # Health check endpoint
│       ├── user/             # User management (OAuth2)
│       ├── settings/         # Key-value settings store
│       └── ImageData.java   # Image/avatar storage entity
├── frontend/                 # Next.js frontend
│   └── src/
│       ├── app/              # Pages (App Router)
│       ├── components/       # React components
│       ├── lib/              # API client, types, i18n
│       └── auth.ts           # NextAuth configuration
├── docker-compose.yml        # Base service definitions
└── docker-compose.override.yml # Development overrides (ports, mock OAuth2)

Using a Real OIDC Provider (e.g. Authentik)

The development setup uses a mock OAuth2 server. For production, configure a real OIDC provider:

1. Create an OAuth2/OpenID Connect application in your provider (e.g. Authentik, Keycloak, Auth0).
2. Set the redirect URI to {AUTH_URL}/api/auth/callback/oidc (e.g. http://localhost:4001/api/auth/callback/oidc).
3. Update your .env file:

   OIDC_ISSUER_URI=https://auth.example.com/application/o/your-app/
   OIDC_JWK_SET_URI=https://auth.example.com/application/o/your-app/jwks/
   OIDC_CLIENT_ID=your-client-id
   OIDC_CLIENT_SECRET=your-client-secret

4. Remove or don't start the mock-oauth2 service. When using docker-compose.yml directly (without the override), the mock server is not included.

Features Included

• OAuth2/OIDC authentication flow (login, logout, token refresh)
• User profile with avatar upload
• Health check endpoint (GET /api/health)
• Key-value settings store
• Swagger UI at /swagger-ui.html
• Internationalization (DE/EN)
• Responsive sidebar navigation
• Docker multi-stage builds
• Mock OAuth2 server for development

License

Apache License 2.0