cmms/backend/README.md

Atlas CMMS Backend

This directory contains the backend configuration and assets for the Atlas CMMS system.

Overview

The backend uses the official Atlas CMMS Docker image (intelloop/atlas-cmms-backend) which provides:

• Spring Boot API: Java 8 based REST API
• PostgreSQL Integration: Database for all CMMS data
• MinIO Integration: Object storage for files and documents
• JWT Authentication: Secure token-based authentication
• Role-based Access Control: Multi-level user permissions
• Email Notifications: SMTP support for system notifications
• OAuth2 Support: Google and Microsoft SSO integration

Directory Structure

backend/
├── logos/              # Custom logo files for branding
├── config/             # Configuration files
├── scripts/            # Utility scripts
└── README.md          # This file

Configuration

The backend is configured through environment variables defined in the main .env file:

Database Configuration

• DB_USER: PostgreSQL username
• DB_PASSWORD: PostgreSQL password
• Database name is set to atlas by default

API Configuration

• PUBLIC_API_URL: External API URL (e.g., http://localhost:8080)
• JWT_SECRET_KEY: Secret key for JWT token signing (minimum 32 characters)
• PUBLIC_FRONT_URL: Frontend URL for CORS and redirects

Storage Configuration

• MINIO_ROOT_USER: MinIO admin username
• MINIO_ROOT_PASSWORD: MinIO admin password
• MINIO_BUCKET_NAME: Bucket name for file storage

Email Configuration (Optional)

• SMTP_HOST: SMTP server hostname
• SMTP_PORT: SMTP server port (default: 587)
• SMTP_USER: SMTP username
• SMTP_PASSWORD: SMTP password
• MAIL_FROM: From email address

Optional Features

• ENABLE_SSO: Enable Single Sign-On (true/false)
• ENABLE_INVITATIONS: Enable user invitations (true/false)

OAuth2 Configuration (Optional)

• GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET: Google OAuth2 credentials
• MICROSOFT_CLIENT_ID / MICROSOFT_CLIENT_SECRET: Microsoft OAuth2 credentials

Custom Branding

Place custom logo files in the logos/ directory. The backend will mount this directory and make logos available for the application.

Supported formats:

• PNG
• JPG/JPEG
• SVG

API Endpoints

The Atlas CMMS backend provides comprehensive REST API endpoints:

Authentication

• POST /api/auth/signin - User login
• POST /api/auth/signup - User registration
• POST /api/auth/logout - User logout
• POST /api/auth/refresh - Token refresh

Work Orders

• GET /api/work-orders - List work orders
• POST /api/work-orders - Create work order
• GET /api/work-orders/{id} - Get work order details
• PUT /api/work-orders/{id} - Update work order
• DELETE /api/work-orders/{id} - Delete work order

Assets

• GET /api/assets - List assets
• POST /api/assets - Create asset
• GET /api/assets/{id} - Get asset details
• PUT /api/assets/{id} - Update asset
• DELETE /api/assets/{id} - Delete asset

Users

• GET /api/users - List users
• POST /api/users - Create user
• GET /api/users/me - Get current user
• PUT /api/users/{id} - Update user

Health Checks

The backend includes health check endpoints:

• GET /api/health - Application health status
• GET /api/info - Application information

Development

Running Locally

To run the backend locally outside of Docker:

1. Install Java 8 JDK
2. Set up PostgreSQL database
3. Configure environment variables
4. Build and run the Spring Boot application

Custom Development

If you need to customize the backend:

1. Fork the Atlas CMMS repository
2. Make your changes
3. Build your own Docker image
4. Update the docker-compose.yml to use your custom image

Support

For backend-specific issues:

• Check the Atlas CMMS documentation: https://grashjs.github.io/user-guide/
• File issues at: https://github.com/Grashjs/cmms/issues
• Contact: contact@atlas-cmms.com

Security Considerations

• Change default passwords in production
• Use strong JWT secret keys (minimum 32 characters)
• Enable HTTPS in production environments
• Regularly update the Docker images
• Secure your PostgreSQL and MinIO instances
• Use proper firewall rules and network security