SubTrackr

A self-hosted subscription management application built with Go and HTMX. Track your subscriptions, visualize spending, and get renewal reminders.

🎨 Themes

Personalize your SubTrackr experience with 5 beautiful themes:

Christmas 🎄 Festive and jolly! (with snowfall animation)

Ocean Cool and refreshing

Optional Authentication Secure your data with optional login support

Available themes: Default (Light), Dark, Christmas 🎄, Midnight (Purple), Ocean (Cyan)

Themes persist across all pages and are saved per user. Change themes anytime from Settings → Appearance.

🚀 Features

• 📊 Dashboard Overview: Real-time stats showing monthly/annual spending
• 💰 Subscription Management: Track all your subscriptions in one place with logos
• 📅 Calendar View: Visual calendar showing all subscription renewal dates with iCal export and subscription URL
• 📈 Analytics: Visualize spending by category and track savings
• 🔔 Email Notifications: Get reminders before subscriptions renew
• 📱 Pushover Notifications: Receive push notifications on your mobile device
• 📤 Data Export: Export your data as CSV, JSON, or iCal format
• 🎨 Beautiful Themes: 5 stunning themes including a festive Christmas theme with snowfall animation
• 🌍 Multi-Currency Support: Support for USD, EUR, GBP, JPY, RUB, SEK, PLN, INR, CHF, BRL, COP, BDT, and CNY (with optional real-time conversion)
• 🤖 MCP Server: AI integration via Model Context Protocol for Claude and other AI assistants
• 🐳 Docker Ready: Easy deployment with Docker
• 🔒 Self-Hosted: Your data stays on your server
• 📱 Mobile Responsive: Optimized mobile experience with hamburger menu navigation

🏗️ Tech Stack

• Backend: Go with Gin framework
• Database: SQLite (no external database needed!)
• Frontend: HTMX + Tailwind CSS
• Deployment: Docker & Docker Compose

🚀 Quick Start

SubTrackr is available as a multi-platform Docker image supporting both AMD64 and ARM64 architectures (including Apple Silicon).

Note: SubTrackr works fully out-of-the-box with no external dependencies. The Fixer.io API key is completely optional for currency conversion features.

Option 1: Docker Compose (Recommended)

1. Create docker-compose.yml:

version: '3.8'

services:
  subtrackr:
    image: ghcr.io/bscott/subtrackr:latest
    container_name: subtrackr
    ports:
      - "8080:8080"
    volumes:
      - ./data:/app/data
    environment:
      - GIN_MODE=release
      - DATABASE_PATH=/app/data/subtrackr.db
      # Optional: Enable automatic currency conversion (requires Fixer.io API key)
      # - FIXER_API_KEY=your_fixer_api_key_here
    restart: unless-stopped

1. Start the container:

docker-compose up -d

1. Access SubTrackr: Open http://localhost:8080

Option 2: Docker Run

docker run -d \
  --name subtrackr \
  -p 8080:8080 \
  -v $(pwd)/data:/app/data \
  -e GIN_MODE=release \
  ghcr.io/bscott/subtrackr:latest

# Optional: With currency conversion enabled
docker run -d \
  --name subtrackr \
  -p 8080:8080 \
  -v $(pwd)/data:/app/data \
  -e GIN_MODE=release \
  -e FIXER_API_KEY=your_fixer_api_key_here \
  ghcr.io/bscott/subtrackr:latest

Option 3: Build from Source

1. Clone the repository:

git clone https://github.com/bscott/subtrackr.git
cd subtrackr

1. Build and run with Docker Compose:

docker-compose up -d --build

🐳 Deployment Guides

Portainer

1. Stack Deployment:
2. Go to Stacks → Add Stack
3. Name: subtrackr
4. Paste the docker-compose.yml content

5. Deploy the stack

6. Environment Variables (optional): PORT=8080 DATABASE_PATH=/app/data/subtrackr.db GIN_MODE=release

7. Volumes:

8. Create a volume named subtrackr-data
9. Mount to /app/data in the container

