Installation

Auto-generate your docs

System Requirements
Required Software
Hardware Recommendations
Installation Steps
Configuration Reference
Database Settings
JWT Configuration
Hibernate Schema Management
Project Dependencies
Core Dependencies
Key Libraries
Database Initialization
Automatic Schema Creation
Initial Data Setup
API Documentation
Main Endpoints
Production Deployment
Build Production JAR
Run as System Service
Production Checklist
Troubleshooting
Common Issues
Logging
Next Steps

This guide covers everything you need to install, configure, and run the Authorization Service in development and production environments.

System Requirements

Required Software

Java Development Kit

JDK 21 or higherVerify installation:

java -version

PostgreSQL

PostgreSQL 12+ recommendedRunning on default port 5432

Maven

Maven 3.6+ (optional)Maven wrapper included in project

Git

Git for version controlClone the repository

Hardware Recommendations

Memory: Minimum 2GB RAM (4GB recommended)
Storage: 500MB free disk space
CPU: Any modern processor

Installation Steps

Install JDK 21

Download and install Java 21 from Oracle or use a package manager:

sudo apt update
sudo apt install openjdk-21-jdk

Verify the installation:

java -version
# Should show: openjdk version "21.x.x"

Install PostgreSQL

Install PostgreSQL database server:

sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

Clone the Repository

Clone the project from your version control system:

git clone <your-repository-url>
cd authorization-service

Create Database

Create a dedicated database for the service:

# Access PostgreSQL
sudo -u postgres psql

-- Create database
CREATE DATABASE autorization_db;

-- Create user (optional, for production)
CREATE USER auth_service WITH PASSWORD 'secure_password_here';

-- Grant privileges
GRANT ALL PRIVILEGES ON DATABASE autorization_db TO auth_service;

-- Exit
\q

Configure Application

Set up your environment variables. The service uses the following configuration from application.properties:

# Database Configuration
spring.datasource.url=jdbc:postgresql://localhost:5432/${DB_NAME}?options=-c%20TimeZone=America/Lima
spring.datasource.username=${DB_USERNAME}
spring.datasource.password=${DB_PASSWORD}
spring.datasource.driver-class-name=org.postgresql.Driver

# JPA/Hibernate Configuration
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true

# JWT Configuration
jwt.secret=${JWT_SECRET}
jwt.expiration-ms=${JWT_EXPIRATION_MS}

# Logging
app.logs.dir=logs

Never commit sensitive credentials to version control. Always use environment variables or external configuration.

Set Environment Variables

Configure the required environment variables:

export DB_NAME="autorization_db"
export DB_USERNAME="postgres"
export DB_PASSWORD="your_secure_password"
export JWT_SECRET="$(openssl rand -base64 32)"
export JWT_EXPIRATION_MS="86400000"

JWT_SECRET: Must be Base64-encoded, minimum 256 bits (32 bytes)
JWT_EXPIRATION_MS: Token lifetime in milliseconds (86400000 = 24 hours)

Build the Project

Compile the project using Maven:

# Using Maven wrapper (recommended)
./mvnw clean package -DskipTests

# Or with installed Maven
mvn clean package -DskipTests

This will create a JAR file in the target/ directory.

Run the Application

Start the Authorization Service:

./mvnw spring-boot:run

The service will start on port 8080 by default.

Verify Installation

Test that the service is running:

Health Check

curl http://localhost:8080/swagger-ui.html

You should see the Swagger UI documentation page.

Configuration Reference

Database Settings

The service uses Spring Data JPA with PostgreSQL:

Variable	Description	Default	Required
`DB_NAME`	PostgreSQL database name	-	Yes
`DB_USERNAME`	Database user	-	Yes
`DB_PASSWORD`	Database password	-	Yes

Connection URL Pattern:

jdbc:postgresql://localhost:5432/autorization_db?options=-c%20TimeZone=America/Lima

JWT Configuration

Variable	Description	Example	Required
`JWT_SECRET`	Secret key for signing tokens (Base64)	See below	Yes
`JWT_EXPIRATION_MS`	Token expiration time in milliseconds	`86400000`	Yes

Generate a secure JWT secret:

