# 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)