diff --git a/README.md b/README.md index 57c77c9..97e3720 100644 --- a/README.md +++ b/README.md @@ -1,83 +1,94 @@
- +

Warracker

- +

+ Open-source warranty tracker for individuals and teams.
+The easiest way to organize product warranties, monitor expiration dates, and store receipts or related documents. + +

- ![GitHub issues](https://img.shields.io/github/issues/sassanix/Warracker) ![GitHub license](https://img.shields.io/github/license/sassanix/Warracker) ![GitHub last commit](https://img.shields.io/github/last-commit/sassanix/Warracker) ![GitHub release](https://img.shields.io/github/v/release/sassanix/Warracker) ![GitHub contributors](https://img.shields.io/github/contributors/sassanix/Warracker) - -[![Dependencies Status](https://img.shields.io/badge/dependencies-up%20to%20date-brightgreen.svg)](https://github.com/denser-org/denser-retriever/pulls?utf8=%E2%9C%93&q=is%3Apr%20author%3Aapp%2Fdependabot) -![Maintenance](https://img.shields.io/badge/Maintained-Actively-green) +[![Discord](https://img.shields.io/badge/discord-chat-green?logo=discord)](https://discord.gg/PGxVS3U2Nw) + +

+ Warracker Demo +

+ # + +
+โญ If you find Warracker helpful, weโ€™d truly appreciate a star on GitHub! Your support motivates us to keep improving and building great new features. -# ๐Ÿ›ก๏ธ Warracker +# -Warracker is an open-source warranty tracker application designed to help you effortlessly keep track of product warranties, expiration dates, and related documentation. +## ๐ŸŒŸOverview -## ๐ŸŒŸ Overview +**Warracker** is a web-based application that simplifies the management of product warranties. It allows users to organize warranty information, monitor expiration dates, and securely store related documents. -**Warracker** is a web-based application designed to simplify and centralize product warranty management. Key capabilities include: -- **Centralized Warranty Management:** Track and manage all your product warranties in one place. -- **Detailed Records:** Save essential details like purchase dates, durations, and notes. -- **Document Storage:** Upload and securely store receipts, invoices, product manuals, and other related files (e.g., ZIP, RAR archives). -- **Proactive Alerts:** Visual notifications for active, expiring (customizable from 1 to 365 days), and expired warranties. -- **Quick Search and Filter:** Instantly find warranties by product name, serial numbers, vendor, tags, or notes. -- **Notes Support:** Add freeform notes to each warranty for extra context or reminders. -- **Secure Access with Multi-User Support:** Create multiple user accounts for shared access; admins can enable or disable new user creation. -- **System Status Dashboard:** Real-time system health and warranty summary. -- **Data Export and Import:** Export warranty data to CSV, or import warranties from CSV files. -- **Email Notifications:** Receive timely email reminders about upcoming expirations โ€” configurable as daily, weekly, or monthly. -- **Customizable Currency Symbols:** Display prices using your preferred currency symbol ($, โ‚ฌ, ยฃ, ยฅ, โ‚น, or a custom symbol). -- **Customizable Dates:** Display dates based on your own region. -- **Tagging:** Organize warranties with flexible, multi-tag support. -- **Password Reset:** Easily recover accounts through a secure, token-based password reset flow. +## ๐Ÿ”‘ Key Features -## ๐Ÿ“ธ Screenshots +| **Feature** | **Description** | +| -------------------------------- | -------------------------------------------------------------------------------------------------------- | +| ๐Ÿ—ƒ๏ธ **Centralized Management** | Track all your product warranties in one place | +| ๐Ÿงพ **Detailed Records** | Store purchase dates, durations, notes, and product photos with thumbnail previews | +| ๐Ÿ“„ **Document Storage** | Upload receipts, invoices, and manuals securely | +| ๐Ÿ”” **Proactive Alerts** | Get alerts for upcoming expirations via email or 100+ push services (Discord, Slack, etc.) using Apprise | +| ๐Ÿ” **Quick Search and Filter** | Search by product name, serial number, vendor, tags, and more with real-time filtering | +| #๏ธโƒฃ **Multiple Serial Numbers** | Add and manage multiple serial numbers per product | +| ๐ŸŒ **Global Warranty View** | Authenticated users can view global warranty data with role-based permissions | +| ๐Ÿ‘ฅ **Multi-User Support** | Manage multiple accounts with admin controls and global access toggles | +| ๐Ÿ“ค **Data Export/Import** | Import/export warranty data via CSV | +| โš™๏ธ **Customizable Settings** | Configure currency, date formats, notification timing, and branding | +| ๐ŸŒ **Internationalization Support** | Support for multiple currencies and date formats tailored to regional preferences, enabling a seamless global user experience | +| ๐Ÿท๏ธ **Tagging** | Organize warranties using custom tags | +| ๐Ÿ” **Password Reset** | Token-based, secure account recovery system | +| ๐Ÿ”‘ **OIDC SSO** | Single sign-on with providers like Google, GitHub, and Keycloak | +| ๐Ÿ“Š **Status Dashboard** | Visual analytics and stats with charts, tables, and global/user views | +| ๐Ÿ“ฑ **Responsive UI** | Mobile-friendly interface with admin tools and improved UX | +| ๐Ÿ“ฆ **Paperless-ngx Integration** | Store/manage documents directly in Paperless-ngx with file-level control | + +--- + + +## Project Status + +**Warracker is in active beta.** +The essential features are reliable and ready for everyday use. Development is ongoing, with regular updates and improvements. + +* โœ… Stable core for tracking, notification , and managing warranty documents, files +* โœ… Full support for self-hosted deployments +* โš’๏ธ Advanced enhancements are still being worked on +* โœ๏ธ Your feedback and bug reports help shape the future of the app + +## ๐Ÿ“ธScreenshots **Home Page** -![image](https://github.com/user-attachments/assets/7d4abda3-00b8-4c35-8a52-074605e21c5a) +![image](https://github.com/user-attachments/assets/7fd27771-c6f6-4c90-9e04-fb8acb455107) -![image](https://github.com/user-attachments/assets/77130aa1-7a39-467b-a8f8-8b961f06f7a0) +![image](https://github.com/user-attachments/assets/3b4aa67a-9e2c-4f85-9f42-beea35b22814) **Status Dashboard** -![image](https://github.com/user-attachments/assets/4c938b33-d6be-4787-a2d9-9153b0234ee2) +![image](https://github.com/user-attachments/assets/0f84cbcb-e434-42b9-9874-070f6a39292e) -## โœจ Features - -- **Warranty Management:** Add, edit, and delete warranty information easily. -- **Document Storage:** Upload and manage receipts, invoices, and product manuals securely. -- **Extended Document Storage:** Securely upload and store additional product-related documents or files in ZIP or RAR format. -- **Status Tracking:** Visual indicators for warranty status (active, expiring soon, expired). -- **Notes:** Add detailed notes for each warranty, viewable and editable via a dedicated notes modal. -- **Search and Tagging:** Find warranties quickly using product names, serial numbers, vendor, notes, or multiple tags. -- **Multi-User Management:** Support for multiple user accounts; admin users can control whether new accounts can be created. -- **Responsive Design:** Optimized for both desktop and mobile devices. -- **Secure Login:** Safe and private authentication for all users. -- **Password Reset:** Token-based secure password recovery flow. -- **Email Alerts:** Customize how and when you receive expiration notifications. -- **CSV Export/Import:** Full support for backing up and restoring warranty data. -- **Currency Customization:** Personalize displayed prices with your preferred symbol. - - -## ๐Ÿ› ๏ธ Technology Stack +## ๐Ÿ› ๏ธTechnology Stack * **Frontend**: HTML, CSS, JavaScript * **Backend**: Python with Flask @@ -85,44 +96,30 @@ Warracker is an open-source warranty tracker application designed to help you ef * **Containerization**: Docker and Docker Compose * **Web Server**: Nginx -## ๐Ÿš€ Setup +## ๐Ÿ—บ๏ธRoadmap + +* โœ… User Authentication +* โœ… Settings Page +* โœ… Status Page +* โœ… Customizable Reminders +* โœ… Email Notifications +* โœ… Warranty Categories via Tags +* โœ… CSV Import/Export +* โœ… OIDC SSO Functionality +* โœ… Advanced User/Admin Controls +* โœ… Paperless-ngx integration +* [ ] Audit trail +* [ ] Warranty Claim Tracking +* [ ] Calendar Integration +* [ ] Localization Support + +## ๐Ÿš€Setup ### Prerequisites * Docker and Docker Compose installed on your system. -* Git (for cloning the repository). - -### Fresh Installation ๐Ÿ†• -1. Clone the repository: - ``` - git clone https://github.com/sassanix/Warracker.git - ``` -2. Navigate to the project directory: - ``` - cd Warracker - ``` -3. Start the application using Docker: - ``` - docker compose up - ``` - -### Updating from a Previous Version โฌ†๏ธ -1. Pull the latest changes: - ``` - git pull origin main - ``` -2. Rebuild and restart the containers: - ``` - docker compose down - docker compose up --build - ``` -3. **Access the Application:** - - Open your browser and navigate to `http://localhost:8005`. - - -## ๐Ÿ‹ Pull Docker +## ๐Ÿ‹Pull Docker ``` services: @@ -132,34 +129,20 @@ services: - "8005:80" volumes: - warracker_uploads:/data/uploads - environment: - - DB_HOST=warrackerdb - - DB_NAME=warranty_db - - DB_USER=warranty_user - - DB_PASSWORD=${DB_PASSWORD:-warranty_password} - - SMTP_HOST=smtp.email.com - - SMTP_PORT=465 - - SMTP_USERNAME=youremail@email.com - - SMTP_PASSWORD=password - - SECRET_KEY=${APP_SECRET_KEY:-your_strong_default_secret_key_here} - - MAX_UPLOAD_MB=32 # Example: Set max upload size to 32MB - - NGINX_MAX_BODY_SIZE_VALUE=32M # For Nginx, ensure this matches MAX_UPLOAD_MB in concept (e.g., 32M) - # - FLASK_DEBUG=0 + env_file: + - .env depends_on: warrackerdb: condition: service_healthy restart: unless-stopped - + warrackerdb: image: postgres:15-alpine volumes: - postgres_data:/var/lib/postgresql/data - environment: - - POSTGRES_DB=warranty_db - - POSTGRES_USER=warranty_user - - POSTGRES_PASSWORD=${DB_PASSWORD:-warranty_password} + env_file: + - .env restart: unless-stopped - healthcheck: test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"] interval: 5s @@ -171,9 +154,9 @@ volumes: warracker_uploads: ``` -To get the docker compose file please go [here](https://github.com/sassanix/Warracker/tree/main/Docker) +To get the docker compose file with environemts and .env example for warracker and the warrackerdb please go [here](https://github.com/sassanix/Warracker/tree/main/Docker) -## ๐Ÿ“ Usage +## ๐Ÿ“Usage ### Adding a Warranty @@ -188,7 +171,7 @@ To get the docker compose file please go [here](https://github.com/sassanix/Warr * Click the edit icon to modify warranty details. * Click the delete icon to remove a warranty. -## ๐Ÿ“ฆ Product Information Entry Requirements for CSV import +## Product Information Entry Requirements for CSV import | Field Name | Format / Example | Required? | Notes | |----------------|-------------------------------------------|--------------------------------------------------------|-----------------------------------------------------------------------| @@ -205,58 +188,16 @@ To get the docker compose file please go [here](https://github.com/sassanix/Warr | **Tags** | Text (`tag1,tag2`) | โŒ No (Optional) | Use comma-separated values for multiple tags. | -## ๐Ÿ’ป Development +## Why I Built This -### Local Development Environment +Warracker was born from personal frustration with warranty confusion. When my fatherโ€™s dishwasher broke, we had the invoice and assumed it was under warranty, only to find out we were referencing the wrong one, and the warranty had ended by a couple of months. -1. Clone the repository. -2. Make your changes. -3. Build and run with Docker Compose: +That experience, along with others like it, made me realize how common and avoidable these issues are. So I built **Warracker**, a simple, organized way to track purchases, receipts, and warranties. It has already saved me money by reminding me to get car repairs done before my warranty expired. - ```bash - docker-compose build - docker-compose up -d - ``` - -### Project Structure - -``` -warracker/ -โ”œโ”€โ”€ backend/ # Python Flask backend -โ”‚ โ”œโ”€โ”€ app.py # Main application logic -โ”‚ โ”œโ”€โ”€ requirements.txt # Python dependencies -โ”‚ โ””โ”€โ”€ init.sql # Database initialization -โ”œโ”€โ”€ frontend/ # Web frontend -โ”‚ โ”œโ”€โ”€ index.html -โ”‚ โ”œโ”€โ”€ script.js -โ”‚ โ””โ”€โ”€ style.css -โ”œโ”€โ”€ docker-compose.yml # Docker configuration -โ”œโ”€โ”€ Dockerfile # Container definition -โ””โ”€โ”€ nginx.conf # Web server configuration -``` - -## ๐Ÿ—บ๏ธ Roadmap - -* User Authentication - **Completed โœ…** -* Settings Page - **Completed โœ…** -* Status Page - **Completed โœ…** -* Customizing Reminders to any day needed - **Completed โœ…** -* Email Reminders for Expiring Warranties - **Completed โœ…** -* Warranty Categories/Grouping through tags - **Completed โœ…** -* Warranty Data Import (CSV) - **Completed โœ…** -* Improved Search and Filtering - **Completed โœ…** -* Warranty claim tracking - **Planned** -* Calendar Integration - **Planned** +Inspired by [**Wallos**](https://github.com/ellite/Wallos), I wanted to bring the same clarity to warranties that it brought to subscriptions and share it with anyone who's ever been burned by missed coverage. -## ๐Ÿ› ๏ธ Troubleshooting - -### Common Issues - -* **Connection Refused Error**: Ensure all containers are running (`docker-compose ps`). Verify the backend is correctly connected to the database. -* **Database Errors**: If schema issues arise, double-check that the database initialization script (`init.sql`) matches the expected schema in `app.py`. - -## ๐Ÿค Contributing +## Contributing We welcome contributions and appreciate your interest in improving this project! To get started, please follow these steps: @@ -272,7 +213,7 @@ We welcome contributions and appreciate your interest in improving this project! `git push origin feature/amazing-feature` 5. **Open a Pull Request** with a clear explanation of your changes. -### ๐Ÿ“Œ Contribution Guidelines +### ๐Ÿ“ŒContribution Guidelines * **Start with an issue**: Before submitting a Pull Request, ensure the change has been discussed in an issue. * **Help is welcome**: Check the [issues](../../issues) for open discussions or areas where help is needed. @@ -280,29 +221,43 @@ We welcome contributions and appreciate your interest in improving this project! * **Follow project style**: Match the project's code style and naming conventions. * **Be respectful**: We value inclusive and constructive collaboration. -### Contributors: +### ๐ŸคContributors: + + + -[](https://github.com/sassanix) -[](https://github.com/humrochagf) -[](https://github.com/clmcavaney) - -### โค๏ธ Supporters: +### โค๏ธSupporters: [](https://github.com/SirSpidey) +[](https://github.com/keithellis74) +[](https://github.com/CristianKerr) + + + [![Support Warracker](https://img.shields.io/badge/Support-Warracker-red?style=for-the-badge&logo=github-sponsors)](https://buymeacoffee.com/sassanix) -## ๐Ÿ“œ License + +## Join Our Community + +[![Join our Discord server!](https://invidget.switchblade.xyz/PGxVS3U2Nw)](https://discord.gg/PGxVS3U2Nw) + +Want to discuss the project or need help? Join our Discord community! + +## ๐Ÿ“œLicense This project is licensed under the GNU Affero General Public License v3.0 - see the [LICENSE](LICENSE) file for details. -## ๐Ÿ™ Acknowledgements +## ๐Ÿ™Acknowledgements * Flask * PostgreSQL * Docker +* Chart.js +* Apprise -## โญ Star History + +## โญStar History @@ -310,31 +265,3 @@ This project is licensed under the GNU Affero General Public License v3.0 - see Star History Chart - -# ๐Ÿš€ **Quick Start** - -Ready to get started? Follow our [**Setup Guide**](https://github.com/Athena25526/warracker/blob/main/SETUP.md) for detailed installation instructions. - -## ๐Ÿ”ง **Memory Optimization** - -Warracker offers configurable memory modes to run efficiently on different server specifications: - -### **Memory Modes** - -Set the `WARRACKER_MEMORY_MODE` environment variable in your `docker-compose.yml`: - -- **`optimized`** (default): 2 gevent workers, ~60-80MB RAM usage - - Best for: Small to medium servers with 1GB+ RAM - - Handles: ~50-100 concurrent users efficiently - -- **`ultra-light`**: 1 sync worker, ~40-50MB RAM usage - - Best for: Minimal VPS, Raspberry Pi, containers with <512MB RAM - - Handles: ~10-20 concurrent users efficiently - -- **`performance`**: 4 gevent workers, ~150-200MB RAM usage - - Best for: High-performance servers with 2GB+ RAM - - Handles: ~200-400 concurrent users efficiently - -### **Additional Memory Settings** - -``` \ No newline at end of file