⚠️ Note: This project is in active development and may have breaking changes.

A simple family utility app for managing household tasks with secure authentication.

Features: Shopping lists • Chores • Expiry tracking • Bills • Mobile-friendly

1. Get the files:

   curl -o compose.yml https://raw.githubusercontent.com/Brramble/homie/main/compose.yml

2. Configure your OIDC provider:

   • Set callback URL to: http://localhost:5000/auth/callback
   • Note your client ID and secret

3. Edit the compose.yml file:

   For OIDC Authentication:

   - SECRET_KEY=your-random-secret-key-here
   - OIDC_ENABLED=true
   - OIDC_BASE_URL=https://your-auth-provider.com
   - OIDC_CLIENT_ID=your-client-id
   - OIDC_CLIENT_SECRET=your-client-secret
   - [email protected]

   For Local Authentication (Family Mode):

   - SECRET_KEY=your-random-secret-key-here
   - OIDC_ENABLED=false
   - USERS=Dad,Bill,Sarah

4. Start:

   docker compose up -d

5. Open: http://localhost:5000

Copy .env.sample to .env and fill in your values, or edit the environment variables in compose.yml.

Required settings:

• SECRET_KEY - Random string for security
• OIDC_ENABLED - Enable/disable OIDC authentication (default: true)

For OIDC mode (OIDC_ENABLED=true):

• OIDC_BASE_URL - Your authentication provider URL
• OIDC_CLIENT_ID & OIDC_CLIENT_SECRET - From your OIDC provider
• ALLOWED_EMAILS - Who can access the app

For Local mode (OIDC_ENABLED=false):

• USERS - Local users in format: username1,username2,username3

Important: Configure {your-base-url}/auth/callback as the callback URL in your OIDC provider.

Homie supports two authentication modes:

Use external OIDC provider (Keycloak, Auth0, etc.)

• Set OIDC_ENABLED=true
• Configure your OIDC provider details
• Users authenticate through your SSO provider

Simple user selection without passwords - perfect for family use

• Set OIDC_ENABLED=false
• Configure USERS environment variable
• Users click their name to login

Example local users setup:

OIDC_ENABLED=false
USERS=Dad,Bill,Sarah

git clone https://github.com/Brramble/homie.git
cd homie
pip install -r requirements.txt
cp .env.sample .env
# Edit .env with your settings
python app.py

Common issues:

• Can't login? Check your OIDC callback URL is set correctly
• OIDC errors? Verify your client ID/secret and base URL
• Access denied? Add your email to ALLOWED_EMAILS

The app uses OIDC auto-discovery but falls back to manual configuration if needed.