JAngular CLI Documentation

Getting Started

What is JAngular CLI?

JAngular CLI is a comprehensive command-line interface tool for rapidly bootstrapping enterprise-grade full-stack applications. It combines Angular 17+ (frontend) with Spring Boot 3.x (Java 21 backend), providing integrated security, authentication, database management, Docker containerization, and deployment strategies. The tool follows industry best practices and generates production-ready code with comprehensive documentation.

What are the system requirements?

To use JAngular CLI, you need:

Node.js - Version 18.x or higher
Java - JDK 21 or higher (Eclipse Temurin recommended)
Maven - Version 3.6.0 or higher
Angular CLI - Version 17.x or higher
Docker - Latest stable version (optional but recommended)
Git - For version control and project management

How do I install JAngular CLI?

Install JAngular CLI globally using npm:

# Install JAngular CLI npm install -g jangular-cli # Verify installation jangular --version # Check system requirements jangular --test

Do I need to install Angular CLI separately?

Yes, Angular CLI is a prerequisite. Install it globally before using JAngular:

# Install Angular CLI npm install -g @angular/cli@^17.0.0 # Verify Angular CLI installation ng version

Project Creation & Configuration

How do I create a new project?

Create a new JAngular project using the init command:

# Create new project jangular init my-enterprise-app # Create with custom configuration jangular init my-app --group-id com.mycompany --artifact-id backend-service

Can I customize the project structure during initialization?

Yes, JAngular CLI provides several customization options during project creation:

Java Package Structure - Custom group ID and artifact ID
Database Selection - Choose between MySQL, PostgreSQL, or SQL Server
Authentication Configuration - JWT settings and security policies
Project Name - Custom application name and metadata

What happens after project creation?

JAngular generates a complete project structure with:

Spring Boot backend with security configuration
Angular frontend with authentication components
Docker configuration for all services
Database migrations and initial schema
Comprehensive documentation and README files
CI/CD pipeline templates

Database Management

Which databases are supported?

JAngular supports multiple enterprise databases:

MySQL 8.0+ - Popular open-source database with excellent performance
PostgreSQL 13+ - Advanced open-source database with JSON support
Microsoft SQL Server 2019+ - Enterprise database for Windows environments

How do database migrations work?

JAngular uses Flyway for robust database migration management:

Versioned Migrations - Sequential SQL scripts with version control
Database-Specific Scripts - Optimized SQL for each database type
Automatic Execution - Migrations run automatically on application startup
Rollback Support - Safe rollback capabilities for failed migrations
Environment Consistency - Same schema across development, staging, and production

Can I change the database after project creation?

While possible, it requires manual configuration changes:

Update database dependencies in pom.xml
Modify database configuration in application.properties
Replace Flyway migration scripts with database-specific versions
Update Docker Compose configuration
Test thoroughly in development environment

For significant changes, creating a new project is often more efficient.

How do I connect to external databases?

Update the database configuration in your environment-specific properties files:

# application-prod.properties spring.datasource.url=jdbc:mysql://production-db.example.com:3306/myapp spring.datasource.username=prod_user spring.datasource.password=secure_password spring.jpa.hibernate.ddl-auto=validate

Authentication & Security

How is authentication implemented?

JAngular implements comprehensive JWT-based authentication:

Access Tokens - Short-lived JWT tokens for API authentication (15 minutes default)
Refresh Tokens - Long-lived tokens for session renewal (7 days default)
Automatic Refresh - Seamless token renewal without user intervention
Secure Storage - Browser storage with automatic cleanup
Token Blacklisting - Immediate invalidation on logout

What security features are included?

JAngular provides enterprise-grade security features:

Password Security - BCrypt hashing with configurable strength
Account Protection - Automatic lockout after failed attempts
Password Policies - Complexity requirements and history tracking
CSRF Protection - Cross-site request forgery prevention
CORS Configuration - Flexible cross-origin resource sharing
SQL Injection Prevention - Parameterized queries and JPA protection
XSS Protection - Output encoding and sanitization

Can I customize the authentication system?

Yes, the authentication system is fully customizable:

JWT Configuration - Custom secret keys and token expiration
Additional Providers - OAuth2, LDAP, or custom authentication
Password Policies - Custom complexity and history requirements
Role-Based Access - Custom roles and permission systems
Security Headers - Additional security header configuration

How do I implement role-based access control?

JAngular includes built-in RBAC with three default roles:

