README.md 17.3 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

Mantas Vilčinskas's avatar
Mantas Vilčinskas 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://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. Comes with Netlify CMS, read-only API, and other useful features.
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>

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

[*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
## Examples 🥳

17
### Official
Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
18

19
20
* [**Example site — cstate.mnts.lt**](https://cstate.mnts.lt)
* [Source code of the example cState site](https://github.com/cstate/example)
Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
21

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
22
23
*Thank you to [Netlify](https://www.netlify.com) for hosting our demo websites!*

24
### More examples from the internet
Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
25
26

* [Chocolatey](https://status.chocolatey.org/)
Mantas Vilčinskas's avatar
add tmw    
Mantas Vilčinskas committed
27
* [tmw.media](https://status.tmw.media)
Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
28
29
30
* [Proventa](https://status.proventa.io/) (German)
* [sr.ht](https://status.sr.ht/)
* [Content Ignite](https://status.contentignite.com/)
31
* [FSCI](https://status.fsci.in/)
32
* [Storehouse](https://status.sthse.co)
HyRo's avatar
HyRo committed
33
* [Hyrousek](https://status.hyrousek.tk)
Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
34

35
*Want your status page here? [Create a PR](https://github.com/cstate/cstate/edit/dev/README.md)!*
Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
36

37
## Contents 🔍
38

39
+ [Sponsors](#sponsors-)
Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
40
+ [Examples](#examples-)
41
42
43
44
45
46
+ [Features](#features-)
+ [Getting started](#getting-started-)
+ [Updating](#updating-)
+ [FAQ](#faq-)
+ [Contribute](#contribute-)
+ [License](#license-)
47

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

49
50
## Features 😎

51
52
53
### Purpose / how it works

You can think of the cState status page as an informational hub. Because the software is static, it cannot directly monitor any services in real time.
Mantas's avatar
Mantas committed
54

55
However, cState is a perfect option for recording incidents because most of the time your services are functioning, so the status page does not need to be updated. By default, the little bit of JavaScript on the page improves the user experience but is not required to see the most vital information.
56

57
There are other commercial options that may update faster because of their architecture, have built-in real-time uptime monitoring, send notifications by email or other means, but cState is not supposed to be better than paid solutions, but _good enough_.
58

59
### List of possibilities
60

61
62
**Please note that with all that cState _can_ do, it cannot do automatic monitoring. [See this thread](https://github.com/cstate/cstate/issues/124)**

63
64
65
66
67
68
69
70
71
| **cState is designed with care**                                                                                         	| **Fast, reliable, and free (even with host)**                                                                            	| **Easy to setup, manage, use**                                                                                                                           	|
|--------------------------------------------------------------------------------------------------------------------------	|--------------------------------------------------------------------------------------------------------------------------	|----------------------------------------------------------------------------------------------------------------------------------------------------------	|
| A simple and focused user interface & experience with [instant loading](https://github.com/cstate/cstate/issues/117), suitable for any brand                            	| Built with [Hugo](https://gohugo.io), a hyperfast Golang static site generator (SSG)                                     	| As easy as WordPress: if you don't like getting into the code, try Netlify CMS                                                                           	|
| cState switches to dark mode automatically, [if told so by your OS and browser settings](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme)                                   	| Use the full power of Hugo — flavored Markdown, shortcodes, templates, and more                                          	| Most of the settings are in the `config.yml` file or under _Settings_ in Netlify CMS                                                                           	|
| Statistical calculations show the key take-away (e.g., time spent fixing an issue)                                       	| Airtight back-end security because cState is built on the [JAMstack](https://jamstack.org/)                              	| Create systems, categories for recording incidents (or even [informational posts](https://github.com/cstate/cstate/releases/tag/v4.0.0) and pages)                                                               	|
| Great for data manipulation and viewing — cState has RSS, tag-like system feeds                                          	| HTTPS, domain linking, easy setup & high performance with [Netlify & Netlify CMS](#getting-started-)*absolutely free* 	| Built-in [language files/translations](https://github.com/cstate/cstate/wiki/Translations#available-translations) for English, German, French, Turkish, and Lithuanian                                                                	|
| Easy [linking to 3rd parties](https://github.com/cstate/cstate/wiki/Customization#tabs), customizable views, colors, HTML, and assets                                                	| You can also use many of the advanced features on platforms such as GitLab Pages & others that support Hugo              	| Extensive documentation on the [wiki](https://github.com/cstate/cstate/wiki)                                                                             	|
| Very little JavaScript. Responsive CSS that is backwards compatible up to Internet Explorer 8                                                    	| Create your own workflow — cState generates static files that can be hosted literally anywhere (CDN, AWS, GitHub Pages)  	| Feel free to [create an issue](https://github.com/cstate/cstate/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc) if you have any questions or feedback 	|
| [Badges for showing the status on other websites (similiar to shields.io)](https://github.com/cstate/cstate/wiki/Badges) 	| [Read-only API available for even further integration](https://github.com/cstate/cstate/wiki/API)                        	| cState is always improving and the user community is only growing — [you're with good company](#sponsors-)                                                             	|
72

Mantas's avatar
Mantas committed
73

74
## Getting started 💻
Mantas's avatar
Mantas committed
75

76
This is how you create a **new site powered by cState.**  What you are generating is a Hugo site with specific, already existing modifications (to Hugo, cState is a theme).
Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
77
 
Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
78

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
79
### 💚 Netlify and Netlify CMS
80

81
cState was built to work best with Netlify and comes with the neccesary files to enable Netlify CMS.
Mantas's avatar
Mantas committed
82

83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
You don't have to use Netlify, but this is the best all-around option:

- To get you started, Netlify is **completely free** (you can pay for extra features, bandwidth, etc)
- It supports all the features you'd want for hosting a modern website: **HTTPS, domain linking, worldwide asset serving, rollbacks, and more**
- As you'd expect, **Netlify CMS** works best with Netlify. **It takss just a few clicks** to make it work


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 [the example repository](https://github.com/cstate/example) repo.

If you cloned the example repository and want to use that newly forked repo, click the 'New site from Git' button in the user dashboard.

These are the settings you should be using:
99
100
101

+ Build command: **hugo**
+ Publish directory: **public**
Mantas's avatar
Mantas committed
102
+ Add one build environment variable
103
  + Key: **HUGO_VERSION**
Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
104
105
  + Value: **0.80** (or later)
+ Also **for the Build image selection, pick Ubuntu Xenial 16.04 or later**
Mantas's avatar
Mantas committed
106

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
107
### 🧡 Other great hosting and CMS options
Mantas's avatar
Mantas committed
108

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
109
The most popular options, apart from Netlify's offers, are:
Mantas's avatar
Mantas committed
110

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
111
112
113
114
115
116
117
118
* **Hosting:**
    * GitHub Pages
    * GitLab Pages
    * CloudFlare Pages
    * Vercel
* **Admin panels / CMS:**
    * Forestry.io
    * Or just use your Git provider (github.com, gitlab.com, etc)
Mantas's avatar
Mantas committed
119

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
120
You can also look at [other headless CMS options **(we use Git-based CMS types)** on jamstack.org](https://jamstack.org/headless-cms/).
121

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
122
### GitLab Pages
123

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
124
Here is a [good guide for getting started with the service.](https://docs.gitlab.com/ee/user/project/pages/#getting-started)
125

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
126
**In short: a `.gitlab-ci.yml` file** is responsible for making cState work. As of v4.2.1, the [cState automatically ships with this file](https://github.com/cstate/cstate/releases/tag/v4.2.1), but support is still experimental.
127

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
128
As of this time, this is a relatively untested option, but Hugo does seem to generate the right things (this can be checked by downloading the **CI/CD artificats**).
129

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
130
According to GitLab, it may take up to 30 minutes before the site is available after the first deployment.
131

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
132
You can [make Netlify CMS work on GitLab](https://www.netlifycms.org/docs/gitlab-backend/), but that requires overriding an existing file in the theme. Create a file in `static/admin/config.yml` and follow the instructions linked earlier. (cState by default ships with Git Gateway for Netlify.)
133

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
134
### GitHub Pages, CloudFlare Pages, Vercel, Forestry, and others
135

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
136
There is no official, separate documentation for these, but if you look below to see how to deploy manually, the instructions will be the same everywhere.
137

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
138
### Doing it on your PC
139

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
140
Keep reading to see how to deploy manually. Developers wishing to contribute, scroll to the very bottom.
141

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
142
### Manual builds
143
144
145

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

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
146
> A minimum version of `0.80` is required for Hugo, starting with v5.
Mantas's avatar
Mantas committed
147

148
#### I want to use my site in production
Mantas's avatar
Mantas committed
149

150
[Clone the example repository](https://github.com/cstate/example):
Mantas's avatar
Mantas committed
151

152
```bash
153
git clone --recursive -b master https://github.com/cstate/example.git
Mantas's avatar
Mantas committed
154
```
155
156
157
158

(We are using `--recursive` because the site will not generate with an empty `themes/cstate` folder.)

Now you can edit what's inside the folder (`example`) and try previewing that with this command:
Klaus's avatar
Klaus committed
159
160

```bash
161
hugo serve
Klaus's avatar
Klaus committed
162
```
Mantas's avatar
Mantas committed
163

164
Once the changes you wanted done are finished, generate the final files like this:
165

166
167
```
hugo
168
```
169

170
And the folder `public` can now be hosted.
Mantas's avatar
Mantas committed
171

172
173
The downside with manual building is that, if you do not want to use a solution like GitLab Pages or Netlify, this process will need to happen on your computer. This can be tedious.

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
174
175
176
177
178
179
### — Docker —

cState comes with a Dockerfile and Netlify ([according to their article from 2016](https://www.netlify.com/blog/2016/10/18/how-our-build-bots-build-sites/)) uses a similar Docker system to build cState. This is an option for people who prefer Docker and NGINX instead of serverless, but serverless still has the priority in our development. 

[Read wiki](https://github.com/cstate/cstate/wiki/Docker)

180
## Updating 🎉
181

182
**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).**
183

184
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 should stay separate from the guts of cState.**
Mantas's avatar
Mantas committed
185

186
Ask yourself these questions:
187

188
189
190
191
192
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
193

194
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
195

196
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
197

198
## FAQ 🤔
Mantas's avatar
Mantas committed
199

200
### What should be the first thing I do after downloading the example repository? What do I edit?
201

202
Most of the settings are in the `config.yml` file or under _Settings_, if you have set up Netlify CMS.
203

204
### How do I create issues?
Mantas's avatar
Mantas committed
205
206
207
208
209
210

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

212
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:
213
214
215

```md
---
Mantas's avatar
Mantas committed
216
217
title: Major outage in East US
date: 2017-02-30 14:30:00
SUNNY's avatar
SUNNY committed
218
resolved: true
Mantas's avatar
Mantas committed
219
220
221
resolvedWhen: 2017-02-30 16:00:00
severity: down
affected:
Mantas's avatar
Mantas committed
222
  - API
Mantas's avatar
Mantas committed
223
section: issue
224
225
---

Mantas's avatar
Mantas committed
226
*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
227

Mantas's avatar
Mantas committed
228
*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" >}}
229
230
```

231
232
This is what you would see for an issue that has been resolved.

233
234
Time to break that down.

Mantas's avatar
Mantas committed
235
236
237
238
239
240
241
`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)*  
242

243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
You don't have to define a date for `resolvedWhen` when the issue is not resolved (obviously):

```md
---
title: Major outage in East US
date: 2017-02-30 14:30:00
resolved: false
severity: down
affected:
  - API
section: issue
---

We are looking into this...
```

### Is that it?

For this very basic tutorial, yes.

Mantas's avatar
v2-rc1    
Mantas committed
263
264
265
266
### I have more questions!

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

267
## Contribute 💥
268

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
269
### Making a change in the code
270
271
272

PRs should be submitted to the `dev` branch, if it exists. Before submitting a pull request, create an issue to [discuss the implications of your proposal](https://github.com/cstate/cstate/issues).

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
Here is a guide for how you should develop:

1. Clone this repository in the command line:

```bash
git clone --recursive -b master https://github.com/cstate/cstate.git
```

2. Navigate to the theme directory:

```bash
cd cstate/exampleSite
```

3. Launch the development setup like this:

```bash
hugo serve --baseUrl=http://localhost/ --theme=cstate --themesDir=../.. --verbose
```

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 making a PR.

### For translators
296
297

[See this](https://github.com/cstate/cstate/wiki/Translations#add-your-translations).
Mantas's avatar
Mantas committed
298

Mantas Vilčinskas's avatar
Mantas Vilčinskas committed
299
### Code of conduct
300
301

[Be kind](/CODE_OF_CONDUCT.md).
302
303

## License ✍
304

305
[MIT](https://github.com/cstate/cstate/blob/master/LICENSE.md) © [Mantas Vilčinskas](https://mnts.lt)
306

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

**Note about versions**

We use semantic versioning. Version numbers are logged in the console (JS partial), the HTML — the `meta[generator]` tag (meta partial), and API index (index.json).