README.md 6.4 KB
Newer Older
1
<p align="center"><img src="https://raw.githubusercontent.com/mistermantas/cstate/master/images/highlight.png" alt="cState"></p>
Mantas's avatar
v2-dev2    
Mantas committed
2

3
<p align="center"><a href="https://github.com/mistermantas/cstate/releases"><img src="https://img.shields.io/github/release/mistermantas/cstate/all.svg?style=flat-square" alt="GitHub release" /></a> <a href="https://github.com/mistermantas/cstate/commits/master"><img src="https://img.shields.io/github/last-commit/mistermantas/cstate.svg?style=flat-square" alt="GitHub last commit" /></a> <a href="https://github.com/mistermantas/cstate/tree/master/"><img src="https://img.shields.io/github/repo-size/mistermantas/cstate.svg?style=flat-square" alt="GitHub repo size in bytes" /></a> <a href="https://gitter.im/cState/Lobby"><img src="https://img.shields.io/badge/chat-gitter-ed1965.svg?style=flat-square" alt="Gitter" /></a> <a href="https://twitter.com/mistermantas"><img src="https://img.shields.io/twitter/follow/mistermantas.svg?style=social&amp;label=Follow" alt="Twitter" /></a></p>
Mantas's avatar
v2-dev2    
Mantas committed
4

Mantas's avatar
Mantas committed
5
> Über fast, backwards compatible (IE8+), tiny, and simple status page built with Hugo. Completely free with Netlify & GitHub Pages.
6

Mantas's avatar
Mantas committed
7
[**Want an example? Click here to see a live demo!**](https://cstate-example.netlify.com)
Mantas's avatar
Mantas committed
8

Mantas's avatar
Mantas committed
9
*Looking for contributors! See Contribute section:*
10

11
## Contents
12

Mantas's avatar
Mantas committed
13
+ [Features](#features)
Mantas's avatar
Mantas committed
14
15
16
+ Getting started
  + [Production](#production)
  + [Development](#development)
Mantas's avatar
Mantas committed
17
+ [Updating](#updating)
18
+ [FAQ](#faq)
Mantas's avatar
Mantas committed
19
20
+ [Contribute](#contribute)
+ [License](#license)
21

Mantas's avatar
Mantas committed
22
23
***

Mantas's avatar
Mantas committed
24
25
## Features

26
+ Built with [Hugo](https://gohugo.io), a hyperfast Golang generator
Mantas's avatar
Mantas committed
27
+ Works not just on mobile, but also on the archaic Internet Explorer 8
28
+ Comes with a simple, focused, and extremely light design
Mantas's avatar
Mantas committed
29
30
+ Edit your status page from a simple config file
+ Comes pre-equipped with Netlify CMS for quick admin updates
31
+ Easy to edit and deploy on Netlify or GitHub Pages
Mantas's avatar
Mantas committed
32
33
34
35
36
+ Secure, ready for HTTPS, thanks to [JAMstack](https://jamstack.org/)

## Getting started

For this tutorial, it is assumed that you have Hugo and Git installed (check with `hugo version` & `git --version`).
Mantas's avatar
Mantas committed
37

Mantas's avatar
Mantas committed
38
#### Production
Mantas's avatar
Mantas committed
39

40
41
42
43
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**
Mantas's avatar
Mantas committed
44
+ Add one build environment variable
45
  + Key: **HUGO_VERSION**
Mantas's avatar
Mantas committed
46
47
48
  + Value: **0.41**

***
Mantas's avatar
Mantas committed
49

Mantas's avatar
Mantas committed
50
51
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.
Mantas's avatar
Mantas committed
52

53
```bash
Mantas's avatar
Mantas committed
54
55
mkdir themes; cd themes;
```
Mantas's avatar
Mantas committed
56

Mantas's avatar
Mantas committed
57
3. Now simply add a Git submodule pointing to this repository, like so:
58

Mantas's avatar
Mantas committed
59
60
```bash
git submodule add https://github.com/mistermantas/cstate
61
```
62

Mantas's avatar
Mantas committed
63
4. Set up cState for your liking. It is now ready to be used in production.
Mantas's avatar
Mantas committed
64
65

#### Development
66

Mantas's avatar
Mantas committed
67
1. Clone this repository in the command line:
68

Mantas's avatar
Mantas committed
69
70
71
```bash
git clone https://github.com/mistermantas/cstate.git
```
72

Mantas's avatar
Mantas committed
73
2. Go to the `exampleSite` folder, like so:
74
75

```bash
Mantas's avatar
Mantas committed
76
77
cd cstate-master/exampleSite
```
78

Mantas's avatar
Mantas committed
79
3. Uncomment this line in `config.yml`:
80

Mantas's avatar
Mantas committed
81
```yml
Mantas's avatar
Mantas committed
82
83
84
85
86
87
88
themesDir: ../..
```

4. Make sure that the folder name is the same as the `theme` value:d

```yml
theme: cstate-master
Mantas's avatar
Mantas committed
89
90
```

Mantas's avatar
Mantas committed
91
5. Then try out the site! A link to it will be shown on screen.
92

Mantas's avatar
Mantas committed
93
94
```bash
hugo serve
95
96
```

Mantas's avatar
Mantas committed
97
98
99
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.
100

101
102
## Updating

Mantas's avatar
Mantas committed
103
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, as to avoid any conflicts.
104
105

```bash
Mantas's avatar
Mantas committed
106
git submodule update
107
108
```

109
## FAQ
Mantas's avatar
Mantas committed
110

111
112
### Where do issues go? What is the frontmatter, how do I define metadata for issues?

Mantas's avatar
Mantas committed
113
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 `major-outage-east-us.md` should look like:
114
115
116

```md
---
Mantas's avatar
Mantas committed
117
118
Title: Major outage in East US
Date: 2017-02-30 14:30:00
119
Resolved: true
Mantas's avatar
Mantas committed
120
ResolvedWhen: 2017-02-30 16:00:00
121
122
Severity: down
Affected:
Mantas's avatar
Mantas committed
123
  - API
124
125
126
Section: post
---

Mantas's avatar
Mantas committed
127
*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" >}}
Mantas's avatar
Mantas committed
128

Mantas's avatar
Mantas committed
129
*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" >}}
130
131
```

132
133
134
Time to break that down.

`Title`: This is the one of the most important parts of an incident. *(required)*  
Mantas's avatar
Mantas committed
135
`Date`: An ISO-8601 formatted date. Does not include time zone. This is when you first discovered the issue. *(required)*  
136
`Resolved`: Whether issue should affect overall status. Either `true` or `false`. *(boolean, required)*  
Mantas's avatar
Mantas committed
137
`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).  
138
139
140
141
`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)*  

Mantas's avatar
Mantas committed
142
## Contribute
143

Mantas's avatar
Mantas committed
144
145
cState needs help to grow, not only would it benefit from stuff like unit tests, but also get influenced by fresh ideas to grow even further.

146
147
+ 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).
Mantas's avatar
Mantas committed
148
149
+ Write consistent, simple, readable code and precise documentation.
+ [Join the Gitter chat](http://discord.io/choraleapp) for help or discussion.
Mantas's avatar
Mantas committed
150
+ You may also the creator’s [mnts Discord](https://discord.gg/EvQZdhT).
151
152
153

## License

Mantas's avatar
Mantas committed
154
[MIT](https://github.com/mistermantas/cstate/blob/master/LICENSE.md) © Mantas Vilčinskas