cState is a powerful status page software. Here is how you can use it.

The README has information on how to set up and upgrade your instance of cState.

For this tutorial, it assumed that you have set up your site like this:

content/
  issues/
    test-issue.md
  pages/
    example-page.md
layouts/
static/
  logo.png
themes/
  cstate/
    ...
config.yml

The cState core is housed under the cstate/ directory and synced with this repository.

Not using the latest version but want to update? Look at the migration guides here.

The config.yml is just a text document like any other and it follows the standard YAML rules.

The configuration file hosts most of the options you will want to change on your status page.

In the content/pages folder, you can add a page like any other. It will not be related or connected to the issues. This is good for things like About pages. Here is what content/pages/example-page.md looks like:

—
title: Example Page
description: This is an example page that demonstrates the capabilities of a Markdown page in cState.
—

Title here!
===========

This is an example page that demonstrates the capabilities of a Markdown page in cState.

You can use HTML if the file extension is `.html`, but this example one is `.md`.

Netlify CMS has a tab for creating and editing Pages.

Incidents are simply Markdown files (like test-issue.md) that are under content/issues/. They are formatted in such a way that cState can recognize the inputted data and generate your status page appropriately.

If you want to simply try out cState as easily and quickly as possibly, simply edit the files under /content/

What's fun is this means cState is easily hackable and portable:

• you can edit files on your own computer as with any text file on any IDE
• you can edit on GitHub.com, GitLab.com, or similar hosted platforms
• you can even use codespaces and VS Code online

So, if you want to add a new issue, you will create a file such as major-us-east-outage.md then set it up with the right data, like this:

—
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)
informational. Makes issue look more like a blog post and removes any references to downtime length. (boolean, v4 onwards)
automated. Starting v6 issues can be marked as automatically created by a bot.

You may have also noticed that all this data is encapsulated within the bounds of three dashes ---. Underneath that is some space for Markdown-formatted text. This is where you can detail the issue at hand and update your users on the status of the issue.

