added readme

2025-11-06 22:46:40 +01:00
parent c3a08372a0
commit 705a89e16e
1 changed files with 260 additions and 2 deletions
@@ -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