generator-jhipster-rust

JHipster blueprint for generating Rust backends with Axum

Introduction

This is a JHipster blueprint that generates a Rust backend using the Axum web framework as an alternative to the traditional Spring Boot backend. It enables you to leverage Rust's performance, safety, and low memory footprint while keeping the familiar JHipster development experience and Angular/React/Vue frontend.

The generated Rust server provides a complete REST API implementation with authentication, user management, entity CRUD operations, and full compatibility with JHipster's frontend clients.

Implemented Features

| Category | Feature | Notes | | ------------------------ | ---------------------------- | -------------------------------------------- | | Backend Framework | Axum web framework | Async HTTP server with Tower middleware | | | Tokio async runtime | High-performance async I/O | | | Structured logging (tracing) | Request tracing and structured logs | | Databases | SQLite | Default option, no external server needed | | | PostgreSQL | Full support with Diesel ORM | | | MySQL | Full support with Diesel ORM | | | MongoDB | Native driver with ObjectId, embedded docs | | Authentication | JWT (JSON Web Tokens) | Stateless auth with configurable expiry | | | OAuth2/OIDC (Keycloak) | Full OIDC flow with JWKS validation | | | Role-based access control | ROLE_USER, ROLE_ADMIN authorities | | User Management | User CRUD operations | Create, read, update, delete users | | | Password hashing (Argon2) | Secure password storage | | | Authority management | Assign/remove user roles | | Entity Generation | Basic CRUD endpoints | GET, POST, PUT, DELETE for entities | | | Field types & validations | String, Integer, Boolean, Date, Blob, etc. | | | Pagination & sorting | Page-based results with sort params | | | Relationships | ManyToOne, OneToMany, OneToOne, ManyToMany | | API Documentation | Swagger UI | Interactive API explorer at /swagger-ui | | | Scalar UI | Modern API docs at /scalar | | | OpenAPI 3.0 spec | JSON spec at /api-docs/openapi.json | | Frontend | Angular | Full JHipster Angular client | | | React | Full JHipster React client | | | Vue | Full JHipster Vue client | | Deployment | Docker support | Multi-stage Dockerfile | | | Docker Compose | Full stack with DB containers | | | Monolithic mode | Serve SPA from Rust backend | | | Microservice mode | API-only service for microservices arch | | | Consul Service Discovery | Service registration, discovery, KV config | | Testing | Rust unit tests | Service and handler tests | | | Cypress E2E tests | End-to-end UI testing | | Email | SMTP email service | Lettre + Tera templates | | | Account activation | Email verification for registration | | | Password reset | Forgot password flow with email | | Message Brokers | Apache Kafka | High-throughput async messaging (rdkafka) | | Monitoring | Prometheus metrics | HTTP request metrics with Grafana dashboards | | CI/CD | GitHub Actions | Build, test, lint, Docker publish | | | GitLab CI | Build, test, lint, Docker publish | | | Local CI with act | Run GitHub Actions locally in Docker | | Developer Experience | Hot reload (cargo-watch) | Auto-rebuild on file changes | | | Environment config (.env) | Flexible configuration | | | Health endpoints | /api/health, /management/info |

Prerequisites

As this is a JHipster blueprint, we expect you have JHipster basic knowledge:

• JHipster

Documentation

Entity Generation

• Entity Generation Guide - Field types, validations, pagination, and relationships

Supported Databases

• SQLite Integration - Default database setup (no external server required)
• PostgreSQL Integration - Setting up PostgreSQL database with macOS configuration
• MySQL Integration - Setting up MySQL database with macOS configuration
• MongoDB Integration - NoSQL document database with ObjectId, embedded documents, and replica set support

Security & Authentication

• Security Guide - JWT and OAuth2/OIDC authentication options
• Keycloak Integration - Detailed Keycloak setup and configuration

Email Integration

• Email Integration Guide - SMTP configuration, email templates, and local development with MailHog

API Documentation

• OpenAPI/Swagger Guide - Swagger UI, Scalar UI, and OpenAPI 3.0 specification

Testing

• Testing Guide - Unit tests, integration tests, and Cypress E2E testing

Message Brokers

• Apache Kafka Guide - High-throughput messaging with rdkafka, REST endpoints, and Docker setup

Monitoring

• Prometheus Monitoring - Metrics collection with Prometheus and Grafana dashboards

CI/CD

• CI/CD Integration - GitHub Actions, GitLab CI, and running locally with act

Generate CI/CD configuration for your project:

jhipster-rust ci-cd

This supports:

• GitHub Actions - .github/workflows/main.yml with build, test, lint, and optional Docker publishing
• GitLab CI - .gitlab-ci.yml with equivalent pipeline stages
• Local testing - Run GitHub Actions locally using act

Deployment

• Docker Guide - Container setup, Docker Compose, and deployment options
• Static UI Hosting - Serve SPA from Rust backend in monolithic mode
• Microservices Architecture - Deploy as part of a microservices architecture
• Consul Service Discovery - Service registration, discovery, and configuration management
• Monolithic Deployment - Quick start guide for monolithic deployment
• Microservice Deployment - Quick start guide for microservice deployment