Apart from obvious Markdown formatting (like *italic*, **bold**), you can also embed dates using this shortcode: {{< track "2018-04-13 15:54:00" >}}`. That is an ISO 8601 date. Keep in mind that you must define seconds.

cstate-cli is here to make managing your cState status page a breeze! 🚀

With cState v6, cstate-cli, a command-line tool designed to simplify creating and managing content for your cState status pages, is now also live.

What it does:

• ⚡️ cstate create: Interactively create new incident or informational posts.
• 📝 cstate draft: Quickly draft posts from templates (Incident Post, Maintenance, Experiment, Postmortem).
• 💻 cstate dev: Run a local Hugo development server.
• 🔨 cstate serve & cstate build: Handy aliases for Hugo's serve and build commands.

Why you'll love it:

• Saves time: Automates tedious tasks.
• Reduces errors: Ensures consistent formatting.
• Improves workflow: Streamlines content creation.

Get started:

# Install globally
npm install -g cstate-cli

# Or use with npx
npx cstate-cli <command>

Example:

cstate draft

This will prompt you to choose a template and guide you through creating a new post.

Check out the full documentation and usage instructions in the repo README here.

Web UI options

All that may seem daunting, as it requires you to push the changed Git repository to GitHub, GitLab, or whatever else you are using.

With tools that provide a CMS-like UI, creating issues can be less of a pain. There is more setup however.

Forestry is a great alternative to Netlify CMS as it offers a much smoother UI and login experience. It is not completely free, however.

Read more about setup here and contact Forestry for support; as of v5 cState does not officially have default Forestry CMS files, but it works absolutely fine if you edit the fields you wish to use!

This method may no longer work. It is deprecated starting v6.

1. Deploy cState on Netlify as per the production instructions on the README.
2. Enable Identity.
3. Make sure Invite only is checked in Identity's settings. (Unless you need more than 5 people on the free plan, see note 1.)
4. Enable Git Gateway and generate an access token for your cState repo. (You might want to enable SSO login, like with GitHub or Google, see note 2.)
5. Go back to the main Identity screen and click Invite users. Send yourself an email.
6. From here on out, you should get a link like this: https://status.example.com/#invite_token=AKdyV8eXVInNXaWQ5mq1v6. While later versions automatically redirect you with this link, if you have JavaScript turned off, or are using an older version, or the link just doesn't work, add /admin/ so that it looks like this: https://status.example.com/admin/#invite_token=AKdyV8eXVInNXaWQ5mq1v6 Now — setup your account!

This is it — the next time you go to /admin, you’ll be able to create / manage issues.

💡 As discussed in issue #62, email templates cannot be overriden by default. However, if in the Netlify Identity UI, you set the email templates to point to netlify/confirmation.html, netlify/recovery.html, netlify/change.html, and netlify/invite.html, all new users will receive the correct link every time, with JavaScript enabled or disabled. But Netlify CMS only works with JavaScript, so. Just a footnote.

1. The default version of Identity supports 5 invite only admins. This might not be enough — you can choose to allow anyone to sign up and restrict people by roles. So, if you want 10 admins, you can choose to setup an Admin role and give it out that way. The obvious downside of this is that anyone can sign up by going to /admin, albeit without any permissions. You may also consider paying to Netlify for Identity’s services to up your member quota.
2. It’s also worth mentioning that Netlify Identity, at the time of writing, supports single sign on for quick logins with services like GitLab, GitHub, BitBucket, and even Google. SSO is typically easier to set up than an email and password.

You can try the official cState Monitor Bot to setup automatic incident creation if a monitor returns the wrong value (e.g. if a server goes down, or throws 500 errors instead of 200 OK on a GET request). Check the repository for setup instructions.

cState does not have monitoring built-in. It can't, cState is built statically first. But starting with v6, an uptime histogram is now shown, showing daily uptime. And this histogram can be edited through the already existing incident/issue system automatically.

You may use a free service such as Uptime Robot to track uptime separately and link to 3rd party monitoring tools with custom tabs.

If you use another monitoring tool that has a small embed, you can also use custom HTML partials on the systems to add monitoring right under the title of the component.

Informational posts were introduced in v4.

In v5.2, they can be pinned if you want to announce upcoming maintenance without changing status.

Informational pages need a title, date, a section: issue definition, and a boolean of informational: true and/or pin: true boolean in the frontmatter.

---
title: Maintenance on Feb 30
date: 2017-02-30 14:30:00 
informational: true
pin: true
---

Hello, this is an informational post that everyone can see at the top.

How can I see what version of cState I have?

Starting with v3, the version is displayed in the web developer tools, specifically the console (if you have JavaScript on). You can see that by pressing F12, or Ctrl+Shift+I, or right clicking and clicking Inspect Element. For those without access to JavaScript, you can view the source of the homepage — the version should be displayed in the meta[generator] head tag. Ctrl+F "generator" or "cState" and you should find the version there. In addition, with v4 you can also see the version from the API index which is easy to access with a link from anywhere, even mobile.

See here

See here

🚸 We always recommend making a backup. You are probably using GitHub, which is in its own a sort of backup system, but for your sanity a backup might help, especially if you are a beginner.

1. Update cState like normal. Basically, the themes/cstate directory where the cState submodule is, should be up to date.
2. UPDATE YOUR config.yml ACCORDINGLY OR CSTATE WILL NOT WORK AS EXPECTED.

• Colors in your config.yml should now have the # mark. Read more

Example:

params:
  brand: "#0a0c0f"
  ok: "#008000"
  disrupted: "#cc4400"
  down: "#e60000"
  notice: "#24478f"

• Every system/component must have a category now, regardless whether or not you want them.
  • Click here, if you want to use categories.
  • If you do not need them, for each system/component add category: Uncategorized, and add this bit of code to your config.yml file:

params:
  categories:     
    - name: Uncategorized
      untitled: true

The end result looks like this:

params:
  categories:
    - name: Uncategorized
      untitled: true
  systems:
    - name: Website
      category: Uncategorized

• To enable the API, add:

outputs:
  page:
    - html
    - json
  section:
    - html
    - json
    - rss
  home:
    - html
    - json
    - rss

Remember: cState is static, so the API is read-only. Nobody can push unwanted changes to your status page.

3. Consider whether you want to enable or disable any of the new features, such as: dark mode, archival type incident history views, informational posts.
4. Try serving your page locally with hugo serve.
5. If everything works, push the changes to your Git server (probably GitHub): git add -A; git commit -m "Update cState"; git push origin master; exit.

⚠ The minimum Hugo version is now 0.48. A new version of Go brings variable overwrites, which may be used in parts of cState in the future.

1. Update cState like normal.
2. Make sure your baseURL is NOT A SLASH IN A PRODUCTION. Moving forward, if the baseURL is not properly defined, RSS and other functionality may not be supported, as well as cause unexpected behavior.
3. Add some values to your config.yml file to enable new functionality and ensure compatability:

Add defaultContentLanguage & preserveTaxonomyNames to the very bottom of the config file as well as a taxonomies object:

defaultContentLanguage: en

preserveTaxonomyNames: true

taxonomies:
  affected: affected