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

Mantas's avatar
Mantas committed
3
<p align="center"><a href="https://github.com/cstate/cstate/releases"><img src="https://img.shields.io/github/release/cstate/cstate/all.svg?style=flat-square" alt="GitHub release" /></a> <a href="https://github.com/cstate/cstate/commits/master"><img src="https://img.shields.io/github/last-commit/cstate/cstate.svg?style=flat-square" alt="GitHub last commit" /></a> <a href="https://github.com/cstate/cstate/tree/master/"><img src="https://img.shields.io/github/repo-size/cstate/cstate.svg?style=flat-square" alt="GitHub repo size in bytes" /></a> <a href="https://discord.gg/EvQZdhT"><img src="https://img.shields.io/badge/discord-support-7289DA.svg?logo=discord&style=flat-square" alt="Discord Chat" /></a> <a href="https://twitter.com/cstate"><img src="https://img.shields.io/twitter/follow/mistermantas.svg?style=social&amp;label=Follow" alt="Twitter" /></a> <a href="https://github.com/matiassingers/awesome-readme#readme"><img src="https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg" alt="Awesome README" /></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
v2-rc1    
Mantas committed
9
10
[You can also see what an example cState project’s source code.](https://github.com/cstate/example)

Mantas's avatar
Mantas committed
11
*Looking for contributors! See Contribute section:*
12

13
## Contents
14

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

Mantas's avatar
Mantas committed
24
25
***

Mantas's avatar
Mantas committed
26
27
## Features

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

## 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
40

Mantas's avatar
Mantas committed
41
#### Production
Mantas's avatar
Mantas committed
42

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

Mantas's avatar
Mantas committed
51
52
53
54
55
56
57
58
**The easy way**

You can simply click this button to get started:

[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/cstate/example)

This sets up cState with its default settings from the cstate/example repo.

Mantas's avatar
Mantas committed
59
***
Mantas's avatar
Mantas committed
60

Mantas's avatar
Mantas committed
61
62
If you want to do this from any branch in this repository, follow the manual instructions:

Mantas's avatar
Mantas committed
63
64
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
65

66
```bash
Mantas's avatar
Mantas committed
67
68
mkdir themes; cd themes;
```
Mantas's avatar
Mantas committed
69

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

Mantas's avatar
Mantas committed
72
```bash
Mantas's avatar
v2-rc1    
Mantas committed
73
git submodule add https://github.com/cstate/cstate
74
```
75

Mantas's avatar
Mantas committed
76
4. Set up cState for your liking. It is now ready to be used in production.
Mantas's avatar
Mantas committed
77
78

#### Development
79

Mantas's avatar
Mantas committed
80
1. Clone this repository in the command line:
81

Mantas's avatar
Mantas committed
82
```bash
Mantas's avatar
v2-rc1    
Mantas committed
83
git clone https://github.com/cstate/cstate.git
Mantas's avatar
Mantas committed
84
```
85

Mantas's avatar
Mantas committed
86
2. Navigate to the theme directory:
87
88

```bash
Mantas's avatar
Mantas committed
89
cd cstate-master
Mantas's avatar
Mantas committed
90
```
91

Mantas's avatar
Mantas committed
92
3. Launch the development setup much like this:
93

Mantas's avatar
Mantas committed
94
```bash
Mantas's avatar
Mantas committed
95
hugo serve --baseUrl=/ --theme=cstate-master --themesDir=../..
96
97
```

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

102
103
## Updating

Mantas's avatar
Mantas committed
104
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.
105

Mantas's avatar
Mantas committed
106
If you already have a Git repository set up with a filled up `themes/cstate` folder, then all you need to do is this:
Mantas's avatar
Mantas committed
107

108
```bash
Mantas's avatar
Mantas committed
109
git submodule foreach git pull origin master
110
111
```

Mantas's avatar
Mantas committed
112
113
114
115
116
117
118
If you have previously used Netlfiy CMS or have made other changes without using the command line, the easiest thing to do is just clone it in a new place, change it how you want to, push those changes, and then you can safely remove the Git folder. So, do this:

```bash
git clone --recursive <your repo link goes here> && git submodule foreach git pull origin master && git push origin master
```

More info about submodules on [updating](https://stackoverflow.com/a/5828396) & [cloning](https://stackoverflow.com/questions/3796927/how-to-git-clone-including-submodules).
Mantas's avatar
Mantas committed
119

120
## FAQ
Mantas's avatar
Mantas committed
121

Mantas's avatar
Mantas committed
122
123
124
125
126
127
128
### Where do issues go?

#### Using an admin panel (Netlify CMS)

This takes a little more effort to set up but pays off in the long run — [see the wiki](https://github.com/cstate/cstate/wiki) for up to date information.

#### Doing it from the Git repository
129

Mantas's avatar
Mantas committed
130
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:
131
132
133

```md
---
Mantas's avatar
Mantas committed
134
135
136
137
138
139
title: Major outage in East US
date: 2017-02-30 14:30:00
desolved: true
resolvedWhen: 2017-02-30 16:00:00
severity: down
affected:
Mantas's avatar
Mantas committed
140
  - API
Mantas's avatar
Mantas committed
141
section: issue
142
143
---

Mantas's avatar
Mantas committed
144
*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
145

Mantas's avatar
Mantas committed
146
*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" >}}
147
148
```

149
150
Time to break that down.

Mantas's avatar
Mantas committed
151
152
153
154
155
156
157
`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)*  
158

Mantas's avatar
v2-rc1    
Mantas committed
159
160
161
162
### I have more questions!

Check out [the wiki](https://github.com/cstate/cstate/wiki).

Mantas's avatar
Mantas committed
163
## Contribute
164

Mantas's avatar
Mantas committed
165
166
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.

167
+ Glance over the [Code of Conduct](/CODE_OF_CONDUCT.md).
Mantas's avatar
v2-rc1    
Mantas committed
168
+ Before submitting a pull request, create an issue to [discuss the implications of your proposal](https://github.com/cstate/cstate/issues).
Mantas's avatar
Mantas committed
169
+ Write consistent, simple, readable code and precise documentation.
Gary Ewan Park's avatar
Gary Ewan Park committed
170
+ You may also use the mnts [Discord chat](https://discord.gg/EvQZdhT) for support.
171
172
173

## License

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