README.md 9 KB
Newer Older
Mantas's avatar
Mantas committed
1
<p align="center"><img src="https://raw.githubusercontent.com/cstate/cstate/master/images/highlight.svg?sanitize=true" alt="cState example illustration"></p>
Mantas's avatar
v2-dev2    
Mantas committed
2

Casper's avatar
Casper 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/zYCjzys"><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/ivbeg/awesome-status-pages"><img src="https://cdn.rawgit.com/sindresorhus/awesome/d7305f38d29fed78fa85652e3a63e154dd8e8829/media/badge.svg" alt="Awesome status page" /></a></p>
Mantas's avatar
v2-dev2    
Mantas committed
4

5
> Über fast, backwards compatible (IE8+), tiny, and simple status page built with Hugo. Completely _free_ with Netlify & GitHub Pages.
6

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

9
[👩‍💻 You can also see what an example cState project’s source code.](https://github.com/cstate/example)
Mantas's avatar
v2-rc1    
Mantas committed
10

11
## Contents ⁉
12

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

Mantas's avatar
Mantas committed
23
24
***

25
26
27
## Features 😎

**Designed with care**
Mantas's avatar
Mantas committed
28

29
+ Comes with a simple, focused, and extremely light design
30
31
32
+ Works not just on mobile, but also on the archaic Internet Explorer 8
+ Makes you accountable, showcasing how long it took for an issue to be resolved
+ Great for data manipulation and viewing — has RSS, tag-like system feeds
33
+ Customizable views, colors, and other elements
34

35
**Fast, reliable, and free (even to host)**
36
37
38
39
40
41
42

+ Built with [Hugo](https://gohugo.io), a hyperfast Golang generator
+ Secure, ready for HTTPS, thanks to [JAMstack](https://jamstack.org/)
+ Easy to edit and deploy on Netlify for _absolutely free_

**Easy to setup, manage, use**

Mantas's avatar
Mantas committed
43
44
+ Edit your status page from a simple config file
+ Comes pre-equipped with Netlify CMS for quick admin updates
Mantas's avatar
v2-rc1    
Mantas committed
45
+ Extensive documentation on the [wiki](https://github.com/cstate/cstate/wiki)
46
+ [Read-only API available](https://github.com/cstate/cstate/wiki/API)
Mantas's avatar
Mantas committed
47

48
## Getting started 💻
Mantas's avatar
Mantas committed
49
50

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

52
53
> A minimum version of `0.48` is required for Hugo, starting with v3.

Mantas's avatar
Mantas committed
54
#### Production
Mantas's avatar
Mantas committed
55

56
57
58
59
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
60
+ Add one build environment variable
61
  + Key: **HUGO_VERSION**
62
  + Value: **0.48** (or later)
Mantas's avatar
Mantas committed
63

Mantas's avatar
Mantas committed
64
65
66
67
68
69
70
71
**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
72
***
Mantas's avatar
Mantas committed
73

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

Mantas's avatar
Mantas committed
76
77
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
78

79
```bash
Mantas's avatar
Mantas committed
80
81
mkdir themes; cd themes;
```
Klaus's avatar
Klaus committed
82
83
84
85
86
2. Start Git on this folder: 

```bash
git init
```
Mantas's avatar
Mantas committed
87

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

Mantas's avatar
Mantas committed
90
```bash
Mantas's avatar
v2-rc1    
Mantas committed
91
git submodule add https://github.com/cstate/cstate
92
```
93

Mantas's avatar
Mantas committed
94
4. Set up cState for your liking. It is now ready to be used in production.
Mantas's avatar
Mantas committed
95
96

#### Development
97

Mantas's avatar
Mantas committed
98
1. Clone this repository in the command line:
99

Mantas's avatar
Mantas committed
100
```bash
101
git clone --recursive -b master https://github.com/cstate/cstate.git
Mantas's avatar
Mantas committed
102
```
103

Mantas's avatar
Mantas committed
104
2. Navigate to the theme directory:
105
106

```bash
107
cd cstate/exampleSite
Mantas's avatar
Mantas committed
108
```
109

Mantas's avatar
Mantas committed
110
3. Launch the development setup much like this:
111

Mantas's avatar
Mantas committed
112
```bash
113
hugo serve --baseUrl=http://localhost/ --theme=cstate --themesDir=../.. --verbose
114
115
```

Mantas's avatar
Mantas committed
116
117
118
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.
119

120
## Updating 🎉
121

Mantas's avatar
Mantas committed
122
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.
123

Mantas's avatar
Mantas committed
124
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
125

126
```bash
Mantas's avatar
Mantas committed
127
git submodule foreach git pull origin master
128
129
```

Mantas's avatar
Mantas committed
130
131
132
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
Mantas's avatar
Mantas committed
133
git clone --recursive <your repo link goes here> && git submodule foreach git pull origin master
Mantas's avatar
Mantas committed
134
135
136
```

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
137

138
## FAQ 🤔
Mantas's avatar
Mantas committed
139

Mantas's avatar
Mantas committed
140
141
142
143
144
145
146
### 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
147

148
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 `2017-02-30-major-outage-east-us.md` should look like:
149
150
151

```md
---
Mantas's avatar
Mantas committed
152
153
title: Major outage in East US
date: 2017-02-30 14:30:00
SUNNY's avatar
SUNNY committed
154
resolved: true
Mantas's avatar
Mantas committed
155
156
157
resolvedWhen: 2017-02-30 16:00:00
severity: down
affected:
Mantas's avatar
Mantas committed
158
  - API
Mantas's avatar
Mantas committed
159
section: issue
160
161
---

Mantas's avatar
Mantas committed
162
*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
163

Mantas's avatar
Mantas committed
164
*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" >}}
165
166
```

167
168
Time to break that down.

Mantas's avatar
Mantas committed
169
170
171
172
173
174
175
`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)*  
176

Mantas's avatar
v2-rc1    
Mantas committed
177
178
179
180
### I have more questions!

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

Mantas's avatar
Mantas committed
181
182
183
184
185
186
187
188
189
## Donate ❤️

cState is only a hobby project of @mistermantas, but it’s a prideful one.

Support the developer and ensure the future of the project by donating for a cuppa tea, some ice cream, or if you are feeling generous — a large size pizza.

* [PayPal](https://paypal.me/AlbinaV}
* or you can make a bank transfer. For info, [get in touch](https://mnts.lt)

190
## Contribute 💥
191

192
> Want to become a maintainer? Hit me up! [@mistermantas](https://twitter.com/mistermantas)
Mantas's avatar
Mantas committed
193

194
+ Glance over the [Code of Conduct](/CODE_OF_CONDUCT.md).
Mantas's avatar
v2-rc1    
Mantas committed
195
+ Before submitting a pull request, create an issue to [discuss the implications of your proposal](https://github.com/cstate/cstate/issues).
196
+ Or if you are a translator — [see this](https://github.com/cstate/cstate/wiki/Translations#add-your-translations).
Mantas's avatar
Mantas committed
197
+ Write consistent, simple, readable code and precise documentation.
198
199
200
+ Version numbers should be added in JS partial & meta generator tags!

## License ✍
201

202
[MIT](https://github.com/cstate/cstate/blob/master/LICENSE.md) © [Mantas Vilčinskas](https://github.com/mistermantas)
203

204
Thanks to all the [contributors](https://github.com/cstate/cstate/graphs/contributors)!