README.md 6.38 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

Mantas's avatar
Mantas committed
9
[**See real-world example**](https://rabbitnodestatus.netlify.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
31
32
33
34
35
36
We encourage you to use [Netlify](https://www.netlify.com) for cState. These are the following options you need to change in deploy settings:

+ Build command: **hugo**
+ Publish directory: **public**
+ Add one build enviroment variable
  + Key: **HUGO_VERSION**
  + Value: **0.31**
Mantas's avatar
Mantas committed
37

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

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

42
```bash
43
44
# 1. First off, we initialize the Git repository
# !: If you already have one, skip this step
45
git init;
Mantas's avatar
Mantas committed
46

47
# !: THIS ONLY WORKS ON BASH, USE THE 2ND COMMAND FOR POWERSHELL
48
# 2. Then this creates all the necessary directories
49
mkdir -p content/issues themes static;
50
mkdir -p content/issues, themes, static;
Mantas's avatar
Mantas committed
51

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

55
56
# 4. Download cState
cd themes; git submodule add https://github.com/mistermantas/cstate;
57

58
# 5. Last off, start the server locally
Mantas's avatar
Mantas committed
59
cd ../; hugo serve;
60
```
61
62
63
64
65

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.

66
**Do not change any files in the `themes` directory or its subdirectories. Everything is handled automatically by Git. If the content or static directories are empty, create at least one file in them (such as `gitkeep.txt`) to make sure Git picks them up.**
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

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
82
83
```

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

86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
## Updating

From your root directory, enter these 2 commands:

```bash
# 1. Fetch submodules
git submodule update --init --recursive;

# 2. Now pull the changes
git submodule foreach git pull origin master  
```

You may also need to update the build enviroment variable **HUGO_VERSION** if you are using Netlify to [the latest equivelant](https://github.com/gohugoio/hugo/releases).

You can [read more on git-scm.com](https://git-scm.com/book/en/v2/Git-Tools-Submodules) about submodules.

102
## FAQ
Mantas's avatar
Mantas committed
103

104
105
106
### 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:
107
108
109

```md
---
110
111
112
113
114
115
116
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
117
118
119
Section: post
---

120
Content goes here.
121
122
```

123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
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
145
## Contribute
146

147
148
149
+ 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`.
150
151
152
153

## License

MIT © Mantas Vilčinskas