133 lines
3.9 KiB
Markdown
133 lines
3.9 KiB
Markdown
# IT Hardware Asset Management System
|
|
|
|
A full-featured web application built with **Python / Flask + MySQL**, containerised with **Docker Compose**.
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
| Module | Capabilities |
|
|
|---|---|
|
|
| **Users** | Manual, CSV, and LDAP/AD import · search · GDPR masking |
|
|
| **Assets** | Track by Serial Number + Service Tag · full history |
|
|
| **Assignments** | Assign/return assets · complete audit trail |
|
|
| **Paperwork** | Generate PDF documents (handover, assignment, return, custom) |
|
|
| **Audit Log** | Immutable log of every create / update / delete / mask action |
|
|
| **Settings** | Admin user management · LDAP config view |
|
|
|
|
### User masking (GDPR / off-boarding)
|
|
When an employee leaves, press **Mask User** to permanently erase PII (name, email, phone).
|
|
The record is kept — linked by the permanent **Windows ID** — so full asset history is preserved for audits, without exposing personal data.
|
|
|
|
---
|
|
|
|
## Quick Start (Docker Compose)
|
|
|
|
```bash
|
|
# 1. Copy the example env file and fill in your values
|
|
cp .env.example .env
|
|
nano .env
|
|
|
|
# 2. Build and start
|
|
docker compose up -d --build
|
|
|
|
# 3. Open the app
|
|
http://localhost:5000
|
|
|
|
# Default credentials (change immediately in Settings!)
|
|
Username: admin
|
|
Password: ChangeMe123!
|
|
```
|
|
|
|
---
|
|
|
|
## Running locally (without Docker)
|
|
|
|
```bash
|
|
# 1. Create a virtual environment
|
|
python -m venv venv
|
|
source venv/bin/activate # Linux/macOS
|
|
# venv\Scripts\activate # Windows
|
|
|
|
# 2. Install dependencies
|
|
pip install -r requirements.txt
|
|
|
|
# 3. Configure environment
|
|
cp .env.example .env
|
|
# Edit .env — set MYSQL_HOST=localhost and your DB credentials
|
|
|
|
# 4. Initialise the database
|
|
flask db init
|
|
flask db migrate -m "initial"
|
|
flask db upgrade
|
|
python init_db.py
|
|
|
|
# 5. Run
|
|
python run.py
|
|
```
|
|
|
|
---
|
|
|
|
## Environment Variables (`.env`)
|
|
|
|
| Variable | Description | Default |
|
|
|---|---|---|
|
|
| `SECRET_KEY` | Flask secret key | *(must change)* |
|
|
| `MYSQL_HOST` | MySQL host | `db` (Docker) / `localhost` |
|
|
| `MYSQL_USER` | MySQL user | `itasset_user` |
|
|
| `MYSQL_PASSWORD` | MySQL password | `itasset_pass` |
|
|
| `MYSQL_DB` | Database name | `itasset_db` |
|
|
| `LDAP_SERVER` | LDAP server URL | *(blank = disabled)* |
|
|
| `LDAP_BIND_USER` | Service account DN | — |
|
|
| `LDAP_BIND_PASSWORD` | Service account password | — |
|
|
| `LDAP_BASE_DN` | Search base | — |
|
|
| `LDAP_WINDOWS_ID_ATTR` | AD attribute for numeric ID | `employeeID` |
|
|
| `COMPANY_NAME` | Shown on PDF headers | `Your Company Name` |
|
|
| `COMPANY_ADDRESS` | Shown on PDF headers | — |
|
|
| `DEFAULT_ADMIN_USER` | First-run admin username | `admin` |
|
|
| `DEFAULT_ADMIN_PASS` | First-run admin password | `ChangeMe123!` |
|
|
|
|
---
|
|
|
|
## CSV Import Format
|
|
|
|
```csv
|
|
windows_id,first_name,last_name,email,department,job_title,location
|
|
408525,John,Doe,john.doe@company.com,IT,Engineer,HQ
|
|
408526,Jane,Smith,jane.smith@company.com,HR,Manager,HQ
|
|
```
|
|
|
|
Column names are matched case-insensitively. `windows_id` is required; all others are optional.
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
IT_asset_management/
|
|
├── app/
|
|
│ ├── __init__.py # App factory
|
|
│ ├── extensions.py # SQLAlchemy, Flask-Login, Migrate
|
|
│ ├── models/ # User, Asset, Assignment, Paperwork, AuditLog, AdminUser
|
|
│ ├── routes/ # auth, dashboard, users, assets, assignments, paperwork, audit, settings
|
|
│ ├── services/ # csv_service, ldap_service, pdf_service
|
|
│ └── templates/ # Jinja2 + Bootstrap 5
|
|
├── config.py
|
|
├── run.py
|
|
├── init_db.py
|
|
├── requirements.txt
|
|
├── Dockerfile
|
|
├── docker-compose.yml
|
|
└── .env.example
|
|
```
|
|
|
|
---
|
|
|
|
## Security Notes
|
|
|
|
- Change `DEFAULT_ADMIN_PASS` immediately after first login.
|
|
- Set a strong random `SECRET_KEY` in `.env`.
|
|
- The LDAP bind password is read from the environment — never commit `.env` to source control.
|
|
- PDF files are stored server-side in the `pdfs/` directory (Docker volume). Restrict access as needed.
|
|
- Masked user records permanently destroy PII and cannot be reversed.
|