267 lines
8.0 KiB
Markdown
267 lines
8.0 KiB
Markdown
# 👶 Baby Monitor
|
|
|
|
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.
|
|
|
|
[](https://www.docker.com/)
|
|
[](https://fastapi.tiangolo.com)
|
|
[](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 - [@brian](https://gitea.gt-proj.com/brian)
|
|
|
|
Project Link: [https://gitea.gt-proj.com/brian/baby-monitor](https://gitea.gt-proj.com/brian/baby-monitor)
|
|
|
|
---
|
|
|
|
Made with ❤️ for new parents everywhere
|