282 lines
9.1 KiB
Markdown
282 lines
9.1 KiB
Markdown
# Atlas CMMS - Enterprise Facilities Management System
|
|
|
|
A complete enterprise-grade CMMS (Computerized Maintenance Management System) built with Vue.js 3 frontend and Atlas CMMS backend, orchestrated with Docker Compose and Nginx Proxy Manager.
|
|
|
|
## 🏗️ Architecture Overview
|
|
|
|
```
|
|
┌─── Nginx Proxy Manager (SSL/Reverse Proxy) ───┐
|
|
│ ├── Frontend (Vue.js 3 + Vuetify) │
|
|
│ ├── Backend API (Atlas CMMS Spring Boot) │
|
|
│ ├── MinIO Console (Object Storage) │
|
|
│ └── Admin Interface │
|
|
└────────────────────────────────────────────────┘
|
|
│ │
|
|
┌────▼────┐ ┌─────▼─────┐
|
|
│PostgreSQL│ │ MinIO │
|
|
│Database │ │ Storage │
|
|
└─────────┘ └───────────┘
|
|
```
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
- Docker and Docker Compose
|
|
- Domain name (for SSL certificates)
|
|
- Ports 80, 443, and 81 available
|
|
|
|
### 1. Clone and Setup
|
|
```bash
|
|
git clone <your-repository>
|
|
cd atlas-cmms
|
|
cp .env.example .env
|
|
```
|
|
|
|
### 2. Configure Environment
|
|
Edit `.env` file with your settings:
|
|
```env
|
|
# Domain configuration
|
|
PUBLIC_API_URL=https://api.your-domain.com
|
|
PUBLIC_FRONT_URL=https://your-domain.com
|
|
|
|
# Database credentials
|
|
DB_USER=rootUser
|
|
DB_PASSWORD=your-secure-password
|
|
|
|
# JWT secret (minimum 32 characters)
|
|
JWT_SECRET_KEY=your-very-secure-jwt-secret-key-here
|
|
```
|
|
|
|
### 3. Start Services
|
|
```bash
|
|
# Production deployment
|
|
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
|
|
|
|
# Development setup
|
|
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d
|
|
```
|
|
|
|
### 4. Configure Nginx Proxy Manager
|
|
1. Access admin interface: `http://your-server-ip:81`
|
|
2. Login with default credentials:
|
|
- Email: `admin@example.com`
|
|
- Password: `changeme`
|
|
3. **Change credentials immediately!**
|
|
4. Configure proxy hosts (see [Nginx Proxy Manager Setup](./nginx-proxy-manager-setup.md))
|
|
|
|
## 📁 Project Structure
|
|
|
|
```
|
|
atlas-cmms/
|
|
├── frontend/ # Vue.js 3 frontend application
|
|
│ ├── src/
|
|
│ │ ├── components/ # Reusable Vue components
|
|
│ │ ├── views/ # Page components
|
|
│ │ ├── stores/ # Pinia state management
|
|
│ │ ├── services/ # API services and repositories
|
|
│ │ ├── composables/ # Vue composables
|
|
│ │ └── utils/ # Utility functions
|
|
│ ├── Dockerfile # Production frontend container
|
|
│ ├── Dockerfile.dev # Development frontend container
|
|
│ └── nginx.conf # Nginx configuration
|
|
├── backend/ # Backend configuration and assets
|
|
│ ├── logos/ # Custom branding assets
|
|
│ ├── scripts/ # Database backup/restore scripts
|
|
│ └── README.md # Backend documentation
|
|
├── monitoring/ # Monitoring and logging configuration
|
|
│ ├── prometheus.yml # Metrics collection config
|
|
│ └── loki-config.yml # Log aggregation config
|
|
├── docker-compose.yml # Base Docker Compose configuration
|
|
├── docker-compose.dev.yml # Development overrides
|
|
├── docker-compose.prod.yml # Production overrides
|
|
├── .env.example # Environment variables template
|
|
└── nginx-proxy-manager-setup.md # Proxy setup guide
|
|
```
|
|
|
|
## 🛠️ Services
|
|
|
|
### Core Services
|
|
- **Nginx Proxy Manager**: SSL termination and reverse proxy
|
|
- **Frontend**: Vue.js 3 application with Vuetify UI
|
|
- **Backend API**: Atlas CMMS Spring Boot application
|
|
- **PostgreSQL**: Primary database
|
|
- **MinIO**: Object storage for files and documents
|
|
|
|
### Development Services
|
|
- **Adminer**: Database administration interface
|
|
- **MailHog**: Email testing server
|
|
|
|
### Production Services
|
|
- **Watchtower**: Automatic container updates
|
|
- **Prometheus**: Metrics collection
|
|
- **Loki**: Log aggregation
|
|
|
|
## 🔧 Configuration
|
|
|
|
### Environment Variables
|
|
|
|
| Variable | Description | Default |
|
|
|----------|-------------|---------|
|
|
| `PUBLIC_API_URL` | External API URL | `http://localhost:8080` |
|
|
| `PUBLIC_FRONT_URL` | Frontend URL | `http://localhost:3000` |
|
|
| `DB_USER` | Database username | `rootUser` |
|
|
| `DB_PASSWORD` | Database password | `mypassword` |
|
|
| `JWT_SECRET_KEY` | JWT signing key | Required (32+ chars) |
|
|
| `MINIO_ROOT_USER` | MinIO admin username | `minioadmin` |
|
|
| `MINIO_ROOT_PASSWORD` | MinIO admin password | `minioadmin123` |
|
|
|
|
### SSL Certificates
|
|
Nginx Proxy Manager provides automatic Let's Encrypt certificates:
|
|
1. Configure proxy host in NPM admin interface
|
|
2. Request SSL certificate for your domain
|
|
3. Enable "Force SSL" and "HTTP/2 Support"
|
|
|
|
## 📊 Features
|
|
|
|
### Frontend (Vue.js 3)
|
|
- **Modern UI**: Vuetify 3 Material Design components
|
|
- **State Management**: Pinia stores with TypeScript support
|
|
- **Authentication**: JWT-based with role-based access control
|
|
- **Repository Pattern**: Clean API abstraction layer
|
|
- **Responsive Design**: Mobile-first approach
|
|
- **Enterprise Architecture**: Separation of concerns, modular design
|
|
|
|
### Backend (Atlas CMMS)
|
|
- **Work Order Management**: Complete lifecycle management
|
|
- **Asset Management**: Asset tracking with history and files
|
|
- **User Management**: Role-based permissions
|
|
- **Inventory Control**: Stock management and tracking
|
|
- **Maintenance Scheduling**: Preventive maintenance planning
|
|
- **Reporting**: Comprehensive analytics and reports
|
|
- **API Integration**: RESTful API with OpenAPI documentation
|
|
|
|
## 🚀 Deployment
|
|
|
|
### Development
|
|
```bash
|
|
# Start development environment
|
|
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up
|
|
|
|
# Access services:
|
|
# - Frontend: http://localhost:3000
|
|
# - API: http://localhost:8080
|
|
# - Database: localhost:5432
|
|
# - Adminer: http://localhost:8081
|
|
# - MailHog: http://localhost:8025
|
|
```
|
|
|
|
### Production
|
|
```bash
|
|
# Start production environment
|
|
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
|
|
|
|
# Access services through Nginx Proxy Manager:
|
|
# - Admin Interface: http://your-server:81
|
|
# - Frontend: https://your-domain.com
|
|
# - API: https://api.your-domain.com
|
|
```
|
|
|
|
## 🔍 Monitoring
|
|
|
|
### Health Checks
|
|
- API health endpoint: `/api/health`
|
|
- Frontend health endpoint: `/health`
|
|
- Automatic container health monitoring
|
|
|
|
### Metrics (Production)
|
|
- **Prometheus**: Metrics collection at `http://localhost:9090`
|
|
- **Application Metrics**: API performance, database connections
|
|
- **System Metrics**: CPU, memory, disk usage
|
|
- **Custom Dashboards**: Grafana integration ready
|
|
|
|
### Logging
|
|
- **Centralized Logging**: Loki log aggregation
|
|
- **Application Logs**: API and frontend logs
|
|
- **Access Logs**: Nginx request logs
|
|
- **Error Tracking**: Structured error logging
|
|
|
|
## 🔒 Security
|
|
|
|
### Best Practices Implemented
|
|
- **SSL/TLS**: Automatic certificate management
|
|
- **JWT Authentication**: Secure token-based auth
|
|
- **Role-Based Access**: Fine-grained permissions
|
|
- **Security Headers**: CORS, XSS, and CSRF protection
|
|
- **Container Security**: Non-root users, minimal images
|
|
- **Network Isolation**: Docker network segmentation
|
|
|
|
### Security Checklist
|
|
- [ ] Change all default passwords
|
|
- [ ] Configure strong JWT secret key
|
|
- [ ] Enable SSL certificates
|
|
- [ ] Configure firewall rules
|
|
- [ ] Set up regular backups
|
|
- [ ] Enable monitoring and alerting
|
|
- [ ] Review user permissions regularly
|
|
|
|
## 📦 Backup and Restore
|
|
|
|
### Database Backup
|
|
```bash
|
|
# Create backup
|
|
./backend/scripts/backup-db.sh
|
|
|
|
# Restore backup
|
|
./backend/scripts/restore-db.sh ./backups/atlas_backup_YYYYMMDD_HHMMSS.sql.gz
|
|
```
|
|
|
|
### Configuration Backup
|
|
```bash
|
|
# Backup Nginx Proxy Manager config
|
|
docker exec nginx-proxy-manager tar -czf /tmp/npm-backup.tar.gz /data
|
|
docker cp nginx-proxy-manager:/tmp/npm-backup.tar.gz ./backups/
|
|
```
|
|
|
|
## 🛠️ Development
|
|
|
|
### Frontend Development
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
### API Development
|
|
The backend uses the official Atlas CMMS Docker image. For custom development:
|
|
1. Fork the Atlas CMMS repository
|
|
2. Build custom Docker image
|
|
3. Update docker-compose.yml image reference
|
|
|
|
### Contributing
|
|
1. Follow established code patterns
|
|
2. Use TypeScript for new frontend code
|
|
3. Test all changes in development environment
|
|
4. Update documentation as needed
|
|
|
|
## 📚 Documentation
|
|
|
|
- [Frontend Documentation](./frontend/README.md)
|
|
- [Backend Documentation](./backend/README.md)
|
|
- [Nginx Proxy Manager Setup](./nginx-proxy-manager-setup.md)
|
|
- [Atlas CMMS User Guide](https://grashjs.github.io/user-guide/)
|
|
|
|
## 🆘 Support
|
|
|
|
### Troubleshooting
|
|
1. Check container logs: `docker logs <container-name>`
|
|
2. Verify network connectivity: `docker network ls`
|
|
3. Review environment variables: `docker-compose config`
|
|
4. Check service health: `docker-compose ps`
|
|
|
|
### Getting Help
|
|
- **Atlas CMMS Issues**: https://github.com/Grashjs/cmms/issues
|
|
- **Atlas CMMS Email**: contact@atlas-cmms.com
|
|
- **Documentation**: https://grashjs.github.io/user-guide/
|
|
|
|
## 📄 License
|
|
|
|
This project is licensed under the MIT License. See the LICENSE file for details.
|
|
|
|
---
|
|
|
|
**Atlas CMMS** - Enterprise Facilities Management Made Simple |