87 lines
4.3 KiB
Markdown
87 lines
4.3 KiB
Markdown
# CalMiner
|
|
|
|
A web application to plan mining projects and estimate costs, returns and profitability.
|
|
|
|
Focuses on ore mining operations and covering parameters such as capital and operational expenditures, resource consumption, production output, and Monte Carlo simulations for risk analysis.
|
|
|
|
The system is designed to help mining companies make informed decisions by simulating various scenarios and analyzing potential outcomes based on stochastic variables.
|
|
|
|
A range of features are implemented to support these functionalities.
|
|
|
|
## Features
|
|
|
|
- **Scenario Management**: Manage multiple mining scenarios with independent parameter sets and outputs.
|
|
- **Process Parameters**: Define and persist process inputs via FastAPI endpoints and template-driven forms.
|
|
- **Cost Tracking**: Capture capital (`capex`) and operational (`opex`) expenditures per scenario.
|
|
- **Consumption Tracking**: Record resource consumption (chemicals, fuel, water, scrap) tied to scenarios.
|
|
- **Production Output**: Store production metrics such as tonnage, recovery, and revenue drivers.
|
|
- **Equipment Management**: Register scenario-specific equipment inventories.
|
|
- **Maintenance Logging**: Log maintenance events against equipment with dates and costs.
|
|
- **Reporting Dashboard**: Surface aggregated statistics for simulation outputs with an interactive Chart.js dashboard.
|
|
- **Unified UI Shell**: Server-rendered templates extend a shared base layout with a persistent left sidebar linking scenarios, parameters, costs, consumption, production, equipment, maintenance, simulations, and reporting views.
|
|
- **Operations Overview Dashboard**: The root route (`/`) surfaces cross-scenario KPIs, charts, and maintenance reminders with a one-click refresh backed by aggregated loaders.
|
|
- **Theming Tokens**: Shared CSS variables in `static/css/main.css` centralize the UI color palette for consistent styling and rapid theme tweaks.
|
|
- **Modular Frontend Scripts**: Page-specific interactions now live in `static/js/` modules, keeping templates lean while enabling browser caching and reuse.
|
|
- **Monte Carlo Simulation (in progress)**: Services and routes are scaffolded for future stochastic analysis.
|
|
|
|
## Documentation & quickstart
|
|
|
|
This repository contains detailed developer and architecture documentation in the `docs/` folder.
|
|
|
|
[Quickstart](docs/quickstart.md) contains developer quickstart, migrations, testing and current status.
|
|
|
|
Key architecture documents: see [architecture](docs/architecture/README.md) for the arc42-based architecture documentation.
|
|
|
|
For contributors: the `routes/`, `models/` and `services/` folders contain the primary application code. Tests and E2E specs are in `tests/`.
|
|
|
|
## Run with Docker
|
|
|
|
The repository ships with a multi-stage `Dockerfile` that produces a slim runtime image.
|
|
|
|
### Build container
|
|
|
|
```powershell
|
|
# Build the image locally
|
|
docker build -t calminer:latest .
|
|
```
|
|
|
|
### Push to registry
|
|
|
|
```powershell
|
|
# Tag and push the image to your registry
|
|
docker login your-registry.com -u your-username -p your-password
|
|
docker tag calminer:latest your-registry.com/your-namespace/calminer:latest
|
|
docker push your-registry.com/your-namespace/calminer:latest
|
|
```
|
|
|
|
### Run container
|
|
|
|
Expose FastAPI on <http://localhost:8000> with database configuration via granular environment variables:
|
|
|
|
```powershell
|
|
# Provide database configuration via granular environment variables
|
|
docker run --rm -p 8000:8000 ^
|
|
-e DATABASE_DRIVER="postgresql" ^
|
|
-e DATABASE_HOST="db.host" ^
|
|
-e DATABASE_PORT="5432" ^
|
|
-e DATABASE_USER="calminer" ^
|
|
-e DATABASE_PASSWORD="s3cret" ^
|
|
-e DATABASE_NAME="calminer" ^
|
|
-e DATABASE_SCHEMA="public" ^
|
|
calminer:latest
|
|
```
|
|
|
|
### Orchestrated Deployment
|
|
|
|
Use `docker compose` or an orchestrator of your choice to co-locate PostgreSQL/Redis alongside the app when needed. The image expects migrations to be applied before startup.
|
|
|
|
## CI/CD expectations
|
|
|
|
CalMiner uses Gitea Actions workflows stored in `.gitea/workflows/`:
|
|
|
|
- `test.yml` runs style/unit/e2e suites on every push with cached Python dependencies.
|
|
- `build-and-push.yml` builds the Docker image, reuses cached layers, and pushes to the configured registry.
|
|
- `deploy.yml` pulls the pushed image on the target host and restarts the container.
|
|
|
|
Pipelines assume the following secrets are provisioned in the Gitea instance: `REGISTRY_USERNAME`, `REGISTRY_PASSWORD`, `REGISTRY_URL`, `SSH_HOST`, `SSH_USERNAME`, and `SSH_PRIVATE_KEY`.
|