ROLE_USER - Standard user permissions
ROLE_MODERATOR - Enhanced permissions for content management
ROLE_ADMIN - Full administrative access

You can extend this system by adding custom roles and permissions in the backend security configuration.

Frontend Development

What frontend technologies are used?

The JAngular frontend leverages modern Angular features:

Angular 17+ - Latest Angular with standalone components
TypeScript 5.0+ - Strong typing and modern JavaScript features
Tailwind CSS - Utility-first CSS framework
RxJS - Reactive programming for asynchronous operations
Angular Signals - Modern state management
Control Flow Syntax - New @if, @for, @switch directives

Can I customize the UI framework?

Yes, you can replace or supplement Tailwind CSS:

Bootstrap - Add Bootstrap for component-based styling
Angular Material - Integrate Material Design components
PrimeNG - Rich UI component library
Custom CSS - Implement your own design system

How do I add new components?

Use Angular CLI commands within the frontend directory:

# Navigate to frontend directory cd frontend # Generate new component ng generate component features/my-feature # Generate service ng generate service services/my-service # Generate guard ng generate guard guards/my-guard

What routing patterns are implemented?

The frontend uses advanced Angular routing:

Lazy Loading - Feature modules loaded on demand
Route Guards - Authentication and authorization protection
Route Resolvers - Pre-load data before navigation
Deep Linking - Bookmarkable URLs with state restoration
Route Preloading - Strategic module preloading

Backend Development

What backend technologies are used?

The JAngular backend uses modern Spring ecosystem:

Spring Boot 3.x - Modern Spring framework with Java 21
Spring Security 6.x - Comprehensive security framework
Spring Data JPA - Data access layer with Hibernate
Spring Web - RESTful web services
Flyway - Database migration management
Maven - Dependency management and build tool

How do I add new API endpoints?

Follow the established patterns in the generated code:

Create Entity - JPA entity in the entity package
Create Repository - JPA repository interface
Create Service - Business logic in the service package
Create Controller - REST endpoints in the controller package
Create DTOs - Data transfer objects for API responses
Add Tests - Unit and integration tests

How is the backend structured?

The backend follows Spring Boot best practices:

Package Organization - Separation by feature and layer
Configuration Classes - Centralized configuration management
Exception Handling - Global exception handling with custom responses
Validation - Bean validation with custom validators
Documentation - OpenAPI 3.0 specification generation

What Java version is required?

JAngular requires Java 21 or higher. This is because:

Spring Boot 3.x requires Java 17+ as minimum
Java 21 provides the latest LTS features and performance improvements
Modern language features improve code quality and maintainability
Better performance and memory management

Docker & Containerization

What Docker features are included?

JAngular provides comprehensive Docker integration:

Multi-Stage Builds - Optimized Docker images with minimal size
Docker Compose - Complete application stack orchestration
Database Services - Containerized database with persistent storage
Database Administration - Web-based database management tools
Production Configuration - Separate production Docker Compose setup
Health Checks - Container health monitoring

Do I need Docker to use JAngular?

Docker is optional but highly recommended:

Without Docker - Run backend with Maven and frontend with Angular CLI
With Docker - Consistent environment across development and production
Database - Docker simplifies database setup and management
Deployment - Docker enables easy deployment to cloud platforms

How do I manage Docker services?

Use the interactive Docker management command:

# Launch Docker management interface jangular docker # Manual Docker Compose commands docker-compose up -d          # Start all services docker-compose logs -f        # View logs docker-compose down          # Stop services docker-compose down -v       # Stop and remove volumes

What's included in the Docker setup?

The Docker configuration includes:

Application Services - Backend and frontend containers
Database Service - MySQL, PostgreSQL, or SQL Server
Database GUI - phpMyAdmin, pgAdmin, or SSMS
Network Configuration - Service discovery and communication
Volume Management - Persistent data storage
Environment Variables - Configuration management

Development Workflow

What's the recommended development workflow?

Follow this workflow for optimal development experience:

Project Setup - Initialize project with jangular init
Install Dependencies - Run npm run install:all
Start Services - Use Docker or run services directly
Development - Develop with hot reload enabled
Testing - Run tests with jangular test
Building - Build for production with jangular build --prod
Deployment - Deploy using Docker or cloud platforms

How do I run the application in development?

You have multiple options for development:

Option 1: Docker (Recommended)

# Start complete development stack docker-compose up -d # View logs docker-compose logs -f

