Shared Shopping List Web App

About The Project

This project provides a central, self-hosted web application for a family or group to manage a shared shopping list. Any member can easily add items they need, creating a single, always-up-to-date list.

This web service is the final development step for the accompanying Android app. The goal is to allow the app to automatically sync with this web service.

Current Status & Workaround: While direct API integration in the app is still to be completed, the system is already fully functional using notifications. The text sent in the Gotify notification can be copied and pasted 1:1 into the Android app to instantly populate the shopping list.

Features

• Multi-user access: Log in to manage the list. Includes an admin panel for user management.

• Real-time updates: Changes to the shopping list (add, mark, delete) are instantly reflected across all connected user sessions.

• Automatic Language Detection: The user interface automatically adapts to your browser's language. Currently, English and German are supported. Simply refresh the page after changing your browser or OS language settings.

• Gotify Notifications: Trigger notifications to your Gotify server.

• Suggestion Box: Get suggestions for items as you type.

• Feature Update: The Deletion Password field is now optional, removing the mandatory requirement for admin to set a password.

• Bugfix: The password prompt for deleting items now correctly appears for all users when a password is set.

• New Feature: Added support for a Dark Theme (Dark Mode).

How to Use

Here is an example docker-compose.yml file:

services:
  shopping-list:
    image: lxtools/noteshop-webapp:latest
    container_name: shopping-list
    restart: always
    ports:
      - "8080:8000" # Host-Port:Container-Port
    volumes:
      # For local development, use a relative path:
      - ./data:/app/data

      # For production, you might use an absolute path like this (choose one):
      # - /opt/containers/sharelist/data:/app/data

    environment:
      # Set the User and Group ID for file permissions.
      # Defaults to 1000 if not specified in your environment.
      - PUID=${PUID:-1000}
      - PGID=${PGID:-1000}
      # Your Gotify URL for notifications. Should be set in a .env file.
      - GOTIFY_URL=${GOTIFY_URL}

First Login

After starting the container for the first time, a default administrator account is created so you can log in.

• Username: admin
• Password: admin

Important: For security reasons, please log in and change the default password immediately using the admin panel.

Managing the Shopping List

• Adding Items:
  • To add multiple items at once, type them into the input field separated by commas (e.g., Milk, Bread, Eggs). Press Enter or click the Add button.
  • To add a single item exactly as typed (even if it contains commas), click the +1 button.
• Marking & Deleting Items:
  • Use the switch next to each item to mark it for deletion.
  • To delete all marked items, click the trash can icon at the top right.
  • Important: For security, you must first set a "Deletion Password" in the admin panel. This password is required to delete items from the list.

Important Notes

• User/Group: Set PUID and PGID to your user's ID on the host system. You can find them by running the commands id -u and id -g.
• Data Directory: Before the first run, create a directory for the database: mkdir data.
• Running: Start the container with: PUID=$(id -u) PGID=$(id -g) docker compose up -d
• Update Sharelist: docker compose pull, docker compose up -d