README.md 10.1 KB
Newer Older
Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
1
<p align="center"><img src="images/cstate-logo-bg.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

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
5
> Über fast, backwards compatible (IE8+), tiny, and simple status page built with Hugo. Completely _free_ with Netlify and Netlify CMS.
Mantas's avatar
v2-rc1    
Mantas committed
6

Eduardo Messuti's avatar
Eduardo Messuti committed
7
8
9
10
## Sponsors 🏅

<a href="//statuspal.io"><img src="images/statuspal-logo-with-text.png" alt="Statuspal" width="200"></a>

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
11
12
13
You can also support the creator and project by **starring, sharing, and using cState**. Thank you!

[*Learn more about sponsorships*](https://github.com/sponsors/mistermantas)
Eduardo Messuti's avatar
Eduardo Messuti committed
14

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
15
16
17
18
19
## Examples 🥳

[**🎯 Click here to see the official live demo!**](https://cstate-example.netlify.com)

[👩‍💻 You can also see what an example cState project’s source code.](https://github.com/cstate/example)
Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
20
21
22
23

Some more examples from the internet:

* [Chocolatey](https://status.chocolatey.org/)
Mantas Vilčinskas's avatar
add tmw    
Mantas Vilčinskas committed
24
* [tmw.media](https://status.tmw.media)
Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
25
26
27
* [Proventa](https://status.proventa.io/) (German)
* [sr.ht](https://status.sr.ht/)
* [Content Ignite](https://status.contentignite.com/)
28
* [FSCI](https://status.fsci.in/)
Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
29
30
31

*Want your status page here? [Create a Pull Request](https://github.com/cstate/cstate/edit/dev/README.md)!*

32
## Contents ⁉
33

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
34
+ [Examples](#examples-)
35
36
+ [Features](#features-)
+ [Getting started](#getting-started-)
Mantas's avatar
Mantas committed
37
38
  + [Production](#production)
  + [Development](#development)
39
40
41
42
+ [Updating](#updating-)
+ [FAQ](#faq-)
+ [Contribute](#contribute-)
+ [License](#license-)
43

Mantas's avatar
Mantas committed
44
45
***

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
46

47
48
49
## Features 😎

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

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
51
* Automatically ships with dark mode
52
+ Comes with a simple, focused, and extremely light design
53
+ Works not just on mobile, but also on the archaic Internet Explorer 8 for some reason
54
55
+ 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
56
+ Customizable views, colors, HTML, and other elements
57

58
**Fast, reliable, and free (even to host)**
59
60

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

**Easy to setup, manage, use**

Mantas's avatar
Mantas committed
66
67
+ 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
68
+ Extensive documentation on the [wiki](https://github.com/cstate/cstate/wiki)
69
+ You can not only create issues, but also informational, about pages
Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
70
+ [Read-only API available](https://github.com/cstate/cstate/wiki/API)
Mantas's avatar
Mantas committed
71

72
## Getting started 💻
Mantas's avatar
Mantas committed
73

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
74

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

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

Mantas's avatar
Mantas committed
79
#### Production
Mantas's avatar
Mantas committed
80

81
82
83
84
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
85
+ Add one build environment variable
86
  + Key: **HUGO_VERSION**
87
  + Value: **0.48** (or later)
Mantas's avatar
Mantas committed
88

Mantas's avatar
Mantas committed
89
90
91
92
93
94
95
96
**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
97
***
Mantas's avatar
Mantas committed
98

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

Mantas's avatar
Mantas committed
101
102
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
103

104
```bash
Mantas's avatar
Mantas committed
105
106
mkdir themes; cd themes;
```
Klaus's avatar
Klaus committed
107
108
109
110
111
2. Start Git on this folder: 

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

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

Mantas's avatar
Mantas committed
115
```bash
Mantas's avatar
v2-rc1    
Mantas committed
116
git submodule add https://github.com/cstate/cstate
117
```
118

Mantas's avatar
Mantas committed
119
4. Set up cState for your liking. It is now ready to be used in production.
Mantas's avatar
Mantas committed
120
121

#### Development
122

Mantas's avatar
Mantas committed
123
1. Clone this repository in the command line:
124

Mantas's avatar
Mantas committed
125
```bash
126
git clone --recursive -b master https://github.com/cstate/cstate.git
Mantas's avatar
Mantas committed
127
```
128

Mantas's avatar
Mantas committed
129
2. Navigate to the theme directory:
130
131

```bash
132
cd cstate/exampleSite
Mantas's avatar
Mantas committed
133
```
134

Mantas's avatar
Mantas committed
135
3. Launch the development setup much like this:
136

Mantas's avatar
Mantas committed
137
```bash
138
hugo serve --baseUrl=http://localhost/ --theme=cstate --themesDir=../.. --verbose
139
140
```

Mantas's avatar
Mantas committed
141
142
143
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.
144

145
## Updating 🎉
146

147
**If you are updating from one major version to another, like from v3 to v4, then please [read the migration guides](https://github.com/cstate/cstate/wiki/Usage#migration-guides).**
148

149
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.
Mantas's avatar
Mantas committed
150

151
Ask yourself these questions:
152

153
154
155
156
157
1. Do I already have the **up to date** Git repository with my status page on my computer?
  * If not, go to your desktop or somewhere else, where you can download your Git repository and run: `git clone --recursive <your repo link goes here> && git submodule foreach git pull origin master`.
  * In the parent directory, type `hugo serve`. Check to see if everything is working.
  * Then do `git add -A; git commit -m "Update cState"; git push origin master; exit`. Your status page is now updated.
2. If you **DO** have the directory, go inside `themes/cstate`. If that is empty, it is easier to delete your local copy and do the steps outlined earlier.
Mantas's avatar
Mantas committed
158

159
There is currently no easier way to do this, unfortunately, you will need the terminal / command line / Git Bash, unless you want to create a new status page from scratch and move your data over manually.
Mantas's avatar
Mantas committed
160

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

163
## FAQ 🤔
Mantas's avatar
Mantas committed
164

165
166
167
168
### Are there settings you can change?

Yes, most of the settings are in the `config.yml` file or under _Settings_ in Netlify CMS.

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

177
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:
178
179
180

```md
---
Mantas's avatar
Mantas committed
181
182
title: Major outage in East US
date: 2017-02-30 14:30:00
SUNNY's avatar
SUNNY committed
183
resolved: true
Mantas's avatar
Mantas committed
184
185
186
resolvedWhen: 2017-02-30 16:00:00
severity: down
affected:
Mantas's avatar
Mantas committed
187
  - API
Mantas's avatar
Mantas committed
188
section: issue
189
190
---

Mantas's avatar
Mantas committed
191
*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
192

Mantas's avatar
Mantas committed
193
*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" >}}
194
195
```

196
197
Time to break that down.

Mantas's avatar
Mantas committed
198
199
200
201
202
203
204
`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)*  
205

Mantas's avatar
v2-rc1    
Mantas committed
206
207
208
209
### I have more questions!

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

210
## Contribute 💥
211

212
> Want to become a maintainer? Hit me up [on Twitter @mistermantas](https://twitter.com/mistermantas)
Mantas's avatar
Mantas committed
213

214
+ Glance over the [Code of Conduct](/CODE_OF_CONDUCT.md).
Mantas's avatar
v2-rc1    
Mantas committed
215
+ Before submitting a pull request, create an issue to [discuss the implications of your proposal](https://github.com/cstate/cstate/issues).
216
+ Or if you are a translator — [see this](https://github.com/cstate/cstate/wiki/Translations#add-your-translations).
217
+ Write consistent, simple, readable code, and precise documentation.
Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
218
+ Version numbers should be added in the JS partial, the meta[generator] tag, and API index.
219
220

## License ✍
221

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

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
224
A special thanks to all [the contributors](https://github.com/cstate/cstate/graphs/contributors)