From 705a89e16ef2a508a1e050d0bc688df58e96742d Mon Sep 17 00:00:00 2001 From: Brian Bjarke Jensen Date: Thu, 6 Nov 2025 22:46:40 +0100 Subject: [PATCH] added readme --- README.md | 262 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 260 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ccd3d35..bf586ed 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,261 @@ -# baby-monitor +# ๐Ÿ‘ถ Baby Monitor -Baby monitor app that helps track feeding, sleeping and diaper changes for a child. +A self-hosted FastAPI web application for tracking baby activities including feeding, sleeping, and diaper changes. Built with modern Python tools and designed for easy deployment with Docker. + +[![Docker](https://img.shields.io/badge/docker-%230db7ed.svg?style=flat&logo=docker&logoColor=white)](https://www.docker.com/) +[![FastAPI](https://img.shields.io/badge/FastAPI-005571?style=flat&logo=fastapi)](https://fastapi.tiangolo.com) +[![Python](https://img.shields.io/badge/python-3.12+-blue.svg?style=flat&logo=python&logoColor=white)](https://www.python.org) + +## โœจ Features + +- ๐Ÿ” **Secure Authentication** - Token-based authentication with environment-configured credentials +- ๐Ÿ’พ **Flexible Storage** - SQLite by default with PostgreSQL support +- ๐Ÿš€ **Scalable Sessions** - In-memory tokens with optional Redis for distributed deployments +- ๐Ÿ“ฆ **Self-Contained** - Docker image includes all optional dependencies +- ๐Ÿ”Œ **Repository Pattern** - Clean architecture with swappable backends +- ๐Ÿฅ **Health Checks** - Built-in health and readiness endpoints +- ๐ŸŒ **SPA Frontend** - Modern single-page application interface +- ๐Ÿณ **Docker Ready** - Production-ready Dockerfile with multi-architecture support + +## ๐Ÿš€ Quick Start + +### Using Docker (Recommended) + +```bash +# Pull and run the latest image +docker run -d \ + --name baby-monitor \ + -p 8000:8000 \ + -e ADMIN_PASSWORD=your-secure-password \ + -v baby_monitor_data:/data \ + gitea.gt-proj.com/brian/baby-monitor:latest + +# Access the application +open http://localhost:8000 +``` + +### Using Docker Compose + +```yaml +version: '3.8' + +services: + baby-monitor: + image: gitea.gt-proj.com/brian/baby-monitor:latest + container_name: baby-monitor + ports: + - "8000:8000" + environment: + - ENVIRONMENT=production + - ADMIN_PASSWORD=${ADMIN_PASSWORD} + # Optional: Use Redis for distributed token storage + # - REDIS_URI=redis://redis:6379 + volumes: + - ./data:/data + restart: unless-stopped + + # Optional: Redis for token storage + # redis: + # image: redis:7-alpine + # restart: unless-stopped +``` + +### Local Development + +```bash +# Clone the repository +git clone https://gitea.gt-proj.com/brian/baby-monitor.git +cd baby-monitor + +# Install dependencies with uv +uv sync --all-extras + +# Set environment variables +export ENVIRONMENT=development +export ADMIN_PASSWORD=password +export DATA_DIR=./data + +# Run the application +uv run uvicorn src.baby_monitor.main:app --reload --host 0.0.0.0 --port 8000 +``` + +## ๐Ÿ”ง Configuration + +### Environment Variables + +| Variable | Default | Description | +|----------|---------|-------------| +| `ENVIRONMENT` | `production` | Set to `development` to enable API docs | +| `ADMIN_PASSWORD` | *(required)* | Admin user password | +| `ADMIN_USERNAME` | `admin` | Admin username | +| `DATA_DIR` | `/data` | Directory for SQLite database | +| `REDIS_URI` | *(optional)* | Redis connection URI for distributed tokens | + +### Storage Options + +**SQLite (Default)** +- Automatic setup, no configuration needed +- Data stored in `/data/baby_monitor.db` +- Perfect for single-server deployments + +**Redis (Optional)** +```bash +# Enable Redis token storage +export REDIS_URI=redis://localhost:6379 +``` + +**PostgreSQL (Future)** +- Repository interface ready +- Swap implementation in `dependencies.py` + +## ๐Ÿ“ Project Structure + +``` +baby-monitor/ +โ”œโ”€โ”€ src/baby_monitor/ +โ”‚ โ”œโ”€โ”€ main.py # FastAPI application +โ”‚ โ”œโ”€โ”€ models/ # Pydantic models +โ”‚ โ”œโ”€โ”€ routers/ # API endpoints +โ”‚ โ”‚ โ”œโ”€โ”€ auth.py # Authentication routes +โ”‚ โ”‚ โ””โ”€โ”€ health.py # Health check routes +โ”‚ โ”œโ”€โ”€ repositories/ # Data access layer +โ”‚ โ”‚ โ”œโ”€โ”€ interfaces.py # Abstract interfaces +โ”‚ โ”‚ โ”œโ”€โ”€ user/ # User repositories +โ”‚ โ”‚ โ”œโ”€โ”€ token/ # Token storage +โ”‚ โ”‚ โ””โ”€โ”€ credentials/ # Credentials management +โ”‚ โ””โ”€โ”€ static/ # Frontend files +โ”œโ”€โ”€ tests/ # Test suite +โ”‚ โ”œโ”€โ”€ integration/ # Integration tests +โ”‚ โ””โ”€โ”€ unit/ # Unit tests +โ”œโ”€โ”€ Dockerfile # Production container +โ”œโ”€โ”€ docker-compose.yml # Local development +โ””โ”€โ”€ pyproject.toml # Project dependencies +``` + +## ๐Ÿ—๏ธ Architecture + +### Repository Pattern + +The application uses the **Repository Pattern** for data access, allowing easy swapping of backends: + +```python +# Switch from SQLite to PostgreSQL +from baby_monitor.repositories.user.postgresql_user import PostgreSQLUserRepository +return PostgreSQLUserRepository(db) + +# Switch from in-memory to Redis tokens +# Just set REDIS_URI environment variable +``` + +### Technology Stack + +- **Backend**: FastAPI + SQLAlchemy 2.0 +- **Database**: SQLite (default) / PostgreSQL (ready) +- **Cache**: In-memory (default) / Redis (optional) +- **Package Manager**: uv +- **Container**: Docker with multi-stage builds + +## ๐Ÿงช Testing + +```bash +# Run all tests +uv run pytest + +# Run with coverage +uv run pytest --cov-report=term-missing --cov=src/baby_monitor + +# Run specific test types +uv run pytest tests/unit/ +uv run pytest tests/integration/ +``` + +## ๐Ÿ”’ Security + +- โœ… Token-based authentication +- โœ… Environment-based secrets (no hardcoded credentials) +- โœ… API docs disabled in production +- โœ… CORS configuration ready +- โš ๏ธ **TODO**: Add password hashing (currently plain text comparison) +- โš ๏ธ **TODO**: Implement rate limiting + +## ๐Ÿš€ Deployment + +### Unraid + +1. Add the repository to Community Applications +2. Configure environment variables +3. Map `/data` volume for persistence +4. Set admin password + +### Docker Swarm / Kubernetes + +The application is stateless when using Redis for tokens, making it suitable for: +- Multi-replica deployments +- Load balancing +- Rolling updates + +### CI/CD + +Gitea Actions workflow included: +- Builds multi-architecture images (amd64, arm64) +- Automatic semantic versioning +- Pushes to container registry +- Health checks and metadata + +## ๐Ÿ“Š API Documentation + +When running in development mode (`ENVIRONMENT=development`): + +- **OpenAPI Docs**: http://localhost:8000/docs +- **ReDoc**: http://localhost:8000/redoc +- **OpenAPI JSON**: http://localhost:8000/openapi.json + +### Key Endpoints + +| Endpoint | Method | Description | +|----------|--------|-------------| +| `/` | GET | Serve home page | +| `/api/` | GET | Authenticated API root | +| `/api/login` | POST | User authentication | +| `/api/logout` | POST | Invalidate token | +| `/health` | GET | Health check | +| `/ready` | GET | Readiness probe | +| `/info` | GET | Feature detection | + +## ๐Ÿค Contributing + +Contributions are welcome! Please: + +1. Fork the repository +2. Create a feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'Add amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Open a Pull Request + +### Development Guidelines + +- Write tests for new features +- Follow PEP 8 style guide +- Add type hints to all functions +- Keep line length โ‰ค 79 characters +- Run `mypy` and `ruff` before committing + +## ๐Ÿ“ License + +This project is licensed under the MIT License - see the LICENSE file for details. + +## ๐Ÿ™ Acknowledgments + +- Built with [FastAPI](https://fastapi.tiangolo.com/) +- Package management by [uv](https://github.com/astral-sh/uv) +- Containerization with [Docker](https://www.docker.com/) + +## ๐Ÿ“ง Contact + +Brian Bjarke Jensen - [@bbj](https://gitea.example.com/bbj) + +Project Link: [https://gitea.example.com/bbj/baby-monitor](https://gitea.example.com/bbj/baby-monitor) + +--- + +Made with โค๏ธ for new parents everywhere