Shepherd

An unofficial Progressive Web App (PWA) for GoatCounter analytics. Track your website analytics on the go with a mobile-friendly interface.

Features

• Real-time Analytics: View stats from multiple GoatCounter sites in one place
• Flexible Date Ranges: Support for hourly (1H, 6H, 12H) and daily (1D, 7D, 30D) time periods
• Visual Analytics: Interactive world map showing visitor locations with color-coded intensity
• Detailed Metrics: Track page views, unique visitors, browser stats, and referral sources
• Offline Support: Smart caching keeps your data available even without internet
• PWA Ready: Install on mobile and desktop devices for a native app experience
• Secure: Store your API key locally or compile it into the app

Getting Started

A free version of this site is available. If this gets slammed with routine use, then it may be removed.

Prerequisites

• Node.js 18 or higher
• A GoatCounter account with API access

Installation

1. Clone the repository:

git clone https://github.com/serrodneyrich/shepherd.git
cd shepherd

2. Install dependencies:

npm install

3. Run the development server:

npm run dev

4. Open [http://localhost:3000] in your browser

Configuration

Option 1: UI Configuration (Recommended for Public Instances)

1. Open the app and navigate to Settings
2. Enter your GoatCounter API key
   • Go to your GoatCounter site → Click @Username (top-right) → Settings → API
   • Generate API Key with "Read Sites" and "Read Statistics" permissions only
   • ⚠️ Never use an API key with write permissions
3. Add your GoatCounter sites (site code is the subdomain, e.g., "example" from example.goatcounter.com)
4. Start viewing your analytics

⚠️ Security Note: Your API key is stored in browser localStorage. Anyone with physical access to your device can retrieve it. Only use on trusted devices.

Option 2: Environment Variable (Self-Hosted Deployments Only)

⚠️ WARNING: This option is ONLY for self-hosted/forked deployments. Do NOT use this for public instances as it will expose your API key to all users.

For self-hosted deployments, you can pre-configure an API key:

1. Create a .env.local file in the project root:

NEXT_PUBLIC_GOATCOUNTER_API_KEY=your_read_only_api_key_here

2. Build and deploy your instance

Important:

• NEXT_PUBLIC_* variables are embedded in the client-side JavaScript bundle
• Anyone can view the value by inspecting your deployed app
• Only use read-only API keys
• Never commit .env.local to version control (already in .gitignore)

API Rate Limiting

Shepherd implements conservative rate limiting (roughly 2 requests per second) to respect GoatCounter's API limits. The app also caches responses for 5 minutes to reduce unnecessary API calls.

Rate limiting is coordinated across browser tabs to prevent accidental API abuse when multiple tabs are open.

Security

Client-Side Architecture

Shepherd is a client-side Progressive Web App (PWA). This means:

• All code runs in your browser
• API calls are made directly from your device to GoatCounter
• There is no backend server processing your requests

API Key Security

Best Practices:

1. Use Read-Only API Keys: Create API keys with ONLY "Read Sites" and "Read Statistics" permissions
2. Never Share API Keys: Your API key grants access to your analytics data
3. Trusted Devices Only: Only enter your API key on devices you control
4. Self-Host for Production: For maximum security, fork and deploy your own instance

Security Limitations:

• API keys are stored in browser localStorage (unencrypted)
• Keys are visible in browser DevTools to anyone with device access
• This is inherent to client-side PWA architecture

Privacy

• No Tracking: Shepherd itself does not collect or track any user data
• No Third-Party Services: No data is sent to third parties (except GoatCounter API)
• Local Storage: All settings and cache are stored locally in your browser
• Offline Capable: Data is cached locally for offline access

Reporting Security Issues

If you discover a security vulnerability, please:

1. Do not open a public GitHub issue
2. Email the maintainer or use GitHub's private security advisory feature
3. Provide details about the vulnerability and steps to reproduce

License

This project is open source and available under the MIT License.

Acknowledgments

• GoatCounter - The excellent privacy-friendly analytics platform this app is built for
• The open source community for the amazing tools and libraries

Support

• For GoatCounter questions: GoatCounter Help

Disclaimer

This is an unofficial third-party application and is not affiliated with or endorsed by GoatCounter. Use at your own risk.