mirror of
https://github.com/sassanix/Warracker.git
synced 2026-01-07 06:00:13 -06:00
Revert README.md to version from June 27 commit
This commit is contained in:
sassanix
299
README.md
299
README.md
@@ -1,83 +1,94 @@
|
||||
|
||||
<div align="center">
|
||||
|
||||
<img src="https://github.com/user-attachments/assets/2132a842-4233-4d37-8fde-b2d23353ed76" width="145"/>
|
||||
<img src="https://github.com/user-attachments/assets/2132a842-4233-4d37-8fde-b2d23353ed76" width="100"/>
|
||||
|
||||
<h1 <strong>Warracker</strong></h1>
|
||||
|
||||
<p align="center">
|
||||
<b>Open-source warranty tracker for individuals and teams.</b> <br/>
|
||||
The easiest way to organize product warranties, monitor expiration dates, and store receipts or related documents.
|
||||
</b>
|
||||
</p>
|
||||
</div>
|
||||
|
||||
|
||||
<div align="center">
|
||||
|
||||
<!--  -->
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
<!--  -->
|
||||
[](https://github.com/denser-org/denser-retriever/pulls?utf8=%E2%9C%93&q=is%3Apr%20author%3Aapp%2Fdependabot)
|
||||
|
||||
[](https://discord.gg/PGxVS3U2Nw)
|
||||
|
||||
<p align="center">
|
||||
<img src="images/demo.gif" alt="Warracker Demo" width="600">
|
||||
</p>
|
||||
|
||||
|
||||
#
|
||||
|
||||
|
||||
|
||||
</div>
|
||||
⭐ 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**
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
**Status Dashboard**
|
||||
|
||||
|
||||
|
||||
|
||||
## ✨ 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:
|
||||
<a href="https://github.com/sassanix/warracker/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=sassanix/warracker" />
|
||||
</a>
|
||||
|
||||
[<img src="https://avatars.githubusercontent.com/u/39465071?s=50&v=4" width="50"/>](https://github.com/sassanix)
|
||||
[<img src="https://avatars.githubusercontent.com/u/1223625?s=50&v=4" width="50"/>](https://github.com/humrochagf)
|
||||
[<img src="https://avatars.githubusercontent.com/u/5875512?s=50&v=4" width="50"/>](https://github.com/clmcavaney)
|
||||
|
||||
### ❤️ Supporters:
|
||||
### ❤️Supporters:
|
||||
|
||||
[<img src="https://avatars.githubusercontent.com/u/8194208?u=7ee82feed0044f85bcfc39f001643fe81a188f66&v=4&s=50" width="50"/>](https://github.com/SirSpidey)
|
||||
[<img src="https://avatars.githubusercontent.com/u/6196195?v=4&s=50" width="50"/>](https://github.com/keithellis74)
|
||||
[<img src="https://avatars.githubusercontent.com/u/79404036?v=4&s=50" width="50"/>](https://github.com/CristianKerr)
|
||||
|
||||
|
||||
|
||||
|
||||
[](https://buymeacoffee.com/sassanix)
|
||||
|
||||
## 📜 License
|
||||
|
||||
## Join Our Community
|
||||
|
||||
[](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
|
||||
<a href="https://star-history.com/#sassanix/Warracker&Date">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=sassanix/Warracker&type=Date&theme=dark" />
|
||||
@@ -310,31 +265,3 @@ This project is licensed under the GNU Affero General Public License v3.0 - see
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=sassanix/Warracker&type=Date" />
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
# 🚀 **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**
|
||||
|
||||
```
|
||||
Reference in New Issue
Block a user