Install & Setup

This guide will walk you through setting up your Shadow Status page from scratch.

Step 1: Get the Repository

Fork (Recommended)

Forking is the easiest way to get started and allows you to receive updates.

1. Go to the Shadow Status repository
2. Click the Fork button in the top right
3. Select your account or organization
4. Wait for the fork to complete

Use as Template

Using as a template creates a fresh repository without the commit history.

1. Go to the Shadow Status repository
2. Click Use this template > Create a new repository
3. Name your repository (e.g., status or my-status-page)
4. Choose public or private visibility
5. Click Create repository

Clone Locally

For local development and manual deployment.

git clone https://github.com/Shadow-Develops/ShadowStatus.git my-status-page
cd my-status-page
npm install

---

Step 2: Configure GitHub Secrets

Your status page needs a GitHub token to fetch issues (for incidents) and commit status updates.

Create a Personal Access Token

1. Go to GitHub Settings > Developer settings > Personal access tokens > Tokens (classic)
2. Click Generate new token > Generate new token (classic)
3. Give it a descriptive name (e.g., "Shadow Status")
4. Set expiration (or "No expiration" for convenience)
5. Select these scopes:
   • repo (Full control of private repositories) — or just public_repo if your repo is public
6. Click Generate token
7. Copy the token immediately — you won't see it again!

Add the Secret to Your Repository

1. Go to your forked/created repository
2. Navigate to Settings > Secrets and variables > Actions
3. Click New repository secret
4. Name: GIT_TOKEN
5. Value: Paste your personal access token
6. Click Add secret

Optional Secrets

You can also add these optional secrets for notifications:

• DISCORD_WEBHOOK — For Discord notifications (How to create a webhook)
• WEBHOOK_URL — For generic webhook notifications

---

Step 3: Configure Your Status Page

You'll need to edit two main configuration files:

config.json

This file controls your site's appearance and behavior. At minimum, update:

config.json

{
	"domain": "https://your-username.github.io/your-repo-name",
	"siteSettings": {
		"siteName": "Your Status Page",
		"siteDescription": "Service status for Your Company"
	},
	"github": {
		"owner": "your-username",
		"repo": "your-repo-name"
	}
}

See the Configuration guide for all available options.

monitors.json

This file defines what services to monitor. Here's a simple example:

monitors.json

{
	"groups": [
		{
			"name": "Web Services",
			"defaultOpen": true,
			"monitors": [
				{
					"name": "Main Website",
					"type": "http",
					"target": "https://example.com",
					"expectedStatus": [200]
				},
				{
					"name": "API",
					"type": "http",
					"target": "https://api.example.com/health",
					"expectedStatus": [200]
				}
			]
		}
	],
	"monitors": []
}

See the Monitors guide for all monitor types and options.

---

Step 4: Enable GitHub Pages

1. Go to your repository's Settings
2. Navigate to Pages in the sidebar
3. Under "Build and deployment":
   • Source: Select "Deploy from a branch"
   • Branch: Select gh-pages and / (root)
4. Click Save

note

The gh-pages branch is created automatically when the deploy workflow runs for the first time.

---

Step 5: Enable GitHub Actions

If Actions aren't already enabled:

1. Go to your repository's Actions tab
2. If prompted, click I understand my workflows, go ahead and enable them
3. The workflows should now be active

Trigger the First Build

The monitor checks run automatically every 30 minutes by default, but you can trigger them manually:

1. Go to Actions > Monitor Checks
2. Click Run workflow > Run workflow

Similarly, trigger the deploy:

1. Go to Actions > Deploy
2. Click Run workflow > Run workflow

---

Step 6: View Your Status Page

After the workflows complete, your status page will be available at:

https://your-username.github.io/your-repo-name/

Custom Domain

To use a custom domain:

1. Add a CNAME file to static/ with your domain (e.g., status.example.com)
2. Configure your DNS with a CNAME record pointing to your-username.github.io
3. Update the domain field in config.json

---

Step 7: Set Up 5-Minute Monitoring (Recommended)

By default, the GitHub Actions workflow runs every 30 minutes. This is because GitHub Actions scheduled workflows can be delayed during high load periods, making shorter intervals unreliable.

For more frequent monitoring, use a free external cron service like cron-job.org to trigger the workflow via GitHub's API.

Create a Fine-Grained Access Token

1. Go to GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens
2. Click Generate new token
3. Give it a name (e.g., "Status Page Cron")
4. Set Repository access to "Only select repositories" and choose your status page repo
5. Under Permissions, expand Repository permissions and set Actions to "Read and write"
6. Click Generate token and copy it

Configure cron-job.org

1. Create a free account at cron-job.org
2. Click Create cronjob and configure:

Setting	Value
Title	Status Page Monitor
URL	https://api.github.com/repos/YOUR_USERNAME/YOUR_REPO/actions/workflows/monitor-checks.yml/dispatches
Schedule	Every 5 minutes
Request Method	POST

3. Go to the Advanced tab and add these Headers:

Authorization: Bearer YOUR_GITHUB_TOKEN
Accept: application/vnd.github+v3+json
Content-Type: application/json

4. Set the Request Body:

{ "ref": "main" }

5. Click Create to save

info

The GitHub Actions workflow will continue running every 30 minutes as a fallback in case the external cron service fails.