StatHaus - Meter Reading Tracker

A Progressive Web App for tracking and managing meter readings for electricity, water, gas, and more. Built with Vue 3, fully client-side by default - your data stays with you!

• Dynamic Meter Types: Create custom types (Electricity, Water, Gas, Heating Oil, Solar, etc.)
• Unlimited Meters: Manage any number of meters per type
• Detailed Readings: Record values with timestamps and notes

• Simple and fast
• No configuration required
• Works offline
• Data stays on this device only

• Automatic synchronization
• Secure authentication (Authentik, Keycloak, Auth0, Google, etc.)
• Available across devices
• No manual file management
• Works on all devices (iOS, Android, Desktop)

Workflow:

1. Settings → Cloud Sync → "Sign in"
2. Log in with OAuth provider (e.g., Authentik)
3. Data syncs automatically
4. Sign in on another device → Data instantly available!

• Automatic login when cloud sync session is active
• Dashboard as default start page
• Seamless user experience

• Warning on decreasing meter values
• Prevents accidental incorrect entries
• Confirmation dialog for unusual values

• Interactive charts with ECharts
• Touch-optimized for mobile
• Zoom & Pan support
• History display

• JSON Export: Complete backup
• CSV Export: For Excel/LibreOffice
• JSON Import: Restore backup

• Installable on desktop & mobile
• Works offline
• Native app experience

For production deployment with OAuth and cloud sync, configure these environment variables:

See docs/OAUTH_SETUP.md for provider-specific setup instructions and backend/README.md for detailed backend configuration.

Images are automatically built via GitHub Actions:

• ghcr.io/kallistox/stathaus:latest - Frontend (nginx + Vue PWA)
• ghcr.io/kallistox/stathaus-backend:latest - Backend (Node.js + Express)

Available tags:

• latest - Latest main branch
• v1.x.x - Semantic version tags
• main-abc123 - Commit SHA

• Docker Desktop (for Mac)
• VSCode (recommended)

1. Clone repository (or open folder)

cd stathaus

2. Start Docker container

docker-compose up

3. Open app

http://localhost:5173

The app automatically reloads on code changes (Hot Reload)!

# Build production image
docker build -t stathaus:latest .

# Start container
docker run -p 8080:80 stathaus:latest

App available at http://localhost:8080

npm install

npm run dev

npm run build

npm run preview

Frontend:

• Framework: Vue 3 (Composition API)
• Build Tool: Vite
• State Management: Pinia
• Routing: Vue Router
• Styling: Tailwind CSS
• Charts: Apache ECharts
• PWA: vite-plugin-pwa
• Storage: IndexedDB + File System Access API + Cloud Sync

Backend:

• Runtime: Node.js 20 (Alpine)
• Framework: Express.js
• Authentication: openid-client (OAuth2/OIDC)
• Database: Redis (ioredis client)
• Validation: Joi
• Logging: Winston
• Security: Helmet
• Deployment: Multi-stage Docker builds

• OAuth2/OIDC Cloud Sync
• Auto-Login
• Dashboard Entrypoint
• Continuous Meter Validation
• Conflict Resolution
• Logo Header
• PWA Icons
• Dark Mode
• PDF Reports
• Dashboard Widgets

• Cost Calculation (Tariff management)
• Usage Predictions (Consumption forecasting)
• Meter Grouping (Group by location/property)

MIT License - use it however you want!

PRs are welcome! For questions or issues, open an issue.

Happy Metering!