Installation & Deployment

You can deploy GitHub Bubble Chart on Vercel or any other platform that supports Node.js applications.

Common Requirements

Prerequisites

• Node.js 18 or higher (download)
• Yarn 1.22 or higher (installation guide)
• GitHub account and a personal access token
• Git installed on your machine (for development/deployment from source)

Environment Variables

All deployments require the following environment variables:

Variable	Description	Default	Required
GITHUB_TOKEN	Your GitHub personal access token	-	Yes
PORT	Server port number	9000	No
CACHE_MAX_AGE	Cache duration in seconds for generated SVGs	14400 (4 hours)	No
DEFAULT_GITHUB_RETRY_DELAY	Delay between GitHub API retry attempts (ms)	1000	No
DEFAULT_GITHUB_MAX_RETRY	Maximum number of GitHub API retry attempts	3	No
LANGUAGE_MAPPINGS_URL	Base URL for language mappings file	Repository main branch URL	No
NODE_ENV	Node environment (dev or prod)	prod for deployments	No

Note

While only GITHUB_TOKEN is strictly required, setting appropriate values for the other variables is recommended for optimal performance.

Standard Deployment Steps

1. Fork/Clone the Repository – Create your own copy of the code
2. Install Dependencies – Run yarn install
3. Build the Project – Run yarn build
4. Set Environment Variables – Configure your GitHub token and other variables
5. Start the Application – Run yarn start or use platform-specific commands

Deploy on Vercel (Recommended)

🔧 Step-by-step guide for Vercel deployment

1. Fork the Repository – First, fork the GitHub repository to your own account.
2. Go to vercel.com – Create an account or sign in.
3. Sign in with GitHub – Click on Log in and then Continue with GitHub.
4. Allow Access – Sign in to GitHub and allow access to repositories if prompted.
5. Import Your Project –
   • Go to Vercel Dashboard
   • Click "Add New..." and select "Project"
   • Select your forked repository
6. Create a GitHub Personal Access Token –
   • Go to GitHub Settings > Developer settings > Personal access tokens
   • Click "Generate new token"
   • Give it a descriptive name
   • Select the repo scope to access private repositories
   • Click "Generate token" and copy the token value
7. Configure Environment Variables – Add all required environment variables from the table above
8. Deploy – Click "Deploy" and get your live API URL.

🎉 Your GitHub Bubble Chart is now live and ready to use with both public AND private repositories!

Rate Limiting Considerations

Since the GitHub API has rate limits (5,000 requests per hour for authenticated requests), consider the following:

• By hosting your own instance with your personal token, you'll have your own rate limit quota
• You can adjust the cache duration in the environment variables (adjust CACHE_MAX_AGE)

Keep Your Fork Updated

To ensure your deployment has the latest features and bug fixes:

• Use GitHub's Sync Fork button to keep your fork updated
• Alternatively, you can use automated tools like pull to automate this process

Deploy on Other Platforms

GitHub Bubble Chart can be deployed on various platforms that support Node.js applications. Follow the standard deployment steps above, along with this generic guide:

General Deployment Guide

For any Node.js-compatible platform, follow these universal steps:

1. Prepare Your Environment

   • Ensure the platform supports Node.js 18+
   • Check if the platform allows setting environment variables
   • Verify that the platform can expose HTTP ports for your service

2. Deploy Your Application

   • Upload your codebase (via Git, direct upload, or other methods)
   • Configure the build command: yarn build
   • Set the start command: node dist/api/index.js or yarn start
   • Configure the port according to platform requirements (some platforms use their own environment variables like $PORT)

3. Configure Environment Variables

   • Add all the required environment variables from the table above
   • Some platforms may require specific format or configuration files
   • For containerized deployments, include variables in your container configuration

4. Monitoring and Scaling

   • Set up monitoring for your application if available
   • Configure auto-scaling if needed for high-traffic deployments
   • Consider adjusting CACHE_MAX_AGE for busy deployments

5. Troubleshooting

   • Check application logs for any errors
   • Verify GitHub token permissions if API calls fail
   • Ensure the application has network access to GitHub's API servers

Tip

For any deployment platform, the key requirements are Node.js 18+ support, ability to set environment variables, and HTTP port exposure.

Local Development

For setting up the project for local development and contributing, please see the Local Development wiki page.