Original post

cState example illustration

GitHub release GitHub last commit GitHub repo size in bytes Discord Chat Twitter Awesome status page

Über fast, backwards compatible (IE8+), tiny, and simple status page built with Hugo. Completely free with Netlify, Netlify CMS.

🎯 Want an example? Click here to see a live demo!

👩‍💻 You can also see what an example cState project’s source code.

Sponsors 🏅

Statuspal

Who uses cState? 🥳

Some more examples from the internet:

Want your status page here? Create a Pull Request!

Contents ⁉


Features 😎

Designed with care

  • New in v4: automatically ships with dark mode
  • Comes with a simple, focused, and extremely light design
  • Works not just on mobile, but also on the archaic Internet Explorer 8 for some reason
  • Makes you accountable, showcasing how long it took for an issue to be resolved
  • Great for data manipulation and viewing — has RSS, tag-like system feeds
  • Customizable views, colors, HTML, and other elements

Fast, reliable, and free (even to host)

  • Built with Hugo, a hyperfast Golang generator
  • Secure, ready for HTTPS; see JAMstack
  • Easy to edit and deploy on Netlify for absolutely free

Easy to setup, manage, use

  • Edit your status page from a simple config file
  • Comes pre-equipped with Netlify CMS for quick admin updates
  • Extensive documentation on the wiki
  • You can not only create issues, but also informational, about pages
  • New in v4: Read-only API available

Getting started 💻

For this tutorial, it is assumed that you have Hugo and Git installed (check with hugo version & git --version).

A minimum version of 0.48 is required for Hugo, starting with v3.

Production

We encourage you to use Netlify for cState. These are the following options you need to change in deploy settings:

  • Build command: hugo
  • Publish directory: public
  • Add one build environment variable
    • Key: HUGO_VERSION
    • Value: 0.48 (or later)

The easy way

You can simply click this button to get started:

Deploy to Netlify

This sets up cState with its default settings from the cstate/example repo.


If you want to do this from any branch in this repository, follow the manual instructions:

  1. Download the contents of the exampleSite directory in this repository. This will be your site guts, which will hold the content and configuration for the status page.
  2. Create a themes folder and navigate to it on the command line.
mkdir themes; cd themes;
  1. Start Git on this folder:
  1. Now simply add a Git submodule pointing to this repository, like so:
git submodule add https://github.com/cstate/cstate
  1. Set up cState for your liking. It is now ready to be used in production.

Development

  1. Clone this repository in the command line:
git clone --recursive -b master https://github.com/cstate/cstate.git
  1. Navigate to the theme directory:
cd cstate/exampleSite
  1. Launch the development setup much like this:
hugo serve --baseUrl=http://localhost/ --theme=cstate --themesDir=../.. --verbose

The main directory is the theme itself (the cState guts, basically) and the exampleSite folder houses all content. Use this local setup to experiment before deploying to production!

If you would like to commit/make a PR, make sure that themesDir is a comment before trying to merge upstream.

Updating 🎉

If you are updating from one major version to another, like from v3 to v4, then please read the migration guides.

Assuming the production install instructions were followed, keep cState updated by having an up to date Git submodule in the themes folder. containing this repository. Your content will stay separate.

Ask yourself these questions:

  1. Do I already have the up to date Git repository with my status page on my computer?
  • If not, go to your desktop or somewhere else, where you can download your Git repository and run: git clone --recursive <your repo link goes here> && git submodule foreach git pull origin master.
  • In the parent directory, type hugo serve. Check to see if everything is working.
  • Then do git add -A; git commit -m "Update cState"; git push origin master; exit. Your status page is now updated.
  1. If you DO have the directory, go inside themes/cstate. If that is empty, it is easier to delete your local copy and do the steps outlined earlier.

There is currently no easier way to do this, unfortunately, you will need the terminal / command line / Git Bash, unless you want to create a new status page from scratch and move your data over manually.

More info about submodules: updating & cloning.

FAQ 🤔

Are there settings you can change?

Yes, most of the settings are in the config.yml file or under Settings in Netlify CMS.

Where do issues go?

Using an admin panel (Netlify CMS)

This takes a little more effort to set up but pays off in the long run — see the wiki for up to date information.

Doing it from the Git repository

Create a file in content/issues. The name of the file will be the slug (what shows up in the URL bar). For example, this is what 2017-02-30-major-outage-east-us.md should look like:

---
title: Major outage in East US
date: 2017-02-30 14:30:00
resolved: true
resolvedWhen: 2017-02-30 16:00:00
severity: down
affected:
  - API
section: issue
---

*Monitoring* - After hitting the ole reboot button Example Chat App is now recovering. We’re going to continue to monitor as everyone reconnects. {{< track "2018-04-13 16:50:00" >}}

*Investigating* - We’re aware of users experiencing unavailable guilds and issues when attempting to connect. We're currently investigating. {{< track "2018-04-13 15:54:00" >}}

Time to break that down.

title: This is the one of the most important parts of an incident. (required)
date: An ISO-8601 formatted date. Does not include time zone. This is when you first discovered the issue. (required)
resolved: Whether issue should affect overall status. Either true or false. (boolean, required)
resolvedWhen: An ISO-8601 formatted date. Does not include time zone. This is when downtime stopped. You may set the time that downtime ended without completely resolving the issue (thus leaving time for monitoring).
severity: If an issue is not resolved, it will have an applied severity. There are 3 levels of severity: notice, disrupted, and down. If there are multiple issues, the status page will take the appearance of the more drastic issue (such as disrupted instead of notice). (required)
affected. Add the items that were present in the config file which should alter the status of each individual system (component). (array, required)
section. This must be issue, so that Hugo treats it as one. (required)

I have more questions!

Check out the wiki.

Support ❤️

cState is only a hobby project of @mistermantas, but it has turned into something a little bit bigger.

Please star, share, and use the software. Thank you, if you do.

If you wish to support the project financially:

Sponsor the author @mistermantas on GitHub

Support the author on PayPal

Contribute 💥

Want to become a maintainer? Hit me up on Twitter @mistermantas

  • Glance over the Code of Conduct.
  • Before submitting a pull request, create an issue to discuss the implications of your proposal.
  • Or if you are a translator — see this.
  • Write consistent, simple, readable code, and precise documentation.
  • Version numbers should be added in the JS partial, the meta[generator] tag, and API index!

License ✍

MIT © Mantas Vilčinskas

Thanks to all the contributors!