Deploying ghstats

Introduction

ghstats is a GitHub statistics dashboard that provides visual insights into repository activity, contribution patterns, and development metrics. It aggregates data from the GitHub API to create comprehensive visualizations of your open source projects or organization’s development activity.

Built for developers and teams who want to understand their GitHub presence, ghstats offers charts, graphs, and metrics that go beyond GitHub’s built-in analytics. Whether you are tracking personal contributions or monitoring organization-wide activity, ghstats provides actionable insights.

Key highlights of ghstats:

• Contribution Graphs: Visualize commit activity over time
• Repository Metrics: Stars, forks, issues, and pull request statistics
• Language Breakdown: See code composition across repositories
• Activity Trends: Track development patterns and velocity
• Comparison Views: Compare metrics across repositories
• User Statistics: Profile-level contribution analysis
• Organization Support: Aggregate statistics for entire organizations
• API Integration: Direct GitHub API data fetching
• Caching: Efficient caching to respect rate limits
• Open Source: Community-driven development

This guide walks through deploying ghstats on Klutch.sh using Docker.

Why Deploy ghstats on Klutch.sh

Deploying ghstats on Klutch.sh provides several advantages:

Always Available: Access your GitHub statistics dashboard anytime.

Team Access: Share dashboards with your team without local setup.

Persistent Cache: Cached data survives container restarts.

HTTPS Security: Secure access to your analytics dashboard.

Regular Updates: Automatic data refresh from GitHub API.

Prerequisites

Before deploying ghstats on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• A GitHub Personal Access Token for API access
• Basic familiarity with Docker

Understanding ghstats Architecture

ghstats typically consists of:

Data Fetcher: Retrieves statistics from GitHub’s REST and GraphQL APIs.

Cache Layer: Stores fetched data to minimize API calls.

Web Server: Serves the dashboard and visualizations.

Chart Library: Renders interactive charts and graphs.

Preparing Your Repository

Create a GitHub repository with your ghstats configuration.

Repository Structure

ghstats-deploy/
├── Dockerfile
├── config.json
└── .dockerignore

Creating the Dockerfile

FROM node:18-alpine

WORKDIR /app

# Install dependencies
RUN npm install -g ghstats-cli

# Or build from source
# RUN apk add --no-cache git && \
#     git clone https://github.com/your-ghstats-fork.git . && \
#     npm install && npm run build

# Copy configuration
COPY config.json /app/config.json

# Set environment variables
ENV GITHUB_TOKEN=${GITHUB_TOKEN}
ENV PORT=3000

# Expose port
EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000 || exit 1

# Start server
CMD ["ghstats", "serve", "--port", "3000"]

Configuration File

Create a config.json:

{
  "github": {
    "token": "${GITHUB_TOKEN}",
    "users": ["your-username"],
    "organizations": ["your-org"],
    "repositories": [
      "owner/repo1",
      "owner/repo2"
    ]
  },
  "cache": {
    "enabled": true,
    "ttl": 3600
  },
  "dashboard": {
    "title": "GitHub Statistics",
    "refresh": 3600
  }
}

Environment Variables Reference

Variable	Required	Description
GITHUB_TOKEN	Yes	GitHub Personal Access Token
PORT	No	HTTP server port (default: 3000)
CACHE_TTL	No	Cache time-to-live in seconds

Deploying ghstats on Klutch.sh

Create GitHub Personal Access Token

Generate a token with appropriate permissions:

1. Go to GitHub Settings > Developer settings
2. Select Personal access tokens > Tokens (classic)
3. Generate new token with scopes:
   • repo (for private repositories)
   • read:org (for organization stats)
   • read:user (for user profile data)

Push Your Repository to GitHub

Commit your Dockerfile and configuration to GitHub.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “ghstats” or “github-analytics”.

Create a New App

Create a new app and connect your GitHub repository.

Configure HTTP Traffic

Set up HTTP traffic:

• Select HTTP as the traffic type
• Set the internal port to 3000

Set Environment Variables

Variable	Value
GITHUB_TOKEN	Your GitHub Personal Access Token
PORT	3000

Attach Persistent Volumes

Mount Path	Size	Purpose
/app/cache	1 GB	Cached GitHub data

Deploy Your Application

Click Deploy to build and launch ghstats.

Access Your Dashboard

Navigate to your app URL to view GitHub statistics.

Dashboard Features

User Statistics

View personal GitHub metrics:

• Total contributions
• Commit history graph
• Repository ownership
• Language distribution

Repository Metrics

Analyze individual repositories:

• Star growth over time
• Fork activity
• Issue and PR statistics
• Commit frequency

Organization View

Aggregate organization statistics:

• Total repositories
• Member contributions
• Popular languages
• Activity trends

Visualization Types

Contribution Graph

Calendar heatmap showing daily commit activity, similar to GitHub’s contribution graph but with more customization options.

Language Charts

Pie or bar charts showing:

• Bytes of code per language
• Repository count per language
• Trend over time

Activity Timeline

Line graphs showing:

• Commits per week/month
• Issues opened/closed
• Pull request activity

Comparison Views

Side-by-side comparison of:

• Multiple repositories
• Time periods
• Contributors

API Rate Limits

GitHub API has rate limits:

• Authenticated: 5,000 requests/hour
• GraphQL: 5,000 points/hour

Optimizing API Usage

• Enable caching
• Use GraphQL for complex queries
• Schedule data refresh during low-usage periods

Customization

Dashboard Themes

Configure visual appearance:

• Color schemes
• Chart types
• Layout options

Metrics Selection

Choose which metrics to display:

• Star count
• Fork count
• Issue statistics
• Contributor counts

Filters

Filter data by:

• Date range
• Repository type
• Language
• Visibility (public/private)

Security Best Practices

Token Security

• Use tokens with minimal required scopes
• Rotate tokens regularly
• Never commit tokens to repositories

Access Control

• Consider authentication for dashboard access
• Limit exposed metrics for public instances

Troubleshooting

API Rate Limit Errors

• Increase cache TTL
• Reduce refresh frequency
• Check token validity

Missing Data

• Verify token has required scopes
• Check repository visibility settings
• Review API response logs

Slow Loading

• Enable caching
• Reduce number of tracked repositories
• Increase server resources

Additional Resources

• GitHub REST API Documentation
• GitHub GraphQL API
• GitHub Stats Projects

Conclusion

Deploying ghstats on Klutch.sh provides continuous visibility into your GitHub activity and project health. Whether you are an individual developer tracking contributions or a team monitoring organization-wide development, a dedicated statistics dashboard offers insights beyond GitHub’s built-in analytics.

The combination of GitHub API integration and Klutch.sh’s reliable hosting creates a powerful platform for understanding your development activity.