Proxmox LXC Container

1. Create LXC Container: bash # Create container (Ubuntu 22.04) pct create 200 local:vztmpl/ubuntu-22.04-standard_22.04-1_amd64.tar.gz \ --hostname subtrackr \ --memory 512 \ --cores 1 \ --net0 name=eth0,bridge=vmbr0,ip=dhcp \ --storage local-lvm \ --rootfs local-lvm:8

2. Install Docker in LXC: ```bash pct start 200 pct enter 200

# Update and install Docker apt update && apt upgrade -y curl -fsSL https://get.docker.com | sh ```

1. Deploy SubTrackr: ```bash mkdir -p /opt/subtrackr cd /opt/subtrackr

# Create docker-compose.yml nano docker-compose.yml # Paste the docker-compose content

docker-compose up -d ```

Unraid

1. Community Applications:
2. Search for "SubTrackr" in CA
3. Configure paths and ports

4. Apply

5. Manual Docker Template:

6. Repository: ghcr.io/bscott/subtrackr:latest
7. Port: 8080:8080
8. Path: /app/data → /mnt/user/appdata/subtrackr

Synology NAS

1. Using Docker Package:
2. Open Docker package
3. Registry → Search "subtrackr"
4. Download latest image

5. Create container with port 8080 and volume mapping

6. Using Container Manager (DSM 7.2+):

7. Project → Create
8. Upload docker-compose.yml
9. Build and run

🔧 Configuration

Environment Variables

Variable	Description	Default
PORT	Server port	8080
DATABASE_PATH	SQLite database file path	./data/subtrackr.db
GIN_MODE	Gin framework mode (debug/release)	debug
FIXER_API_KEY	Fixer.io API key for currency conversion (optional)	None

Currency Conversion (Optional)

SubTrackr supports automatic currency conversion using Fixer.io exchange rates:

Without API key: (Fully functional) - Basic multi-currency support with display symbols - Manual currency selection per subscription - Subscriptions displayed in their original currency - No automatic conversion between currencies

With Fixer.io API key: - Real-time exchange rates (cached for 24 hours) - Automatic conversion between any supported currencies - Display original amount + converted amount in your preferred currency

Setup: 1. Sign up for free at Fixer.io (1000 requests/month) 2. Get your API key from the dashboard 3. Add FIXER_API_KEY=your_key_here to your environment variables 4. Restart SubTrackr - currency conversion will be automatically enabled

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.

Supported currencies: USD, EUR, GBP, JPY, RUB, SEK, PLN, INR, CHF, BRL, COP, BDT, CNY

Email Notifications (SMTP)

Configure SMTP settings in the web interface:

1. Navigate to Settings → Email Notifications
2. Enter your SMTP details:
3. Gmail: smtp.gmail.com:587
4. Outlook: smtp-mail.outlook.com:587
5. Custom: Your SMTP server details
6. Test connection
7. Enable renewal reminders

Pushover Notifications

Receive push notifications on your mobile device via Pushover:

1. Get your Pushover credentials:
2. Sign up at pushover.net (free account)
3. Get your User Key from the dashboard

4. Create an application at pushover.net/apps/build to get an Application Token

5. Configure in SubTrackr:

6. Navigate to Settings → Pushover Notifications
7. Enter your User Key and Application Token
8. Click "Test Connection" to verify configuration

9. Save settings

10. Notification Types:

11. Renewal Reminders: Get notified before subscriptions renew (uses the same reminder days setting as email)
12. High Cost Alerts: Receive alerts when adding expensive subscriptions (uses the same threshold as email alerts)

Note: Pushover notifications work alongside email notifications. Both will be sent when enabled, giving you multiple ways to stay informed about your subscriptions.

Data Persistence

Important: Always mount a volume to /app/data to persist your database!

volumes:
  - ./data:/app/data  # Local directory
  # OR
  - subtrackr-data:/app/data  # Named volume

🔐 Security Recommendations

