From 041a120c17b785f038f0e3c9e428b121f60ec9f3 Mon Sep 17 00:00:00 2001 From: F43nd1r Date: Fri, 30 Jul 2021 16:13:16 +0200 Subject: [PATCH] Deduplicate documentation (#255) * deduplicate documentation * changes from review * upload docs and jar-with-dependencies to gh release --- .github/workflows/releasetag.yml | 20 ++++-- README.md | 64 +++++++++++++++---- chaos-monkey-docs/pom.xml | 1 + .../src/main/asciidoc/assaults.adoc | 1 + .../src/main/asciidoc/getting-started.adoc | 2 + .../src/main/asciidoc/index.adoc | 20 ------ .../src/main/asciidoc/watcher.adoc | 2 +- .../chaos-monkey-demo-app-ext-jar/pom.xml | 7 -- demo-apps/chaos-monkey-demo-app-naked/pom.xml | 7 -- .../pom.xml | 7 -- demo-apps/chaos-monkey-demo-app/pom.xml | 7 -- .../chaos-monkey-web-reactive-app/pom.xml | 7 -- docs/_config.yml | 9 +++ docs/assets/css/style.scss | 20 ++++++ 14 files changed, 101 insertions(+), 73 deletions(-) create mode 100644 docs/_config.yml create mode 100644 docs/assets/css/style.scss diff --git a/.github/workflows/releasetag.yml b/.github/workflows/releasetag.yml index cfa48616..2166794a 100644 --- a/.github/workflows/releasetag.yml +++ b/.github/workflows/releasetag.yml @@ -26,18 +26,23 @@ jobs: restore-keys: | ${{ runner.os }}-maven- - name: Run Maven deploy - run: ./mvnw deploy -DperformRelease=true --settings .settings.xml + run: ./mvnw deploy -DperformRelease=true --settings .settings.xml -pl chaos-monkey-spring-boot env: SONATYPE_USERTOKEN: ${{ secrets.SONATYPE_USERTOKEN }} SONATYPE_USERTOKENPASSWORD: ${{ secrets.SONATYPE_USERTOKENPASSWORD }} GPG_PASSPHRASE: ${{ secrets.GPG_PASSPHRASE }} + - name: Gather docs + run: | + mkdir ./docs/latest + cp -R ./chaos-monkey-docs/target/generated-docs ./docs/latest/ + cp README.md ./docs/ + sed -i 's/docs\/images/images/g' ./docs/README.md - name: Publish gh-pages uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} enable_jekyll: true - publish_dir: ./chaos-monkey-docs/target/generated-docs - destination_dir: latest + publish_dir: ./docs commit_message: ${{ github.event.head_commit.message }} create_github_release: @@ -62,15 +67,20 @@ jobs: key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }} restore-keys: | ${{ runner.os }}-maven- - - name: Convert changelog to docbook - run: ./mvnw asciidoctor:process-asciidoc@output-docbook -pl chaos-monkey-docs + - name: Generate documentation (docbook, html, zip) + run: ./mvnw asciidoctor:process-asciidoc@output-docbook generate-resources -pl chaos-monkey-docs - name: Convert changelog from docbook to markdown uses: docker://pandoc/core:2.14 with: args: "-f docbook -t gfm -o changes.md chaos-monkey-docs/target/generated-docbook/changes.xml --wrap=none" + - name: Generate jar with dependencies + run: ./mvnw package -pl chaos-monkey-spring-boot - name: Create Github Release uses: softprops/action-gh-release@v1 with: body_path: changes.md + files: | + ./chaos-monkey-docs/target/chaos-monkey-docs-*.zip + ./chaos-monkey-spring-boot/target/chaos-monkey-spring-boot-*-jar-with-dependencies.jar env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/README.md b/README.md index 6e4cc3bd..74bcc59e 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -[![Apache License 2](https://img.shields.io/badge/license-ASF2-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0.txt) +[![Apache License 2](https://img.shields.io/github/license/codecentric/chaos-monkey-spring-boot)](https://www.apache.org/licenses/LICENSE-2.0.txt) [![Build Status](https://github.com/codecentric/chaos-monkey-spring-boot/workflows/Chaos%20Monkey%20Build/badge.svg)](https://github.com/codecentric/chaos-monkey-spring-boot/actions?query=workflow%3A%22Chaos+Monkey+Build%22) [![codecov](https://codecov.io/gh/codecentric/chaos-monkey-spring-boot/branch/main/graph/badge.svg)](https://codecov.io/gh/codecentric/chaos-monkey-spring-boot) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/de.codecentric/chaos-monkey-spring-boot/badge.svg)](https://maven-badges.herokuapp.com/maven-central/de.codecentric/chaos-monkey-spring-boot/) @@ -13,10 +13,10 @@ This project provides a Chaos Monkey for Spring Boot applications and will try to attack your running Spring Boot App. ->All details are explained on [Chaos Monkey for Spring Boot](https://codecentric.github.io/chaos-monkey-spring-boot/) +>Everything from getting started to advanced usage is explained in the [Documentation for Chaos Monkey for Spring Boot](https://codecentric.github.io/chaos-monkey-spring-boot/latest/) ## Introduction -If you're not familiar with the principles of chaos engineering yet, check out my latest blog post and enter the world of chaos engineering. +If you're not familiar with the principles of chaos engineering yet, check out this blog post and enter the world of chaos engineering. Chaos Engineering – withstanding turbulent conditions in production
@@ -25,20 +25,60 @@ Get familiar with the Chaos Monkey for Spring Boot in the following video, Chaos Monkey for Spring Boot
-**Chaos Monkey for Spring Boot - new features** -## Contributions -Chaos Monkey is open source and welcomes contributions from everyone. The contribution-guideline is where you should begin in order to best understand how to contribute to this project. +## What is the goal of Chaos Monkey? + +Inspired by [PRINCIPLES OF CHAOS ENGINEERING](https://principlesofchaos.org/), with a focus on [Spring Boot](https://projects.spring.io/spring-boot/), Chaos Monkey wants to test applications better and especially during operation. + +After writing many unit and integration tests, a code coverage from 70% to 80%, this unpleasant feeling remains, how our baby behaves in production? + +Many questions remain unanswered: + +- Will our fallbacks work? +- How does the application behave with network latency? +- What if one of our services breaks down? +- Service Discovery works, but is our Client-Side-Load-Balancing also working? + +As you can see, there are many more questions and open topics you have to deal with. +That was the start of Chaos Monkey for Spring Boot. + +### How does it work? +If Spring Boot Chaos Monkey is on your classpath and activated with profile name `chaos-monkey`, it will automatically hook into your application. + +Now you can activate [watchers](https://codecentric.github.io/chaos-monkey-spring-boot/latest/#watchers), which look for classes to [assault](https://codecentric.github.io/chaos-monkey-spring-boot/latest/#assaults). There are also [runtime assaults](https://codecentric.github.io/chaos-monkey-spring-boot/latest/#runtime-assaults), which attack your whole application. + +

+ +

+ +## Be social and communicative! +If you start to implement Chaos Engineering at your company, then you must be a very social and communicative person. Why? Because you will get to know many of your colleagues personally in a very short time when your chaos experiments strike. + +### Check your resilience +Are your services already resilient and can handle failures? Don´t start a chaos experiment if not! + +### Implement active application monitoring +Check your monitoring and check if you can see the overall state of your system. There are many great tools out there to get a pleasant feeling about your entire system. + +### Define steady states +Define a metric to check a steady state of your service and of course your entire system. Start small with a service that is not critical. + +### Do not start in production +Of course, you can start in production, but keep in mind... + +> The best place on earth is...production!
+> *Josh Long* + +...so let's keep production as the best place on earth and look for our first experiences on another stage. If all goes well, and you're confident, run it in production. ## Documentation -[Documentation](https://codecentric.github.io/chaos-monkey-spring-boot/#docs) +[Documentation](https://codecentric.github.io/chaos-monkey-spring-boot/latest/) -## Releases -[Releases](https://codecentric.github.io/chaos-monkey-spring-boot/#releases) +## Contributions +Chaos Monkey is open source and welcomes contributions from everyone. The [contribution guideline](https://github.com/codecentric/chaos-monkey-spring-boot/blob/main/CONTRIBUTING.adoc) is where you should begin in order to best understand how to contribute to this project. ->Chaos Monkey for Spring Boot 1.0.1 depends on [Spring Boot 2.0.x](https://projects.spring.io/spring-boot/) and [Spring Framework 5.0.x](https://projects.spring.io/spring-framework/) -## Latest Snapshots -[Snapshots](https://codecentric.github.io/chaos-monkey-spring-boot/#snapshots) +## Releases +[Releases](https://github.com/codecentric/chaos-monkey-spring-boot/releases) diff --git a/chaos-monkey-docs/pom.xml b/chaos-monkey-docs/pom.xml index 8f02817b..9f3026be 100644 --- a/chaos-monkey-docs/pom.xml +++ b/chaos-monkey-docs/pom.xml @@ -44,6 +44,7 @@ generate-resources process-asciidoc + zip index.adoc diff --git a/chaos-monkey-docs/src/main/asciidoc/assaults.adoc b/chaos-monkey-docs/src/main/asciidoc/assaults.adoc index 45219d44..e09ea9a5 100644 --- a/chaos-monkey-docs/src/main/asciidoc/assaults.adoc +++ b/chaos-monkey-docs/src/main/asciidoc/assaults.adoc @@ -18,6 +18,7 @@ You can determine at runtime whether an exception should occur when the method i Thanks to the great community, the Chaos Monkey for Spring Boot can throw any kind of RuntimeException. You can configure the required exception at runtime via the Actuator Endpoint. +[[runtime-assaults]] === Runtime Assaults === These assaults attack your whole application. diff --git a/chaos-monkey-docs/src/main/asciidoc/getting-started.adoc b/chaos-monkey-docs/src/main/asciidoc/getting-started.adoc index b5db49a9..bf45bc8d 100644 --- a/chaos-monkey-docs/src/main/asciidoc/getting-started.adoc +++ b/chaos-monkey-docs/src/main/asciidoc/getting-started.adoc @@ -18,6 +18,8 @@ There are two ways to integrate the Chaos Monkey for Spring Boot into your exist ---- +NOTE: If you want to use the latest snapshot version, add the sonatype staging repository `https://oss.sonatype.org/content/repositories/snapshots/` + 2.) Start your Spring Boot App Command-Line example: [source,txt,subs="verbatim,attributes"] diff --git a/chaos-monkey-docs/src/main/asciidoc/index.adoc b/chaos-monkey-docs/src/main/asciidoc/index.adoc index 04ea564f..047918c7 100644 --- a/chaos-monkey-docs/src/main/asciidoc/index.adoc +++ b/chaos-monkey-docs/src/main/asciidoc/index.adoc @@ -1,5 +1,4 @@ = Chaos Monkey for Spring Boot Reference Guide = -Benjamin Wilms :revnumber: {project-version} :revdate: {commit-time} :toc: left @@ -13,25 +12,6 @@ Benjamin Wilms :last-update-label!: :tabsize: 2 -== What is the goal of Chaos Monkey? == - -Inspired by http://principlesofchaos.org/[PRINCIPLES OF CHAOS ENGINEERING] and by my work in distributed system, with a focus on http://projects.spring.io/spring-boot/[Spring Boot], I wanted to test the resulting applications better and especially during operation. - -After writing many unit and integration tests, a code coverage from 70% to 80%, this unpleasant feeling remains, how our baby behaves in production? - -Many questions remain unanswered: - -- Will our fallbacks work? -- How does the application behave with network latency? -- What if one of our services breaks down? -- Service Discovery works, but is our Client-Side-Load-Balancing also working? - -As you can see, there are many more questions and open topics you have to deal with. - -That was my start to take a deep dive into Chaos Engineering and I started this little project to share my thoughts and experience. - -A detailed explanation of when and why you should use the Chaos Monkey for Spring Boot https://codecentric.github.io/chaos-monkey-spring-boot/[can be found here]. - include::getting-started.adoc[] include::endpoints.adoc[] include::toggles.adoc[] diff --git a/chaos-monkey-docs/src/main/asciidoc/watcher.adoc b/chaos-monkey-docs/src/main/asciidoc/watcher.adoc index e79b3c3f..31fd5d43 100644 --- a/chaos-monkey-docs/src/main/asciidoc/watcher.adoc +++ b/chaos-monkey-docs/src/main/asciidoc/watcher.adoc @@ -1,4 +1,4 @@ -[[watcher]] +[[watchers]] == Watcher == A watcher is a Chaos Monkey for Spring Boot component, that will scan your app for a specific type of annotation. diff --git a/demo-apps/chaos-monkey-demo-app-ext-jar/pom.xml b/demo-apps/chaos-monkey-demo-app-ext-jar/pom.xml index 4e3815c4..42c5f45e 100644 --- a/demo-apps/chaos-monkey-demo-app-ext-jar/pom.xml +++ b/demo-apps/chaos-monkey-demo-app-ext-jar/pom.xml @@ -73,13 +73,6 @@ - - org.apache.maven.plugins - maven-deploy-plugin - - true - - diff --git a/demo-apps/chaos-monkey-demo-app-naked/pom.xml b/demo-apps/chaos-monkey-demo-app-naked/pom.xml index 96dc0f97..bdb868b3 100644 --- a/demo-apps/chaos-monkey-demo-app-naked/pom.xml +++ b/demo-apps/chaos-monkey-demo-app-naked/pom.xml @@ -85,13 +85,6 @@ - - org.apache.maven.plugins - maven-deploy-plugin - - true - - diff --git a/demo-apps/chaos-monkey-demo-app-unleash-toggles/pom.xml b/demo-apps/chaos-monkey-demo-app-unleash-toggles/pom.xml index f6441e5a..ffe6c1bd 100644 --- a/demo-apps/chaos-monkey-demo-app-unleash-toggles/pom.xml +++ b/demo-apps/chaos-monkey-demo-app-unleash-toggles/pom.xml @@ -99,13 +99,6 @@ - - org.apache.maven.plugins - maven-deploy-plugin - - true - - diff --git a/demo-apps/chaos-monkey-demo-app/pom.xml b/demo-apps/chaos-monkey-demo-app/pom.xml index 4398ee1c..16e12169 100644 --- a/demo-apps/chaos-monkey-demo-app/pom.xml +++ b/demo-apps/chaos-monkey-demo-app/pom.xml @@ -94,13 +94,6 @@ - - org.apache.maven.plugins - maven-deploy-plugin - - true - - diff --git a/demo-apps/chaos-monkey-web-reactive-app/pom.xml b/demo-apps/chaos-monkey-web-reactive-app/pom.xml index 366ead2b..c4b85e48 100644 --- a/demo-apps/chaos-monkey-web-reactive-app/pom.xml +++ b/demo-apps/chaos-monkey-web-reactive-app/pom.xml @@ -77,13 +77,6 @@ - - org.apache.maven.plugins - maven-deploy-plugin - - true - - diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 00000000..3d728186 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,9 @@ +theme: jekyll-theme-cayman +title: Chaos Monkey for Spring Boot +author: Codecentric +description: This project provides a Chaos Monkey for Spring Boot and will try to attack your running Spring Boot App. +social: + name: Codecentric + links: + - https://www.codecentric.de/ + - https://github.com/codecentric \ No newline at end of file diff --git a/docs/assets/css/style.scss b/docs/assets/css/style.scss new file mode 100644 index 00000000..5d2b98d6 --- /dev/null +++ b/docs/assets/css/style.scss @@ -0,0 +1,20 @@ +--- +--- + +@import "{{ site.theme }}"; + +.main-content { + max-width: 90rem; +} + +.imgborder { + display:inline-block; + position:relative; + border:1px solid #01add1; +} + +.imgborder.s1 { + -webkit-box-shadow: 0 28px 16px -26px rgba(0, 0, 0, 0.5); + -moz-box-shadow: 0 28px 16px -26px rgba(0, 0, 0, 0.5); + box-shadow: 0 28px 16px -26px rgba(0, 0, 0, 0.5); +} \ No newline at end of file