# Warracker: a self-hosted warranty tracker you run in Docker

> Warracker is an AGPL-3.0 Flask and PostgreSQL application for tracking product warranties, receipts and claims on your own server. It installs from a Compose file, but the setup documentation stops short of the first login.

**sassanix/Warracker** — 🛡️ Warracker is an open source, self-hostable warranty tracker to monitor expirations, store receipts, files. You own the data, your rules!

- Repository: https://github.com/sassanix/Warracker
- Website: https://warracker.com
- Stars: 1,491 · Forks: 48
- Language: JavaScript
- License: AGPL-3.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/sassanix-warracker

## What Warracker tracks that a spreadsheet does not

A warranty spreadsheet fails in a predictable way. The purchase date is a cell, the receipt is a PDF in a downloads folder, and the claim you filed in month eight lives in an email thread. Warracker puts those three things behind one login. The README lists the record fields directly: purchase dates, durations, notes, product photos with thumbnail previews, and uploaded receipts, invoices and manuals. Each product can carry multiple serial numbers, which matters for bundles and for appliances where the serial is stamped somewhere you will not look again.

The audience is narrow and stated: individuals and teams, self-hosted. The repository topics repeat it (asset-tracker, self-hosted, warranty-management). This is not a consumer app with a signup page. You supply the server, the database and the SMTP credentials. In exchange, the files sit on a volume you mount, and the export is a CSV you can take elsewhere. The README's own framing is that you own the data.

Two features push it past a simple expiry list. Warranty claims are tracked end to end with statuses, dates and resolutions, so a claim is a record with a lifecycle rather than a note. The status dashboard renders charts and tables over the same data. Neither is unusual on its own. Together they mean the tool covers the period after a product fails, which is when most warranty spreadsheets have already been abandoned.

## Flask, PostgreSQL and Nginx inside one container

The stack is conventional and the repository layout confirms it. backend/ holds Python Flask code, frontend/ holds HTML, CSS and JavaScript, locales/ and babel.cfg handle translation, and nginx.conf sits at the top level. PostgreSQL 15-alpine is a separate service. The Dockerfile is a two-stage build: a builder stage on python:3.13-slim-trixie installs build-essential, libpq-dev and libcurl4-openssl-dev to compile the Python dependencies, and a runtime stage installs nginx, supervisor, postgresql-client and the runtime libraries. The final image runs as a non-root user, uid 999, created with useradd. Supervisor starts nginx and the Flask process together, which is why the container exposes port 80 rather than a Flask port.

Data flow is short. The browser talks to nginx on port 80, nginx proxies to the Flask application, and Flask reads and writes PostgreSQL over the DB_HOST, DB_PORT, DB_NAME, DB_USER and DB_PASSWORD variables. Uploaded files go to /data/uploads, which the Compose file maps to a named volume or a host directory. Migrations are mounted from backend/migrations into /app/migrations, so schema changes ship with the image rather than in a separate step.

Notifications are the one piece of external plumbing. The README says alerts go out by email or through Apprise, which covers 100+ push services including Discord and Slack. Apprise is toggled with APPRISE_ENABLED, which defaults to false in the Compose file. OIDC single sign-on is configured through OIDC_PROVIDER_NAME, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, OIDC_ISSUER_URL and OIDC_SCOPE, with Google, GitHub and Keycloak named as examples. Both integrations are opt-in and both are inert until you fill in the variables, which is the right default.

## Installing Warracker with Docker Compose

The README's prerequisites are Docker and Docker Compose, and nothing else. There is no package on npm or PyPI for the application itself; the image is published to the GitHub Container Registry as ghcr.io/sassanix/warracker/main:latest. The README's Compose example runs the app on host port 8005, mapping to port 80 in the container, with a named volume for uploads and a second service for PostgreSQL 15-alpine.

```yaml
services:
  warracker:
    image: ghcr.io/sassanix/warracker/main:latest
    ports:
      - "8005:80"
    volumes:
      - warracker_uploads:/data/uploads
    env_file:
      - .env
    depends_on:
      warrackerdb:
        condition: service_healthy
    restart: unless-stopped
```

The healthcheck on the database service is what makes depends_on meaningful here. It runs pg_isready against $$POSTGRES_USER and $$POSTGRES_DB, with a 5 second interval, a 5 second timeout and 5 retries, so the app container waits for a database that actually accepts connections rather than one that has merely started.

The repository also carries a docker-compose.yml that builds from the local Dockerfile instead of pulling the image. It sets DB_NAME to warranty_test and DB_USER to warranty_user, and it mounts ./uploads and ./backend/migrations from the working directory. Several values have defaults that are fine for a trial and wrong for anything public: DB_PASSWORD falls back to warranty_password, DB_ADMIN_PASSWORD to change_this_password_in_production, and SECRET_KEY to your_very_secret_flask_key_change_me. The Compose file's own comment says SECRET_KEY is used for the Flask session and JWT, so it is not cosmetic.

```bash
cp env.example .env
docker compose up -d
```

