README.md 5.51 KB
Newer Older
1
2
# cState

3
4
5
[![GitHub last commit](https://img.shields.io/github/last-commit/mistermantas/cstate.svg?style=flat-square)](https://github.com/mistermantas/cstate/commits/master)
[![GitHub repo size in bytes](https://img.shields.io/github/repo-size/mistermantas/cstate.svg?style=flat-square)](https://github.com/mistermantas/cstate/tree/master/)
[![Discord](https://img.shields.io/badge/discord-join%20chat-7289DA.svg?style=flat-square)](http://discord.io/choraleapp)  [![Twitter](https://img.shields.io/twitter/follow/mistermantas.svg?style=social&label=Follow)](https://twitter.com/mistermantas)
6

7
> The fastest and most efficient status page on the market, beating even paid solutions. cState has outstanding browser support (IE8+) and can easily be managed with GitHub Pages or Netlify. Ready for production.
8

9
[**See real-world example**](https://status.rabbitnode.com)
10

11
## Contents
12

Mantas's avatar
Mantas committed
13
+ [Features](#features)
14
15
+ [Install](#install)
+ [FAQ](#faq)
Mantas's avatar
Mantas committed
16
17
+ [Contribute](#contribute)
+ [License](#license)
18

Mantas's avatar
Mantas committed
19
20
## Features

21
22
23
24
25
26
+ Built with [Hugo](https://gohugo.io), a hyperfast Golang generator
+ Works not just on mobile browsers, but also on archaic browsers like Internet Explorer 8
+ Comes with a simple, focused, and extremely light design
+ Edit your status page just from the config file
+ Comes pre-equipped with Netlify CMS for quick updates
+ Easy to edit and deploy on Netlify or GitHub Pages
Mantas's avatar
Mantas committed
27

28
## Install
Mantas's avatar
Mantas committed
29

30
We encourage you to use [Netlify](https://www.netlify.com) for cState. The build command is `hugo` and your site is compiled to `public`.
Mantas's avatar
Mantas committed
31

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

34
**This does not seem to work in one go on PowerShell, so enter each command individually.**
Mantas's avatar
Mantas committed
35

36
```bash
37
38
# 1. First off, we initialize the Git repository
# !: If you already have one, skip this step
39
git init;
Mantas's avatar
Mantas committed
40

41
# 2. Then this creates all the necessary directories
42
mkdir -p content/issues, themes, static;
Mantas's avatar
Mantas committed
43

44
# 3. We get the config file
Mantas's avatar
Mantas committed
45
curl -o config.yml https://cdn.rawgit.com/mistermantas/cstate/master/config-example.yml;
Mantas's avatar
Mantas committed
46

47
48
# 4. Download cState
cd themes; git submodule add https://github.com/mistermantas/cstate;
49

50
# 5. Last off, start the server locally
Mantas's avatar
Mantas committed
51
cd ../; hugo serve;
52
```
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

And that is it; you have set up cState locally.

Now is a good time to make cState look the way you want it to, so upload a favicon (and logo) to `/static/`. Edit `config.yml` to fit your needs. And so on, and so forth.

**Do not change any files in the `themes` directory or its subdirectories. Everything is handled automatically by Git.**

To make the status page public, you will need to connect to a remote GitHub repository much like this:

```bash
# Create a remote origin like this (if you have not already)
git remote add origin https://github.com/username/example.git

# Add all the files
git add -A

# Then a message based on your changes
git commit -m "Testing out cState"

# All done
git push -u origin master
74
75
```

76
77
78
For an example of a working status page, see [rabbitnode/status](https://github.com/rabbitnode/status).

## FAQ
Mantas's avatar
Mantas committed
79

80
81
82
### Where do issues go? What is the frontmatter, how do I define metadata for issues?

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 `i-am-an-issue.md` should look like:
83
84
85

```md
---
86
87
88
89
90
91
92
Title: Give your issue a good title
Description: This description is here merely for metadata purposes and may show up in search results. It may be used as a summary.
Date: 2017-02-30 14:30
Resolved: true
Severity: down
Affected:
  - Client Area
93
94
95
Section: post
---

96
Content goes here.
97
98
```

99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
Time to break that down.

`Title`: This is the one of the most important parts of an incident. *(required)*  
`Description`: This description is here merely for metadata purposes and may show up in search results. It may be used as a summary.  
`Date`: An ISO-8601 formatted date. Does not include time zone. *(required)*  
`Resolved`: Whether issue should affect overall status. Either `true` or `false`. *(boolean, required)*  
`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)*  

### Is there an admin panel or some easy way to change the state of each issue?

If you use [Netlify](https://www.netlify.com), you can expect to see Netlify CMS integration very soon. Otherwise, you could fall back to [prose.io](http://prose.io) or something similiar.

### How do I make this work on GitHub Pages?

Compile locally, commit changes, and push them out. We do recommend using [Netlify](https://www.netlify.com), however.

### My question was not answered!

This part of the documentation still needs to finished. [Questions](https://github.com/mistermantas/cstate/issues) are more than welcome and you should get a pretty fast response as well.

Mantas's avatar
Mantas committed
121
## Contribute
122

123
124
125
+ Glance over the [Code of Conduct](/CODE_OF_CONDUCT.md).
+ Before submitting a pull request, create an issue to [discuss the implications of your proposal](https://github.com/mistermantas/cstate/issues).
+ Write consistent, simple, and readable code. You can [join the Chorale Discord](http://discord.io/choraleapp) to discuss in `#cstate`.
126
127
128
129

## License

MIT © Mantas Vilčinskas