zwitschi
04d7f202b6
Some checks failed
CI / test (pull_request) Failing after 1m8s
- Introduced a new document outlining UI structure, reusable template components, CSS variable conventions, and per-page data/actions for the CalMiner application. - Removed outdated idempotency audit and logging audit documents as they are no longer relevant. - Updated quickstart guide to streamline developer setup instructions and link to relevant documentation. - Created a roadmap document detailing scenario enhancements and data management strategies. - Deleted the seed data plan document to consolidate information into the setup process. - Refactored setup_database.py for improved logging and error handling during database setup and migration processes.
89 lines
3.0 KiB
Markdown
89 lines
3.0 KiB
Markdown
# Developer Quickstart
|
|
|
|
- [Developer Quickstart](#developer-quickstart)
|
|
- [Development](#development)
|
|
- [User Interface](#user-interface)
|
|
- [Testing](#testing)
|
|
- [Staging](#staging)
|
|
- [Deployment](#deployment)
|
|
- [Using Docker Compose](#using-docker-compose)
|
|
- [Manual Docker Deployment](#manual-docker-deployment)
|
|
- [Database Deployment \& Migrations](#database-deployment--migrations)
|
|
- [Usage Overview](#usage-overview)
|
|
- [Theme configuration](#theme-configuration)
|
|
- [Where to look next](#where-to-look-next)
|
|
|
|
This document provides a quickstart guide for developers to set up and run the CalMiner application locally.
|
|
|
|
## Development
|
|
|
|
See [Development Setup](docs/developer/development_setup.md).
|
|
|
|
### User Interface
|
|
|
|
There is a dedicated [UI and Style](docs/developer/ui_and_style.md) guide for frontend contributors.
|
|
|
|
### Testing
|
|
|
|
Testing is described in the [Testing CI](docs/architecture/07_deployment/07_01_testing_ci.md) document.
|
|
|
|
## Staging
|
|
|
|
Staging environment setup is covered in [Staging Environment Setup](docs/developer/staging_environment_setup.md).
|
|
|
|
## Deployment
|
|
|
|
The application can be deployed using Docker containers.
|
|
|
|
### Using Docker Compose
|
|
|
|
For production deployment, use the provided `docker-compose.yml`:
|
|
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
This starts the FastAPI app and PostgreSQL database.
|
|
|
|
### Manual Docker Deployment
|
|
|
|
Build and run the container manually:
|
|
|
|
```bash
|
|
docker build -t calminer .
|
|
docker run -d -p 8000:8000 \
|
|
-e DATABASE_HOST=your-postgres-host \
|
|
-e DATABASE_USER=calminer \
|
|
-e DATABASE_PASSWORD=your-password \
|
|
-e DATABASE_NAME=calminer_db \
|
|
calminer
|
|
```
|
|
|
|
Ensure the database is set up and migrated before running.
|
|
|
|
### Database Deployment & Migrations
|
|
|
|
See the [Database Deployment & Migrations](docs/architecture/07_deployment/07_02_database_deployment_migrations.md) document for details on database deployment and migration strategies.
|
|
|
|
## Usage Overview
|
|
|
|
- **Run the application**: Follow the [Development Setup](docs/developer/development_setup.md) to get the application running locally.
|
|
- **Access the UI**: Open your web browser and navigate to `http://localhost:8000/ui` to access the user interface.
|
|
- **API base URL**: `http://localhost:8000/api`
|
|
- Key routes include creating scenarios, parameters, costs, consumption, production, equipment, maintenance, and reporting summaries. See the `routes/` directory for full details.
|
|
- **UI base URL**: `http://localhost:8000/ui`
|
|
|
|
### Theme configuration
|
|
|
|
Theming is laid out in [Theming](docs/architecture/05_03_theming.md).
|
|
|
|
## Where to look next
|
|
|
|
- Architecture overview & chapters: [architecture](architecture/README.md) (per-chapter files under `docs/architecture/`)
|
|
- [Testing & CI](architecture/07_deployment/07_01_testing_ci.md.md)
|
|
- [Development setup](developer/development_setup.md)
|
|
- Implementation plan & roadmap: [Solution strategy](architecture/04_solution_strategy.md)
|
|
- Routes: [routes](../routes/)
|
|
- Services: [services](../services/)
|
|
- Scripts: [scripts](../scripts/) (migrations and backfills)
|