SubTracker

Manage subscriptions, renewal reminders, budgets, logos, and Wallos migrations in one self-hosted dashboard.

简体中文 · Local development · Deployment · Deployment guide · Releases

The current main branch ships with Docker / Docker Compose deployment. If you need Cloudflare Worker serverless deployment, use the lite branch, where the Worker-specific workflows, deployment notes, and runtime adaptations are maintained.

Quick Start

Deploy with the install script

curl -fsSL https://raw.githubusercontent.com/Smile-QWQ/SubTracker/main/scripts/install.sh | bash

• Full mode is recommended for most users.
• The installer now asks you to choose Simplified Chinese or English at the start. You can still force it with --lang zh or --lang en.
• Release artifacts support both x86 and ARM.
• See DEPLOYMENT.md for the full deployment flow.

Run locally

npm install
npm run prisma:generate
npm run prisma:push
npm run prisma:seed
npm run dev

Default addresses:

• Web: http://127.0.0.1:5173
• API: http://127.0.0.1:3001

Default credentials:

• Username: admin
• Password: admin

Screenshots

Dashboard

More views

Subscriptions	Spending

AI recognition	Wallos import

Features

• Subscription management: create, duplicate, edit, renew, pause, disable, and restore subscriptions; add, correct, and delete payment records; attach multiple note images via local upload or URL; and manage larger collections with tags, multi-tag filtering, custom ordering, search, bulk status updates, and bulk deletion.
• Lifetime purchases: track lifetime licenses and one-time purchases separately, with a dedicated investment total and no renewal reminders or recurring spending projections.
• Reminder rules: define reminders before renewal, on the renewal day, and after expiration with the days&time; format; override defaults per subscription; and preview the resulting trigger schedule before saving.
• Statistics and budgets: normalize multi-currency subscriptions into a base currency, track spending totals and trends, inspect monthly/yearly tag spending and status breakdowns, review the next 30 days of renewals, compare auto-renew ratios, and configure monthly, yearly, or per-tag budgets. Historical spending keeps recorded currencies separate, with monthly trends, subscription rankings, and linked payment details.
• AI assistance: extract subscription details from text or images into the form, and generate an AI summary on the statistics page. Includes provider presets, OpenAI/Claude/Gemini API support, model lists, and capability diagnostics.
• Calendar and overview: view subscriptions in a calendar, track upcoming renewals from the dashboard, and renew in place or jump to the matching subscription.
• Notifications: send reminders through Webhook, SMTP / Resend email, PushPlus, Telegram Bot, ServerChan, Gotify, Bark, NotifyX, and Apprise.
• Logos and assets: upload logos or import them from a URL, reuse saved local logos, search online, and preserve assets in ZIP backups. Supports common raster formats, SVG, and animated GIFs.
• Backup and migration: import Wallos JSON, SQLite, and ZIP backups, and export, inspect, import, or restore native SubTracker ZIP backups.
• Multi-currency tools: maintain exchange-rate data, convert values into the base currency, and use the built-in currency converter.
• Login and session controls: support remember-me sessions, default-password change reminders, and rate limiting after repeated login failures.
• Interface: support Simplified Chinese and English, light, dark, and system themes, with a sticky desktop sidebar and independently scrollable content.

Tech Stack

• Frontend: Vue 3, Vite, TypeScript, Naive UI, Pinia, TanStack Query, ECharts
• Backend: Fastify, Prisma, SQLite, Zod, node-cron

Local Development

1. Install dependencies

npm install

2. Copy the API environment template

cp apps/api/.env.example apps/api/.env

3. Initialize the database

npm run prisma:generate
npm run prisma:push
npm run prisma:seed

4. Start the dev environment

npm run dev

After the first login, changing the default admin password is strongly recommended. Login attempts are rate-limited after too many failures.

Useful Commands

npm run dev
npm run build
npm run lint
npm test

Deployment

Use the install script for the smoothest setup:

curl -fsSL https://raw.githubusercontent.com/Smile-QWQ/SubTracker/main/scripts/install.sh | bash

The script downloads release artifacts, prepares the deployment directory, and lets you choose between:

• Full deployment (full): deploy web and API together with the published frontend image
• API-only deployment (api): deploy only the API container and host the web assets yourself

Full deployment is the recommended default.

On first startup, the API container initializes the SQLite schema automatically.

If you want to use Apprise, deploy an Apprise API instance separately and point SubTracker to it in Settings → Notifications → Apprise. The default SubTracker compose files do not make Apprise a hard dependency.

Updating

For routine upgrades:

docker compose pull
docker compose up -d

If you use API-only mode, you also need to download and replace the extracted contents of subtracker-web-dist.zip.

You only need to rerun the install script when:

• deploying for the first time
• rebuilding the deployment directory
• switching between api and full
• adopting a newer deployment template or updated .env defaults

See DEPLOYMENT.md for the complete guide.

Release Artifacts

Each release currently provides:

• subtracker-web-dist.zip: frontend static assets
• ghcr.io/smile-qwq/subtracker-api: API Docker image
• ghcr.io/smile-qwq/subtracker-web: frontend image used in full deployment

All published images support both x86 and ARM architectures.

License

This project is released under the GNU General Public License v3.0 (GPLv3).

Acknowledgements

Thanks to the following projects and ecosystems:

• Wallos — migration reference and compatibility direction
• Vue 3 and Vite — frontend foundation
• Naive UI — UI components
• Fastify and Prisma — backend and data access
• Pinia, TanStack Query, and ECharts — state, data fetching, and charts

Star History