After that, the app answers on http://localhost:8005, which is also the default FRONTEND_URL and APP_BASE_URL in the Compose file. Those two variables matter more than they look: the comment next to them says they are important for redirects and email links, so a wrong value breaks OIDC callbacks and notification links even though the UI loads fine. The README does not document a default administrator account or a first-login procedure, so treat account creation as something to confirm against env.example and the running instance rather than something this article can tell you.

## Where the documentation leaves you on your own

The README is a feature table and a Compose snippet. It does not document rollback, and it does not document backup or restore of the PostgreSQL volume, which is the one procedure a self-hosted records tool needs most. Uploaded files and database rows are two separate stores: the warracker_uploads volume holds receipts, and the database holds the metadata that points at them. Restoring one without the other gives you records with missing attachments, or orphaned files. Nothing in the repository describes how to keep them consistent.

Upgrades are the other soft spot. The README pulls the main tag, which moves. There is no documented migration step, no note on whether a downgrade is possible, and no statement about what happens to the schema when an older image meets a newer database. The release history shows 1.0.0, 1.0.1 and 1.0.2 within five days in October 2025, and the last push to the repository was on 2026-09-07. Frequent early point releases plus a long tail of commits is a normal shape for a project this age, but it means you should pin an image tag rather than track main if you care about a working instance on a Monday morning.

The project describes itself as in active development, with the core stable and advanced enhancements still being worked on. Calendar integration is listed on the roadmap as unchecked. The README does not say what happens to a warranty claim record when a user is deleted, or how the global warranty view interacts with per-user permissions beyond a role-based toggle. Those are the questions to answer before a team relies on it.

## Warracker against a general document manager

Paperless-ngx is the obvious comparison, and Warracker's own feature list includes an integration with it: documents can be stored and managed directly in Paperless-ngx with file-level control. The difference is the data model. Paperless-ngx is built around documents, tags and correspondents, and a warranty is a document with a date on it. Warracker is built around a warranty record that owns its dates, serial numbers, claim status and attachments. If you already run Paperless-ngx for everything else, the integration lets you keep the files there and the expiry logic in Warracker, which is a sensible split.

Against a spreadsheet, the difference is alerts and access control. A spreadsheet cannot email you, cannot push to Discord through Apprise, and cannot give one user read-only access to a global view while another edits their own records. Against a hosted warranty service, the difference is custody. Warracker's files live on a volume you mount and its data lives in a PostgreSQL instance you run, which is also the cost: you are the operator.

## Licence and the cost of keeping it running

Warracker is licensed AGPL-3.0. For an individual or an internal team running it on their own infrastructure, that is the same practical situation as most self-hosted software: you can use and modify it, and if you distribute a modified version or offer it to users over a network, the licence's source-availability terms come into play. If you plan to build a hosted service on top of it, read the licence text in the repository rather than a summary, and take advice if the answer matters commercially.

The running cost is a container plus a PostgreSQL 15 instance. The Compose file mounts migrations from the host, so the schema is managed by the image you deploy, and the database volume is the thing you must not lose. There is no documented upgrade path, so budget for reading CHANGELOG.md before each image bump and for testing a restore of both the database and the uploads volume. The notification path adds one more dependency: if APPRISE_ENABLED is true, an Apprise endpoint or SMTP server has to stay reachable, or expirations will pass silently.

## Conclusion

Adopt Warracker if you already run Docker and PostgreSQL and want warranty records, receipts and claim status in one place you control, and if you are comfortable reading env.example and docker-compose.yml to fill in the gaps the README leaves. Do not adopt it if you need a hosted service with no server administration, or if a documented first-login and recovery path is a hard requirement. Verify the .env values, the uploads volume mapping and the database credentials before you point it at anything you care about.

## FAQ

### What is the best app to track warranties?

Warracker is one option: a self-hosted warranty tracker that stores purchase dates, durations, serial numbers, receipts and claim status, and sends expiration alerts by email or through Apprise. Choosing between it and a hosted service comes down to whether you want to run the PostgreSQL database and Docker container yourself.

### What is the best software for warranty management?

Warracker is an open source, self-hostable option under AGPL-3.0, built on Flask and PostgreSQL and shipped as a Docker image. For teams, it adds multi-user accounts, role-based permissions on a global warranty view, and CSV import and export.

### Is there a default login or password for a new Warracker instance?

The README does not document a default administrator account or password. The Compose file does define fallback values for DB_PASSWORD, DB_ADMIN_PASSWORD and SECRET_KEY, and its own comment marks the admin password as one to change in production, but no application login credential is given.

## Sources

- [License: AGPL-3.0](https://github.com/sassanix/Warracker/blob/main/LICENSE)
- [Project website](https://warracker.com)
- [README](https://github.com/sassanix/Warracker/blob/main/README.md)
- [Releases](https://github.com/sassanix/Warracker/releases)
- [sassanix/Warracker on GitHub](https://github.com/sassanix/Warracker)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sassanix-warracker