Installation

To install or update this blueprint:

npm install -g generator-jhipster-rust

Usage

To use this blueprint, run the below command

jhipster-rust

You can look for updated rust blueprint specific options by running

```bash
jhipster-rust app --help

And looking for (blueprint option: rust) like

Plugin Development USAGE

To begin to work:

• launch: npm install
• link: npm link
• link JHipster: npm link generator-jhipster
• test your module in a JHipster project:
  • create a new directory and go into it
  • link the blueprint: npm link generator-jhipster-undefined
  • launch JHipster with flags: jhipster --blueprints undefined
• then, come back here, and begin to code!

Pre-release

To use an unreleased version, install it using git.

npm install -g jhipster/generator-jhipster-rust#main
jhipster --blueprints rust --skip-jhipster-dependencies

Monolithic Deployment

For monolithic applications, you can serve the SPA UI directly from the Rust backend. This enables single-server deployment where the Rust backend serves both API endpoints and the SPA frontend.

Building the SPA Client

1. Build the SPA client for production:

   cd client
   npm run build

2. Copy the built files to a location the server can access:

   mkdir -p dist/static
   cp -r client/dist/<baseName>/browser/* dist/static/

Configuration

Enable static file serving by setting these environment variables in your .env file:

| Variable | Description | Default | | -------------------- | --------------------------------------------------------- | --------------- | | SERVE_STATIC_FILES | Set to true to enable static file serving | false | | STATIC_FILES_DIR | Path to the directory containing the built Angular app | ./dist/static | | APP_HTTPS | Set to true when using HTTPS (for OAuth2 redirect URLs) | false |

Example .env configuration:

SERVE_STATIC_FILES=true
STATIC_FILES_DIR=./dist/static
# APP_HTTPS=true  # Uncomment for production with TLS

Running the Server

cd server
cargo run

The server will:

• Serve API endpoints at /api/*
• Serve static files from the configured directory
• Fall back to index.html for Angular routes (SPA routing)

Access the application at http://localhost:8080 (or your configured APP_PORT).

OAuth2/Keycloak Considerations

When using OAuth2 authentication with SERVE_STATIC_FILES=true:

• The server automatically redirects to itself after authentication (instead of a separate frontend URL)
• Set APP_HTTPS=true in production when behind a TLS-terminating proxy
• Ensure your Keycloak client has the correct redirect URI configured (e.g., http://localhost:8080/*)

Microservice Deployment

For microservice applications, the Rust backend serves as a standalone API service without UI, designed to work with a separate gateway application.

Key Characteristics

• API-only: No static file serving, UI is handled by gateway
• Stateless: JWT tokens enable horizontal scaling
• Independent: Each microservice has its own database
• Discoverable: Health endpoints for container orchestration
• Service Discovery: Optional Consul integration for auto-registration and discovery (see Consul Guide)

Configuration

Configure your microservice with a unique port:

APP_PORT=8081  # Use unique port for each microservice
JWT_SECRET=shared-jwt-secret-across-microservices  # Same secret for all services

Running the Microservice

cd server
cargo run

The microservice will:

• Expose REST API endpoints at /api/*
• Provide health checks at /api/health
• Validate JWT tokens from the gateway

Docker Deployment

Build and run with Docker:

docker build -t myservice:latest .
docker run -p 8081:8081 -e JWT_SECRET=shared-secret myservice:latest

For detailed microservice architecture guidance, see Microservices Architecture Guide.

Not Yet Implemented

The following features from the base JHipster generator are planned for future versions:

High Priority (Core Microservices Features)

| Feature | Notes | | ------------------------- | -------------------------------------------------- | | Inter-service HTTP Client | Feign-like client with automatic token propagation | | Circuit Breaker | Resilience4j equivalent | | Kubernetes Manifests | No K8s deployment, service, ingress generation |

Medium Priority (Enterprise Features)

| Feature | Notes | | --------------------- | -------------------------------------------------------- | | Cloud Configuration | Spring Cloud Config equivalent for remote config loading | | Pulsar Message Broker | Apache Pulsar integration (Kafka is already supported) | | Distributed Tracing | Zipkin/Jaeger integration for request tracing | | Caching (Redis) | Redis dependencies or caching layer | | Gateway Routing Logic | Dynamic route management or request forwarding |

Lower Priority (Nice to Have)

| Feature | Notes | | -------------------- | -------------------------------------------------- | | WebSocket Support | tokio-tungstenite or STOMP messaging | | Additional Databases | Cassandra, Neo4j, Couchbase, MSSQL, Oracle support | | Elasticsearch | full-text search integration | | Helm Charts | Helm chart generation for Kubernetes | | Rate Limiting | throttle/rate limit middleware | | API Versioning | Routes don't use /v1, /v2 prefixes | | GraphQL | async-graphql support | | Embedded Assets | rust-embed for single-binary static files |