Famli is a modern, containerized Progressive Web Application designed for household-centric contact management. Unlike traditional contact systems that focus on individuals, Famli organizes contacts by household units, making it ideal for managing family addresses, Christmas card lists, and event invitations.

The premice of this app was because I have family all over the UK and it was a pain to remember their addresses, hence creating Famli.

N.b: This was mostly vibe coded with Calude-Code but it has been checked by a human.

• 🏡 Household-Centric Organization - Manage contacts by families and households rather than individuals
• 👥 People Directory - View all contacts alphabetically, sorted by first or last name
• 🎨 Color Themes - Customizable color themes for each household
• 🌍 Locale Support - Country-specific address formats (US, UK, Canada, Australia)
• 🔐 Role-Based Access Control - Admin, Editor, and Viewer roles with appropriate permissions
• 🌙 Dark Mode - Beautiful responsive design with dark mode support
• 📱 Progressive Web App - Install on mobile devices for app-like experience
• 🔒 Secure Authentication - JWT-based authentication with refresh tokens
• 📊 Complete Member Management - Track birthdays, emails, phones, and notes for household members
• 📝 Audit Logging - Track all administrative actions for security

First Run Setup

Household List View

Create/Edit Household

People/Contacts View

Docker Compose:

Copy and paste this text into your docker-compose.yml file, make your own edits, and run it with docker compose up -d

services:
  famli:
    image: ajb3932/famli:latest
    container_name: famli
    user: "1000:1000"
    ports:
      - "9992:9992"
    volumes:
      - ./famli-data:/app/data
    environment:
      - NODE_ENV=production
      - PORT=9992
      - DB_PATH=/app/data/famli.db
      - JWT_SECRET=change-this-secret-in-production
      - JWT_REFRESH_SECRET=change-this-refresh-secret-in-production
      - CORS_ORIGIN=*
    restart: unless-stopped

Docker CLI:

docker run -d \
  -p 3000:3000 \
  -v ./famli-data:/app/data \
  -e JWT_SECRET=your-secret-key \
  -e JWT_REFRESH_SECRET=your-refresh-secret \
  --user 1000:1000 \
  --name famli \
  ajb3932/famli:latest

⚠️ Important: Make sure the data directory has correct permissions:

mkdir -p ./famli-data
sudo chown -R $(id -u):$(id -g) ./famli-data

The following Environment Variables are available:

🔒 Security: Always change the JWT secrets in production! Generate secure random strings:

# Generate a secure random string
openssl rand -base64 32

When the app first runs, it will automatically detect that no users exist and present you with a setup wizard at the root URL. You'll be asked to create an administrator account with:

• Username
• Email
• Password (minimum 8 characters)

Once setup is complete, you'll be automatically logged in and can start adding households!

/ (Root)

• If no users exist: Shows the first-run setup wizard
• If not logged in: Shows the login page
• If logged in: Shows the main application dashboard

Main Application Features:

• Households Tab - View all households in a list format with member counts. Click any household to see full details and members.

• People Tab - Browse all contacts alphabetically. Toggle sorting by first name or last name. Click any person to navigate to their household.

• Users Tab (Admin Only) - Manage user accounts, assign roles, and view audit logs.

User Roles:

Locale Settings:

Switch between country formats in the header dropdown:

• 🇺🇸 United States - City, State, ZIP Code
• 🇬🇧 United Kingdom - Town, County, Postcode
• 🇨🇦 Canada - City, Province, Postal Code
• 🇦🇺 Australia - City, State, Postcode

If you encounter database permission errors, see TROUBLESHOOTING.md for detailed solutions.

Quick Fix for Permission Issues:

# Fix directory ownership
sudo chown -R $(id -u):$(id -g) ./famli-data

# Verify permissions
ls -la ./famli-data

🐳 Docker

git clone https://github.com/ajb3932/famli.git
cd famli
mkdir -p famli-data
docker build -t my-famli .
docker run -d -p 3000:3000 -v ./famli-data:/app/data --user $(id -u):$(id -g) my-famli

🐳 Docker Compose

git clone https://github.com/ajb3932/famli.git
cd famli
mkdir -p famli-data
# Edit docker-compose.yml first if needed
docker compose up -d --build

💾 Node.js (Development)

git clone https://github.com/ajb3932/famli.git
cd famli

# Backend
cd backend
npm install
cp .env.example .env
# Edit .env with your settings
npm run dev

# Frontend (in another terminal)
cd frontend
npm install
npm run dev

Backend:

• Node.js with Express.js
• SQLite3 database
• JWT authentication with bcrypt
• Helmet, CORS, and rate limiting

Frontend:

• React 19 with Vite
• Tailwind CSS
• Progressive Web App features
• Dark mode support

Deployment:

• Docker with multi-stage builds
• Alpine Linux base image
• Health checks and graceful shutdown

The SQLite database is stored in /app/data/famli.db (Docker) or backend/data/famli.db (manual).

Backup:

# Docker
docker cp famli:/app/data/famli.db ./backup-$(date +%Y%m%d).db

# Manual
cp backend/data/famli.db ./backup-$(date +%Y%m%d).db

Restore:

# Docker
docker cp ./backup.db famli:/app/data/famli.db
docker restart famli

# Manual
cp ./backup.db backend/data/famli.db

• ✅ Change default JWT secrets in production
• ✅ Use HTTPS in production (reverse proxy recommended)
• ✅ Regularly backup your database
• ✅ Keep dependencies up to date
• ✅ Use strong passwords (min 8 characters)
• ✅ Consider rate limiting at reverse proxy level
• ✅ Review audit logs for suspicious activity

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.

ISC