89 lines
5.1 KiB
Markdown
89 lines
5.1 KiB
Markdown
---
|
|
title: "07 — Deployment View"
|
|
description: "Describe deployment topology, infrastructure components, and environments (dev/stage/prod)."
|
|
status: draft
|
|
---
|
|
|
|
<!-- markdownlint-disable-next-line MD025 -->
|
|
|
|
# 07 — Deployment View
|
|
|
|
## Deployment Topology
|
|
|
|
The CalMiner application is deployed using a multi-tier architecture consisting of the following layers:
|
|
|
|
1. **Client Layer**: This layer consists of web browsers that interact with the application through a user interface rendered by Jinja2 templates and enhanced with JavaScript (Chart.js for dashboards).
|
|
2. **Web Application Layer**: This layer hosts the FastAPI application, which handles API requests, business logic, and serves HTML templates. It communicates with the database layer for data persistence.
|
|
3. **Database Layer**: This layer consists of a PostgreSQL database that stores all application data, including scenarios, parameters, costs, consumption, production outputs, equipment, maintenance logs, and simulation results.
|
|
4. **Caching Layer**: This layer uses Redis to cache frequently accessed data and improve application performance.
|
|
|
|
## Infrastructure Components
|
|
|
|
The infrastructure components for the application include:
|
|
|
|
- **Web Server**: Hosts the FastAPI application and serves API endpoints.
|
|
- **Database Server**: PostgreSQL database for persisting application data.
|
|
- **Static File Server**: Serves static assets such as CSS, JavaScript, and image files.
|
|
- **Reverse Proxy (optional)**: An Nginx or Apache server can be used as a reverse proxy.
|
|
- **Containerization**: Docker images are generated via the repository `Dockerfile`, using a multi-stage build to keep the final runtime minimal.
|
|
- **CI/CD Pipeline**: Automated pipelines (Gitea Actions) run tests, build/push Docker images, and trigger deployments.
|
|
- **Cloud Infrastructure (optional)**: The application can be deployed on cloud platforms.
|
|
|
|
## Environments
|
|
|
|
The application can be deployed in multiple environments to support development, testing, and production:
|
|
|
|
### Development Environment
|
|
|
|
The development environment is set up for local development and testing. It includes:
|
|
|
|
- Local PostgreSQL instance (docker compose recommended, script available at `docker-compose.postgres.yml`)
|
|
- FastAPI server running in debug mode
|
|
|
|
### Testing Environment
|
|
|
|
The testing environment is set up for automated testing and quality assurance. It includes:
|
|
|
|
- Staging PostgreSQL instance
|
|
- FastAPI server running in testing mode
|
|
- Automated test suite (e.g., pytest) for running unit and integration tests
|
|
|
|
### Production Environment
|
|
|
|
The production environment is set up for serving live traffic and includes:
|
|
|
|
- Production PostgreSQL instance
|
|
- FastAPI server running in production mode
|
|
- Load balancer (e.g., Nginx) for distributing incoming requests
|
|
- Monitoring and logging tools for tracking application performance
|
|
|
|
## Containerized Deployment Flow
|
|
|
|
The Docker-based deployment path aligns with the solution strategy documented in [04 — Solution Strategy](04_solution_strategy.md) and the CI practices captured in [14 — Testing & CI](14_testing_ci.md).
|
|
|
|
### Image Build
|
|
|
|
- The multi-stage `Dockerfile` installs dependencies in a builder layer (including system compilers and Python packages) and copies only the required runtime artifacts to the final image.
|
|
- Build arguments are minimal; database configuration is supplied at runtime via granular variables (`DATABASE_DRIVER`, `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_USER`, `DATABASE_PASSWORD`, `DATABASE_NAME`, optional `DATABASE_SCHEMA`). Secrets and configuration should be passed via environment variables or an orchestrator.
|
|
- The resulting image exposes port `8000` and starts `uvicorn main:app` (s. [README.md](../../README.md)).
|
|
|
|
### Runtime Environment
|
|
|
|
- For single-node deployments, run the container alongside PostgreSQL/Redis using Docker Compose or an equivalent orchestrator.
|
|
- A reverse proxy (e.g., Nginx) terminates TLS and forwards traffic to the container on port `8000`.
|
|
- Migrations must be applied prior to rolling out a new image; automation can hook into the deploy step to run `scripts/run_migrations.py`.
|
|
|
|
### CI/CD Integration
|
|
|
|
- Gitea Actions workflows reside under `.gitea/workflows/`.
|
|
- `test.yml` executes the pytest suite using cached pip dependencies.
|
|
- `build-and-push.yml` logs into the container registry, rebuilds the Docker image using GitHub Actions cache-backed layers, and pushes `latest` (and additional tags as required).
|
|
- `deploy.yml` connects to the target host via SSH, pulls the pushed tag, stops any existing container, and launches the new version.
|
|
- Required secrets: `REGISTRY_URL`, `REGISTRY_USERNAME`, `REGISTRY_PASSWORD`, `SSH_HOST`, `SSH_USERNAME`, `SSH_PRIVATE_KEY`.
|
|
- Extend these workflows when introducing staging/blue-green deployments; keep cross-links with [14 — Testing & CI](14_testing_ci.md) up to date.
|
|
|
|
## Integrations and Future Work (deployment-related)
|
|
|
|
- **Persistence of results**: `/api/simulations/run` currently returns in-memory results; next iteration should persist to `simulation_result` and reference scenarios.
|
|
- **Deployment**: implement infrastructure-as-code (e.g., Terraform/Ansible) to provision the hosting environment and maintain parity across dev/stage/prod.
|