Option 2: Direct Execution

# Terminal 1: Start backend npm run start:backend # Terminal 2: Start frontend npm run start:frontend

How do I test the application?

JAngular provides comprehensive testing capabilities:

# Run all tests jangular test # Run backend tests only jangular test --backend # Run frontend tests only jangular test --frontend # System requirements test jangular --test

How do I build for production?

Build optimized production artifacts:

# Build everything for production jangular build --all --prod # Build specific components jangular build --backend --prod jangular build --frontend

Deployment & Production

What deployment options are available?

JAngular supports multiple deployment strategies:

Docker Compose - Simple containerized deployment
Cloud Platforms - AWS, GCP, Azure with container services
Kubernetes - Scalable orchestration with provided manifests
Traditional Servers - JAR deployment with reverse proxy

How do I deploy to cloud platforms?

JAngular includes guides for major cloud providers:

AWS - ECS, EKS, and Elastic Beanstalk deployment
Google Cloud - Cloud Run, GKE, and App Engine deployment
Azure - Container Instances, AKS, and App Service deployment
DigitalOcean - App Platform and Kubernetes deployment

What about CI/CD integration?

The generated project includes CI/CD templates for:

GitHub Actions - Complete workflow with testing and deployment
GitLab CI/CD - Pipeline configuration with Docker integration
Jenkins - Jenkinsfile for traditional CI/CD setups
Azure DevOps - Pipeline templates for Microsoft ecosystem

Troubleshooting

What if the requirements check fails?

Run the system requirements test to identify issues:

# Check system requirements jangular --test # Common issues and solutions: # - Node.js version: Update to version 18+ # - Java version: Install JDK 21+ # - Maven: Install Maven 3.6.0+ # - Angular CLI: Install @angular/cli@^17.0.0

How do I resolve port conflicts?

Default ports used by JAngular:

Frontend - Port 4200 (Angular dev server)
Backend - Port 8080 (Spring Boot)
Database - Port 3306 (MySQL), 5432 (PostgreSQL), 1433 (SQL Server)
Database GUI - Port 8081 (phpMyAdmin), 5050 (pgAdmin)

Modify ports in docker-compose.yml or application configuration files.

What if Docker services fail to start?

Common Docker troubleshooting steps:

Check Docker is running: docker --version
Check port availability: netstat -an | grep :8080
Clean Docker resources: docker-compose down -v
Rebuild images: docker-compose build --no-cache
Check logs: docker-compose logs

How do I resolve database connection issues?

Database connection troubleshooting:

Verify database is running: docker-compose ps
Check database health: Use the Docker management menu
Verify credentials in application.properties
Check network connectivity between services
Review database logs: docker-compose logs mysql

What if frontend build fails?

Frontend build troubleshooting:

Clear npm cache: npm cache clean --force
Delete node_modules: rm -rf node_modules && npm install
Check Angular CLI version: ng version
Update dependencies: npm update
Check for TypeScript errors: ng build --verbose

Support & Community

How do I get help?

Multiple support channels are available:

Documentation - Comprehensive guides covering all features
GitHub Issues - Report bugs and request features
Community Discussions - Ask questions and share solutions
Stack Overflow - Tag questions with "jangular-cli"

How do I report issues?

When reporting issues on GitHub, include:

System Information - OS, Node.js, Java, and CLI versions
Steps to Reproduce - Exact commands and actions taken
Error Messages - Complete error output and stack traces
Expected Behavior - What should have happened
Configuration - Relevant configuration files and settings

How can I contribute to JAngular?

Contributions are welcome in many forms:

Bug Reports - Help identify and fix issues
Feature Requests - Suggest new functionality
Documentation - Improve guides and examples
Code Contributions - Submit pull requests
Testing - Test on different platforms and configurations
Community Support - Help other users in discussions

How do I stay updated?

Keep up with JAngular developments:

GitHub Releases - Watch the repository for new releases
CLI Notifications - Automatic update notifications
Release Notes - Detailed changelog for each version
Breaking Changes - Migration guides for major updates

How do I update JAngular CLI?

Keep your CLI installation current:

# Update to latest version npm install -g jangular-cli@latest # Check current version jangular --version # View available updates npm outdated -g jangular-cli

Community Support: JAngular is an open-source project that thrives on community contributions. Whether you're reporting issues, suggesting features, or helping other developers, your participation helps make JAngular better for everyone.

Frequently Asked Questions