{"id":29330781,"url":"https://github.com/bscott/subtrackr","last_synced_at":"2026-04-16T06:00:54.983Z","repository":{"id":300328745,"uuid":"1005890033","full_name":"bscott/subtrackr","owner":"bscott","description":"Self-hosted Subscription Tracker","archived":false,"fork":false,"pushed_at":"2026-04-16T04:01:21.000Z","size":24008,"stargazers_count":411,"open_issues_count":6,"forks_count":16,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-16T05:49:14.908Z","etag":null,"topics":["finance","finance-management","go","homelab","htmx","selfhosted","subscription","tracking","vibecoding"],"latest_commit_sha":null,"homepage":"https://subtrackr.xyz/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bscott.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-06-21T03:03:04.000Z","updated_at":"2026-04-16T03:58:11.000Z","dependencies_parsed_at":"2025-06-21T04:32:56.584Z","dependency_job_id":"0e59d586-d2df-4838-b910-35abfd887a49","html_url":"https://github.com/bscott/subtrackr","commit_stats":null,"previous_names":["bscott/subtrackr"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/bscott/subtrackr","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bscott%2Fsubtrackr","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bscott%2Fsubtrackr/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bscott%2Fsubtrackr/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bscott%2Fsubtrackr/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bscott","download_url":"https://codeload.github.com/bscott/subtrackr/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bscott%2Fsubtrackr/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31873606,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"online","status_checked_at":"2026-04-16T02:00:06.042Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["finance","finance-management","go","homelab","htmx","selfhosted","subscription","tracking","vibecoding"],"created_at":"2025-07-08T00:01:36.507Z","updated_at":"2026-04-16T06:00:54.861Z","avatar_url":"https://github.com/bscott.png","language":"Go","funding_links":[],"categories":["go","Go"],"sub_categories":[],"readme":"# SubTrackr\n\nA self-hosted subscription management application built with Go and HTMX. Track your subscriptions, visualize spending, and get renewal reminders.\n\n![SubTrackr Dashboard](dashboard-screenshot.png)\n\n![SubTrackr Calendar View](calendar-screenshot.png)\n\n![SubTrackr Mobile View](mobile-screenshot.png)\n\n## 🎨 Themes\n\nPersonalize your SubTrackr experience with 5 beautiful themes:\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cimg src=\"screenshots/christmas.png\" alt=\"Christmas Theme\" width=\"600\"/\u003e\u003cbr/\u003e\n      \u003cb\u003eChristmas 🎄\u003c/b\u003e\u003cbr/\u003e\n      Festive and jolly! (with snowfall animation)\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cimg src=\"screenshots/ocean.png\" alt=\"Ocean Theme\" width=\"600\"/\u003e\u003cbr/\u003e\n      \u003cb\u003eOcean\u003c/b\u003e\u003cbr/\u003e\n      Cool and refreshing\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cimg src=\"screenshots/login.png\" alt=\"Login Page\" width=\"600\"/\u003e\u003cbr/\u003e\n      \u003cb\u003eOptional Authentication\u003c/b\u003e\u003cbr/\u003e\n      Secure your data with optional login support\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n**Available themes:** Default (Light), Dark, Christmas 🎄, Midnight (Purple), Ocean (Cyan)\n\nThemes persist across all pages and are saved per user. Change themes anytime from Settings → Appearance.\n\n![Version](https://img.shields.io/github/v/release/bscott/subtrackr?logo=github\u0026label=version)\n![Go Version](https://img.shields.io/badge/go-%3E%3D1.21-00ADD8)\n![License](https://img.shields.io/badge/license-AGPL--3.0-green)\n\n## 🚀 Features\n\n- 📊 **Dashboard Overview**: Real-time stats showing monthly/annual spending\n- 💰 **Subscription Management**: Track all your subscriptions in one place with logos\n- 📅 **Calendar View**: Visual calendar showing all subscription renewal dates with iCal export and subscription URL\n- 📈 **Analytics**: Visualize spending by category and track savings\n- 🔔 **Email Notifications**: Get reminders before subscriptions renew\n- 📱 **Pushover Notifications**: Receive push notifications on your mobile device\n- 📤 **Data Export**: Export your data as CSV, JSON, or iCal format\n- 🎨 **Beautiful Themes**: 5 stunning themes including a festive Christmas theme with snowfall animation\n- 🌍 **Multi-Currency Support**: Support for USD, EUR, GBP, JPY, RUB, SEK, PLN, INR, CHF, BRL, COP, BDT, and CNY (with optional real-time conversion)\n- 🤖 **MCP Server**: AI integration via Model Context Protocol for Claude and other AI assistants\n- 🐳 **Docker Ready**: Easy deployment with Docker\n- 🔒 **Self-Hosted**: Your data stays on your server\n- 📱 **Mobile Responsive**: Optimized mobile experience with hamburger menu navigation\n\n## 🏗️ Tech Stack\n\n- **Backend**: Go with Gin framework\n- **Database**: SQLite (no external database needed!)\n- **Frontend**: HTMX + Tailwind CSS\n- **Deployment**: Docker \u0026 Docker Compose\n\n## 🚀 Quick Start\n\nSubTrackr is available as a multi-platform Docker image supporting both AMD64 and ARM64 architectures (including Apple Silicon).\n\n**Note:** SubTrackr works fully out-of-the-box with no external dependencies. The Fixer.io API key is completely optional for currency conversion features.\n\n### Option 1: Docker Compose (Recommended)\n\n1. **Create docker-compose.yml**:\n\n```yaml\nversion: '3.8'\n\nservices:\n  subtrackr:\n    image: ghcr.io/bscott/subtrackr:latest\n    container_name: subtrackr\n    ports:\n      - \"8080:8080\"\n    volumes:\n      - ./data:/app/data\n    environment:\n      - GIN_MODE=release\n      - DATABASE_PATH=/app/data/subtrackr.db\n      # Optional: Enable automatic currency conversion (requires Fixer.io API key)\n      # - FIXER_API_KEY=your_fixer_api_key_here\n    restart: unless-stopped\n```\n\n2. **Start the container**:\n\n```bash\ndocker-compose up -d\n```\n\n3. **Access SubTrackr**: Open http://localhost:8080\n\n### Option 2: Docker Run\n\n```bash\ndocker run -d \\\n  --name subtrackr \\\n  -p 8080:8080 \\\n  -v $(pwd)/data:/app/data \\\n  -e GIN_MODE=release \\\n  ghcr.io/bscott/subtrackr:latest\n\n# Optional: With currency conversion enabled\ndocker run -d \\\n  --name subtrackr \\\n  -p 8080:8080 \\\n  -v $(pwd)/data:/app/data \\\n  -e GIN_MODE=release \\\n  -e FIXER_API_KEY=your_fixer_api_key_here \\\n  ghcr.io/bscott/subtrackr:latest\n```\n\n### Option 3: Build from Source\n\n1. **Clone the repository**:\n```bash\ngit clone https://github.com/bscott/subtrackr.git\ncd subtrackr\n```\n\n2. **Build and run with Docker Compose**:\n```bash\ndocker-compose up -d --build\n```\n\n## 🐳 Deployment Guides\n\n### Portainer\n\n1. **Stack Deployment**:\n   - Go to Stacks → Add Stack\n   - Name: `subtrackr`\n   - Paste the docker-compose.yml content\n   - Deploy the stack\n\n2. **Environment Variables** (optional):\n   ```\n   PORT=8080\n   DATABASE_PATH=/app/data/subtrackr.db\n   GIN_MODE=release\n   ```\n\n3. **Volumes**:\n   - Create a volume named `subtrackr-data`\n   - Mount to `/app/data` in the container\n\n### Proxmox LXC Container\n\n1. **Create LXC Container**:\n   ```bash\n   # Create container (Ubuntu 22.04)\n   pct create 200 local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.gz \\\n     --hostname subtrackr \\\n     --memory 512 \\\n     --cores 1 \\\n     --net0 name=eth0,bridge=vmbr0,ip=dhcp \\\n     --storage local-lvm \\\n     --rootfs local-lvm:8\n   ```\n\n2. **Install Docker in LXC**:\n   ```bash\n   pct start 200\n   pct enter 200\n   \n   # Update and install Docker\n   apt update \u0026\u0026 apt upgrade -y\n   curl -fsSL https://get.docker.com | sh\n   ```\n\n3. **Deploy SubTrackr**:\n   ```bash\n   mkdir -p /opt/subtrackr\n   cd /opt/subtrackr\n   \n   # Create docker-compose.yml\n   nano docker-compose.yml\n   # Paste the docker-compose content\n   \n   docker-compose up -d\n   ```\n\n### Unraid\n\n1. **Community Applications**:\n   - Search for \"SubTrackr\" in CA\n   - Configure paths and ports\n   - Apply\n\n2. **Manual Docker Template**:\n   - Repository: `ghcr.io/bscott/subtrackr:latest`\n   - Port: `8080:8080`\n   - Path: `/app/data` → `/mnt/user/appdata/subtrackr`\n\n### Synology NAS\n\n1. **Using Docker Package**:\n   - Open Docker package\n   - Registry → Search \"subtrackr\"\n   - Download latest image\n   - Create container with port 8080 and volume mapping\n\n2. **Using Container Manager** (DSM 7.2+):\n   - Project → Create\n   - Upload docker-compose.yml\n   - Build and run\n\n## 🔧 Configuration\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `PORT` | Server port | `8080` |\n| `DATABASE_PATH` | SQLite database file path | `./data/subtrackr.db` |\n| `GIN_MODE` | Gin framework mode (debug/release) | `debug` |\n| `FIXER_API_KEY` | Fixer.io API key for currency conversion (optional) | None |\n\n### Currency Conversion (Optional)\n\nSubTrackr supports automatic currency conversion using Fixer.io exchange rates:\n\n**Without API key:** (Fully functional)\n- Basic multi-currency support with display symbols\n- Manual currency selection per subscription\n- Subscriptions displayed in their original currency\n- No automatic conversion between currencies\n\n**With Fixer.io API key:**\n- Real-time exchange rates (cached for 24 hours)\n- Automatic conversion between any supported currencies\n- Display original amount + converted amount in your preferred currency\n\n**Setup:**\n1. Sign up for free at [Fixer.io](https://fixer.io/) (1000 requests/month)\n2. Get your API key from the dashboard\n3. Add `FIXER_API_KEY=your_key_here` to your environment variables\n4. Restart SubTrackr - currency conversion will be automatically enabled\n\n**Note:** The free Fixer.io plan only allows EUR as the base currency. SubTrackr automatically handles cross-rate calculations (e.g., USD→INR goes through EUR) so all currency conversions work correctly regardless of this limitation.\n\n**Supported currencies:** USD, EUR, GBP, JPY, RUB, SEK, PLN, INR, CHF, BRL, COP, BDT, CNY\n\n### Email Notifications (SMTP)\n\nConfigure SMTP settings in the web interface:\n\n1. Navigate to Settings → Email Notifications\n2. Enter your SMTP details:\n   - **Gmail**: smtp.gmail.com:587\n   - **Outlook**: smtp-mail.outlook.com:587\n   - **Custom**: Your SMTP server details\n3. Test connection\n4. Enable renewal reminders\n\n### Pushover Notifications\n\nReceive push notifications on your mobile device via Pushover:\n\n1. **Get your Pushover credentials**:\n   - Sign up at [pushover.net](https://pushover.net/) (free account)\n   - Get your User Key from the dashboard\n   - Create an application at [pushover.net/apps/build](https://pushover.net/apps/build) to get an Application Token\n\n2. **Configure in SubTrackr**:\n   - Navigate to Settings → Pushover Notifications\n   - Enter your User Key and Application Token\n   - Click \"Test Connection\" to verify configuration\n   - Save settings\n\n3. **Notification Types**:\n   - **Renewal Reminders**: Get notified before subscriptions renew (uses the same reminder days setting as email)\n   - **High Cost Alerts**: Receive alerts when adding expensive subscriptions (uses the same threshold as email alerts)\n\n**Note**: Pushover notifications work alongside email notifications. Both will be sent when enabled, giving you multiple ways to stay informed about your subscriptions.\n\n### Data Persistence\n\n**Important**: Always mount a volume to `/app/data` to persist your database!\n\n```yaml\nvolumes:\n  - ./data:/app/data  # Local directory\n  # OR\n  - subtrackr-data:/app/data  # Named volume\n```\n\n## 🔐 Security Recommendations\n\n1. **Reverse Proxy**: Use Nginx/Traefik for HTTPS\n2. **Authentication**: Add basic auth or OAuth2 proxy\n3. **Network**: Don't expose port 8080 directly to internet\n4. **Backups**: Regular backups of the data directory\n\n### Nginx Reverse Proxy Example\n\n```nginx\nserver {\n    server_name subtrackr.yourdomain.com;\n    \n    location / {\n        proxy_pass http://localhost:8080;\n        proxy_set_header Host $host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-Forwarded-Proto $scheme;\n    }\n}\n```\n\n### Traefik Labels\n\n```yaml\nlabels:\n  - \"traefik.enable=true\"\n  - \"traefik.http.routers.subtrackr.rule=Host(`subtrackr.yourdomain.com`)\"\n  - \"traefik.http.routers.subtrackr.entrypoints=websecure\"\n  - \"traefik.http.routers.subtrackr.tls.certresolver=letsencrypt\"\n```\n\n## 📊 API Documentation\n\nSubTrackr provides a RESTful API for external integrations. All API endpoints require authentication using an API key.\n\n### Authentication\n\nCreate an API key from the Settings page in the web interface. Include the API key in your requests using one of these methods:\n\n```bash\n# Authorization header (recommended)\ncurl -H \"Authorization: Bearer sk_your_api_key_here\" https://your-domain.com/api/v1/subscriptions\n\n# X-API-Key header\ncurl -H \"X-API-Key: sk_your_api_key_here\" https://your-domain.com/api/v1/subscriptions\n```\n\n### API Endpoints\n\n#### Subscriptions\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/v1/subscriptions` | List all subscriptions |\n| POST | `/api/v1/subscriptions` | Create a new subscription |\n| GET | `/api/v1/subscriptions/:id` | Get subscription details |\n| PUT | `/api/v1/subscriptions/:id` | Update subscription |\n| DELETE | `/api/v1/subscriptions/:id` | Delete subscription |\n\n#### Statistics \u0026 Export\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/api/v1/stats` | Get subscription statistics |\n| GET | `/api/v1/export/csv` | Export subscriptions as CSV |\n| GET | `/api/v1/export/json` | Export subscriptions as JSON |\n\n### Example Requests\n\n#### List Subscriptions\n```bash\ncurl -H \"Authorization: Bearer sk_your_api_key_here\" \\\n  https://your-domain.com/api/v1/subscriptions\n```\n\n#### Create Subscription\n```bash\ncurl -X POST \\\n  -H \"Authorization: Bearer sk_your_api_key_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Netflix\",\n    \"cost\": 15.99,\n    \"schedule\": \"Monthly\",\n    \"status\": \"Active\",\n    \"category\": \"Entertainment\"\n  }' \\\n  https://your-domain.com/api/v1/subscriptions\n```\n\n#### Update Subscription\n```bash\ncurl -X PUT \\\n  -H \"Authorization: Bearer sk_your_api_key_here\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"cost\": 17.99,\n    \"status\": \"Active\"\n  }' \\\n  https://your-domain.com/api/v1/subscriptions/123\n```\n\n#### Get Statistics\n```bash\ncurl -H \"Authorization: Bearer sk_your_api_key_here\" \\\n  https://your-domain.com/api/v1/stats\n```\n\nResponse:\n```json\n{\n  \"total_count\": 15,\n  \"active_count\": 12,\n  \"total_cost\": 245.67,\n  \"categories\": {\n    \"Entertainment\": 45.99,\n    \"Productivity\": 89.00,\n    \"Storage\": 29.99\n  }\n}\n```\n\n## 🤖 MCP Server (AI Integration)\n\nSubTrackr includes a [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that allows AI assistants like Claude to read and manage your subscriptions via natural language.\n\n### Available Tools\n\n| Tool | Description |\n|------|-------------|\n| `list_subscriptions` | List all subscriptions |\n| `get_subscription` | Get a subscription by ID |\n| `create_subscription` | Create a new subscription |\n| `update_subscription` | Update an existing subscription |\n| `delete_subscription` | Delete a subscription |\n| `get_stats` | Get subscription statistics |\n\n### Setup\n\n#### Local Install\n\nBuild the MCP server binary:\n\n```bash\ngo build -o subtrackr-mcp ./cmd/mcp\n```\n\nAdd to your Claude Desktop (`claude_desktop_config.json`) or Claude Code (`.claude/settings.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"subtrackr\": {\n      \"command\": \"/path/to/subtrackr-mcp\",\n      \"env\": {\n        \"DATABASE_PATH\": \"/path/to/subtrackr.db\"\n      }\n    }\n  }\n}\n```\n\n#### Docker\n\nThe MCP binary is included in the Docker image. Configure your MCP client to exec into the container:\n\n```json\n{\n  \"mcpServers\": {\n    \"subtrackr\": {\n      \"command\": \"docker\",\n      \"args\": [\"exec\", \"-i\", \"subtrackr\", \"/app/subtrackr-mcp\"]\n    }\n  }\n}\n```\n\nThe MCP server shares the same SQLite database as the web server, so changes made through either interface are immediately visible in the other.\n\n## 🛠️ Development\n\n### Prerequisites\n\n- Go 1.21+\n- Docker (optional)\n\n### Local Development\n\n```bash\n# Install dependencies\ngo mod download\n\n# Run development server\ngo run cmd/server/main.go\n\n# Build binary\ngo build -o subtrackr cmd/server/main.go\n```\n\n### Building Docker Image\n\n```bash\n# Build for current platform\ndocker build -t subtrackr:latest .\n\n# Build multi-platform\ndocker buildx build --platform linux/amd64,linux/arm64 \\\n  -t subtrackr:latest --push .\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n## 📝 License\n\nThis project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- Built with [Gin](https://gin-gonic.com/) web framework\n- UI powered by [HTMX](https://htmx.org/) and [Tailwind CSS](https://tailwindcss.com/)\n- Icons from [Heroicons](https://heroicons.com/)\n\n## ⚠️ Known Limitations\n\n- **Price History**: SubTrackr currently tracks only the current price per subscription. If a subscription changes price over time, annual spend calculations will be based on the current price multiplied by the billing cycle, which may not reflect actual historical spending. For accurate historical tracking, consider manually updating subscription costs when prices change or keeping external records.\n\n## 📞 Support\n\n- 🐛 Issues: [GitHub Issues](https://github.com/bscott/subtrackr/issues)\n- 💬 Discussions: [GitHub Discussions](https://github.com/bscott/subtrackr/discussions)\n\n---\n\nMade with ❤️ by me and Vibing ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbscott%2Fsubtrackr","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbscott%2Fsubtrackr","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbscott%2Fsubtrackr/lists"}