README.md 6.53 KB
Newer Older
1
2
# cState

Mantas's avatar
Mantas committed
3
4
![Screnshot](https://raw.githubusercontent.com/mistermantas/cstate/master/images/screenshot.png)

Mantas's avatar
Mantas committed
5
[![GitHub release](https://img.shields.io/github/release/mistermantas/cstate.svg?style=flat-square)](https://github.com/mistermantas/cstate/releases) [![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/) [![Gitter](https://img.shields.io/badge/chat-gitter-ed1965.svg?style=flat-square)](https://gitter.im/cState/Lobby) [![Twitter](https://img.shields.io/twitter/follow/mistermantas.svg?style=social&label=Follow)](https://twitter.com/mistermantas)
6

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

Mantas's avatar
Mantas committed
9
10
11
*This release is a developer preview.*

[**Live demo**](https://cstate.netlify.com)
12

13
## Contents
14

Mantas's avatar
Mantas committed
15
+ [Features](#features)
Mantas's avatar
Mantas committed
16
17
18
19
+ Getting started
  + [Production](#production)
  + [Development](#development)
  + [Updating](#updating)
20
+ [FAQ](#faq)
Mantas's avatar
Mantas committed
21
22
+ [Contribute](#contribute)
+ [License](#license)
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 (with Netlify)
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
46
  + Key: **HUGO_VERSION**
  + Value: **0.31**
Mantas's avatar
Mantas committed
47

Mantas's avatar
Mantas committed
48
49
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
50

51
```bash
Mantas's avatar
Mantas committed
52
53
mkdir themes; cd themes;
```
Mantas's avatar
Mantas committed
54

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

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

Mantas's avatar
Mantas committed
61
62
63
4. Set up cState for your liking. It is now ready to be deployed

#### Development
64

Mantas's avatar
Mantas committed
65
1. Clone this repository in the command line:
66

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

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

```bash
Mantas's avatar
Mantas committed
74
75
cd cstate-master/exampleSite
```
76

Mantas's avatar
Mantas committed
77
3. Uncomment this line in `config.yml`:
78

Mantas's avatar
Mantas committed
79
80
81
82
83
```yml
# themesDir: ../..
```

3. Then try out the site! A link to it will be shown on screen.
84

Mantas's avatar
Mantas committed
85
86
```bash
hugo serve
87
88
```

Mantas's avatar
Mantas committed
89
90
91
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.
92

93
94
## Updating

Mantas's avatar
Mantas committed
95
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.
96
97

```bash
Mantas's avatar
Mantas committed
98
git submodule update
99
100
```

101
## FAQ
Mantas's avatar
Mantas committed
102

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

Mantas's avatar
Mantas committed
105
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:
106
107
108

```md
---
Mantas's avatar
Mantas committed
109
110
Title: Major outage in East US
Date: 2017-02-30 14:30:00
111
Resolved: true
Mantas's avatar
Mantas committed
112
ResolvedWhen: 2017-02-30 16:00:00
113
114
Severity: down
Affected:
Mantas's avatar
Mantas committed
115
  - API
116
117
118
Section: post
---

Mantas's avatar
Mantas committed
119
120
121
*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" >}}
122
123
```

124
125
126
Time to break that down.

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

Mantas's avatar
Mantas committed
136
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 similar.
137
138
139

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

Mantas's avatar
Mantas committed
140
Compile locally (using production instructions), commit changes, and push them out. Using [Netlify](https://www.netlify.com) is recommended as it simplifies the process.
141
142
143
144
145

### 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
146
## Contribute
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).
Mantas's avatar
Mantas committed
150
151
+ Write consistent, simple, readable code and precise documentation.
+ [Join the Gitter chat](http://discord.io/choraleapp) for help or discussion.
152
153
154

## License

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