openssl rand -base64 32

Hibernate Schema Management

The spring.jpa.hibernate.ddl-auto property controls database schema handling:

update (Development): Automatically updates schema based on entities
validate (Production): Only validates schema, doesn’t modify
none (Production): No schema management

In production, use validate or none and manage schema with migration tools like Flyway or Liquibase.

Project Dependencies

From pom.xml, the service includes:

Core Dependencies

<!-- Spring Boot 4.0.2 -->
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>4.0.2</version>
</parent>

<!-- Java 21 -->
<properties>
    <java.version>21</java.version>
</properties>

Key Libraries

Spring Boot Web MVC 4.0.2: REST API framework
Spring Security 6: Authentication and authorization
Spring Data JPA: Database persistence
JJWT 0.12.6: JWT token generation and validation
SpringDoc OpenAPI 2.8.9: API documentation (Swagger UI)
PostgreSQL Driver: Database connectivity
Lombok: Reduce boilerplate code
Jakarta Validation: Request validation
Spring Dotenv 4.0.0: Environment variable management

Database Initialization

Automatic Schema Creation

With spring.jpa.hibernate.ddl-auto=update, Hibernate will automatically create tables for:

Users
Roles
Permissions
Modules
Activity Logs (Audit)
User-Role mappings
Role-Permission mappings

Initial Data Setup

You’ll need to create initial users and roles. Here’s a sample SQL script:

-- Insert default roles
INSERT INTO roles (id, name, description) VALUES
  (gen_random_uuid(), 'ADMIN', 'Administrator with full access'),
  (gen_random_uuid(), 'USER', 'Standard user');

-- Insert permissions
INSERT INTO permissions (id, name, description) VALUES
  (gen_random_uuid(), 'READ_PRIVILEGES', 'Can read resources'),
  (gen_random_uuid(), 'WRITE_PRIVILEGES', 'Can create/update resources');

-- Create admin user (password: password123)
INSERT INTO users (id, names, email, password, status, is_enabled) VALUES
  (gen_random_uuid(),
   'Admin User',
   '[email protected]',
   '$2a$10$...', -- BCrypt hash of 'password123'
   'ACTIVO',
   true);

-- Link admin user to ADMIN role
INSERT INTO user_roles (user_id, role_id)
SELECT u.id, r.id
FROM users u, roles r
WHERE u.email = '[email protected]'
  AND r.name = 'ADMIN';

Password hashes should be generated using BCrypt with strength 10. Use the service’s own user creation endpoint once you have an initial admin user.

API Documentation

Once running, access the interactive API documentation:

Swagger UI: http://localhost:8080/swagger-ui.html
OpenAPI JSON: http://localhost:8080/v3/api-docs

Main Endpoints

Endpoint	Method	Description	Auth Required
`/api/auth/login`	POST	Authenticate and get JWT token	No
`/api/users`	GET	List all users	Yes
`/api/users`	POST	Create new user	Yes (WRITE_PRIVILEGES)
`/api/users/{id}`	GET	Get user by ID	Yes (READ_PRIVILEGES)
`/api/users/{id}`	PUT	Update user	Yes (WRITE_PRIVILEGES)
`/api/users/{id}/activate`	PATCH	Activate user	Yes (WRITE_PRIVILEGES)
`/api/users/{id}/deactivate`	PATCH	Deactivate user	Yes (WRITE_PRIVILEGES)
`/api/users/{id}/roles/{roleId}`	POST	Assign role to user	Yes (WRITE_PRIVILEGES)
`/api/users/{id}/roles/{roleId}`	DELETE	Revoke role from user	Yes (WRITE_PRIVILEGES)
`/api/users/search`	GET	Search users (paginated)	Yes (READ_PRIVILEGES)
`/api/audit-logs`	GET	Query audit logs	Yes

Production Deployment

Build Production JAR

./mvnw clean package -DskipTests

This creates an executable JAR: target/autorization-0.0.1-SNAPSHOT.jar

Run as System Service

# Create service file: /etc/systemd/system/authorization.service
[Unit]
Description=Authorization Service
After=postgresql.service

