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.
105 lines
1.9 KiB
Markdown
105 lines
1.9 KiB
Markdown
# Development Environment Setup
|
|
|
|
This document outlines the local development environment and steps to get the project running.
|
|
|
|
## Prerequisites
|
|
|
|
- Python (version 3.11+)
|
|
- PostgreSQL (version 13+)
|
|
- Git
|
|
- Docker and Docker Compose (optional, for containerized development)
|
|
|
|
## Clone and Project Setup
|
|
|
|
```powershell
|
|
# Clone the repository
|
|
git clone https://git.allucanget.biz/allucanget/calminer.git
|
|
cd calminer
|
|
```
|
|
|
|
## Development with Docker Compose (Recommended)
|
|
|
|
For a quick setup without installing PostgreSQL locally, use Docker Compose:
|
|
|
|
```powershell
|
|
# Start services
|
|
docker-compose up
|
|
|
|
# The app will be available at http://localhost:8000
|
|
# Database is automatically set up
|
|
```
|
|
|
|
To run in background:
|
|
|
|
```powershell
|
|
docker-compose up -d
|
|
```
|
|
|
|
To stop:
|
|
|
|
```powershell
|
|
docker-compose down
|
|
```
|
|
|
|
## Manual Development Setup
|
|
|
|
### Virtual Environment
|
|
|
|
```powershell
|
|
# Create and activate a virtual environment
|
|
python -m venv .venv
|
|
.\.venv\Scripts\Activate.ps1
|
|
```
|
|
|
|
### Install Dependencies
|
|
|
|
```powershell
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
### Database Setup
|
|
|
|
1. Create database user:
|
|
|
|
```sql
|
|
CREATE USER calminer_user WITH PASSWORD 'your_password';
|
|
```
|
|
|
|
1. Create database:
|
|
|
|
```sql
|
|
CREATE DATABASE calminer;
|
|
```
|
|
|
|
### Environment Variables
|
|
|
|
1. Copy `.env.example` to `.env` at project root.
|
|
1. Edit `.env` to set database connection details:
|
|
|
|
```dotenv
|
|
DATABASE_DRIVER=postgresql
|
|
DATABASE_HOST=localhost
|
|
DATABASE_PORT=5432
|
|
DATABASE_USER=calminer_user
|
|
DATABASE_PASSWORD=your_password
|
|
DATABASE_NAME=calminer
|
|
DATABASE_SCHEMA=public
|
|
```
|
|
|
|
1. The application uses `python-dotenv` to load these variables. A legacy `DATABASE_URL` value is still accepted if the granular keys are omitted.
|
|
|
|
### Running the Application
|
|
|
|
```powershell
|
|
# Start the FastAPI server
|
|
uvicorn main:app --reload
|
|
```
|
|
|
|
## Testing
|
|
|
|
```powershell
|
|
pytest
|
|
```
|
|
|
|
E2E tests use Playwright and a session-scoped `live_server` fixture that starts the app at `http://localhost:8001` for browser-driven tests.
|