1. Reverse Proxy: Use Nginx/Traefik for HTTPS
2. Authentication: Add basic auth or OAuth2 proxy
3. Network: Don't expose port 8080 directly to internet
4. Backups: Regular backups of the data directory

Nginx Reverse Proxy Example

server {
    server_name subtrackr.yourdomain.com;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Traefik Labels

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.subtrackr.rule=Host(`subtrackr.yourdomain.com`)"
  - "traefik.http.routers.subtrackr.entrypoints=websecure"
  - "traefik.http.routers.subtrackr.tls.certresolver=letsencrypt"

📊 API Documentation

SubTrackr provides a RESTful API for external integrations. All API endpoints require authentication using an API key.

Authentication

Create an API key from the Settings page in the web interface. Include the API key in your requests using one of these methods:

# Authorization header (recommended)
curl -H "Authorization: Bearer sk_your_api_key_here" https://your-domain.com/api/v1/subscriptions

# X-API-Key header
curl -H "X-API-Key: sk_your_api_key_here" https://your-domain.com/api/v1/subscriptions

API Endpoints

Subscriptions

Method	Endpoint	Description
GET	/api/v1/subscriptions	List all subscriptions
POST	/api/v1/subscriptions	Create a new subscription
GET	/api/v1/subscriptions/:id	Get subscription details
PUT	/api/v1/subscriptions/:id	Update subscription
DELETE	/api/v1/subscriptions/:id	Delete subscription

Statistics & Export

Method	Endpoint	Description
GET	/api/v1/stats	Get subscription statistics
GET	/api/v1/export/csv	Export subscriptions as CSV
GET	/api/v1/export/json	Export subscriptions as JSON

Example Requests

List Subscriptions

curl -H "Authorization: Bearer sk_your_api_key_here" \
  https://your-domain.com/api/v1/subscriptions

Create Subscription

curl -X POST \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Netflix",
    "cost": 15.99,
    "schedule": "Monthly",
    "status": "Active",
    "category": "Entertainment"
  }' \
  https://your-domain.com/api/v1/subscriptions

Update Subscription

curl -X PUT \
  -H "Authorization: Bearer sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "cost": 17.99,
    "status": "Active"
  }' \
  https://your-domain.com/api/v1/subscriptions/123

Get Statistics

curl -H "Authorization: Bearer sk_your_api_key_here" \
  https://your-domain.com/api/v1/stats

Response:

{
  "total_count": 15,
  "active_count": 12,
  "total_cost": 245.67,
  "categories": {
    "Entertainment": 45.99,
    "Productivity": 89.00,
    "Storage": 29.99
  }
}

🤖 MCP Server (AI Integration)

SubTrackr includes a Model Context Protocol (MCP) server that allows AI assistants like Claude to read and manage your subscriptions via natural language.

Available Tools

Tool	Description
list_subscriptions	List all subscriptions
get_subscription	Get a subscription by ID
create_subscription	Create a new subscription
update_subscription	Update an existing subscription
delete_subscription	Delete a subscription
get_stats	Get subscription statistics

Setup

Local Install

Build the MCP server binary:

go build -o subtrackr-mcp ./cmd/mcp

Add to your Claude Desktop (claude_desktop_config.json) or Claude Code (.claude/settings.json):

{
  "mcpServers": {
    "subtrackr": {
      "command": "/path/to/subtrackr-mcp",
      "env": {
        "DATABASE_PATH": "/path/to/subtrackr.db"
      }
    }
  }
}

Docker

The MCP binary is included in the Docker image. Configure your MCP client to exec into the container:

{
  "mcpServers": {
    "subtrackr": {
      "command": "docker",
      "args": ["exec", "-i", "subtrackr", "/app/subtrackr-mcp"]
    }
  }
}

The MCP server shares the same SQLite database as the web server, so changes made through either interface are immediately visible in the other.

🛠️ Development

Prerequisites

• Go 1.21+
• Docker (optional)

Local Development

```bash

Install dependencies

go mod download

Run development server

go run cmd/server/main.go

Build binary

go build -o subtrackr cmd/server/main.