lxtools/noteshop-webapp repository overview

⁠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 & Integration: The direct API integration for importing items into the Android app is now fully functional. Gotify notifications have been enhanced to include the username and the specific list name where items/tasks were added, facilitating better assignment within the app. The option to include the username in notifications can be configured in the Admin Panel. Future updates to the Android app will also include a feature to notify users about unimported items/tasks from the web app (if the list names match and the web app is configured), making web app notifications optional.

⁠Versioning

The project has adopted a new versioning scheme. As of 1.0.12, the version format is 1.0.x, moving away from the previous 0.1.0.x scheme to better reflect the project's maturity.

⁠Android App

The app is registered with F-Droid and will be available there soon.

For the impatient, the signed Android app can be downloaded in advance starting from version 0.1.177⁠. This is the same version that will later be available on F-Droid and is compatible with web app version 0.1.0.9 and later.

Disclaimer: Installing apps from unknown sources always carries a security risk. It is strongly recommended to wait for the official release on F-Droid. The app is provided without any guarantee.

⁠Features

• Multi-user access: Log in to manage the list. Includes an 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.
• Configurable Gotify Notifications: Trigger notifications to your Gotify server. Admins can configure whether to include user and list details in the message.
• Suggestion Box: Get suggestions for items as you type.
• Dark Theme: The app supports a dark mode and can also follow your system's theme preference.
• Multiple Lists: Create and manage multiple shopping lists.
• Item Editing: Edit items directly in the list.
• Optional Deletion Password: The deletion password is now optional. If not set, no password is required to delete items.

⁠Support and Feedback

For questions, bug reports, or feature requests, please open an issue on the project's Gitea Issues page⁠.

⁠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}
      # E-Mail settings for password reset
      - MAIL_USERNAME=${MAIL_USERNAME}
      - MAIL_PASSWORD=${MAIL_PASSWORD}
      - MAIL_FROM=${MAIL_FROM}
      - MAIL_PORT=${MAIL_PORT}
      - MAIL_SERVER=${MAIL_SERVER}
      - MAIL_STARTTLS=${MAIL_STARTTLS}
      - MAIL_SSL_TLS=${MAIL_SSL_TLS}
      - MAIL_SUPPRESS_SEND=${MAIL_SUPPRESS_SEND}

⁠Environment Variables

All environment variables from the docker-compose.yml file (e.g., GOTIFY_URL, MAIL_...) can be managed in a .env file placed in the same directory.

An example file is provided in this repository. You can copy it to .env and adjust the values to your needs.

TODO: Add link to project's .env example⁠ here.

⁠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