[Service]
User=appuser
ExecStart=/usr/bin/java -jar /opt/authorization/autorization-0.0.1-SNAPSHOT.jar
EnvironmentFile=/opt/authorization/.env
SuccessExitStatus=143
TimeoutStopSec=10
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

# Enable and start
sudo systemctl enable authorization
sudo systemctl start authorization

Production Checklist

Security Configuration

Use strong, randomly generated JWT secret
Configure HTTPS/TLS
Set up CORS policies
Use environment-specific database credentials
Enable rate limiting
Configure secure session management

Database Configuration

Use connection pooling (HikariCP is included)
Set spring.jpa.hibernate.ddl-auto=validate
Disable spring.jpa.show-sql
Configure backup strategy
Set up read replicas (if needed)
Enable SSL for database connections

Monitoring & Logging

Configure centralized logging
Set up application monitoring (Prometheus, Grafana)
Enable Spring Boot Actuator endpoints
Configure log rotation
Set appropriate log levels
Monitor audit logs regularly

Performance

Troubleshooting

Common Issues

Port 8080 Already in Use

Change the port in environment variables:

export SERVER_PORT=8081
./mvnw spring-boot:run

Or add to application.properties:

server.port=8081

Database Connection Failed

Verify PostgreSQL is running:

sudo systemctl status postgresql

Test connection manually:

psql -h localhost -U postgres -d autorization_db

Check firewall rules and PostgreSQL pg_hba.conf configuration.

JWT Token Errors

SignatureException: JWT secret mismatch or corrupted token ExpiredJwtException: Token has expired, request a new one MalformedJwtException: Invalid token formatEnsure:

JWT secret is consistent across restarts
Secret is properly Base64-encoded
Token hasn’t expired (check JWT_EXPIRATION_MS)

Build Failures

Clean Maven cache and rebuild:

./mvnw clean install -U

Verify Java version:

java -version
javac -version

Both should show Java 21.

Logging

Application logs are written to:

Console output (during development)
logs/ directory (configurable via app.logs.dir)

Increase log verbosity for debugging:

logging.level.com.autorization=DEBUG
logging.level.org.springframework.security=DEBUG

Next Steps

Quick Start

Get your first JWT token in minutes

API Reference

Explore all available endpoints

Architecture

Learn about the hexagonal architecture

Security

Understand authentication and authorization

Quick Start

Hexagonal Architecture

⌘I

Build docs developers (and LLMs) love

Get started for free Talk to us

Get Started

Core Concepts

Guides

System Requirements

Required Software

Java Development Kit

PostgreSQL

Maven

Git

Hardware Recommendations

Installation Steps

Configuration Reference

Database Settings

JWT Configuration

Hibernate Schema Management

Project Dependencies

Core Dependencies

Key Libraries

Database Initialization

Automatic Schema Creation

Initial Data Setup

API Documentation

Main Endpoints

Production Deployment

Build Production JAR

Run as System Service

Production Checklist

Troubleshooting

Common Issues

Logging

Next Steps

Quick Start

API Reference

Architecture

Security

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​System Requirements

​Required Software

Java Development Kit

PostgreSQL

Maven

Git

​Hardware Recommendations

​Installation Steps

​Configuration Reference

​Database Settings

​JWT Configuration

​Hibernate Schema Management

​Project Dependencies

​Core Dependencies

​Key Libraries

​Database Initialization

​Automatic Schema Creation

​Initial Data Setup

​API Documentation

​Main Endpoints

​Production Deployment

​Build Production JAR

​Run as System Service

​Production Checklist

​Troubleshooting

​Common Issues

​Logging

​Next Steps

Quick Start

API Reference

Architecture

Security

Build docs developers (and LLMs) love

System Requirements

Required Software

Hardware Recommendations

Installation Steps

Configuration Reference

Database Settings

JWT Configuration

Hibernate Schema Management

Project Dependencies

Core Dependencies

Key Libraries

Database Initialization

Automatic Schema Creation

Initial Data Setup

API Documentation

Main Endpoints

Production Deployment

Build Production JAR

Run as System Service

Production Checklist

Troubleshooting

Common Issues

Logging

Next Steps