docs(pages): update installation instructions

swingletree-oss · Jul 18, 2020 · b741c99 · b741c99
1 parent 0f75708
commit b741c99
Show file tree

Hide file tree

Showing 5 changed files with 114 additions and 18 deletions.
diff --git a/docs/_docs/install/compose.md b/docs/_docs/install/compose.md
@@ -0,0 +1,49 @@
+---
+title: Docker Compose
+permalink: /docs/install/compose/
+redirect_from: /docs/index.html
+---
+
+<div class="well well-sm">
+Kubernetes is recommended to host your Swingletree installation. Docker Compose can be used to quickly set up a Swingletree instance for evaluation purposes. 
+</div>
+
+This section covers the installation of an on-premise Swingletree using `docker-compose`
+
+
+#### Custom CA
+
+In case you need to use a custom certificate authority mount the certificate in `pem` format into the containers and define the environment variable `NODE_EXTRA_CA_CERTS` with the absolute path of the file inside the container.
+
+```yaml
+# docker-compose.yml
+[ ... ]
+  # example for scotty
+  scotty:
+    container_name: scotty
+    env_file: 
+      - ./compose.env
+    environment:
+      NODE_EXTRA_CA_CERTS: /opt/cert/ca.pem # reference extra ca certs file to nodejs
+    image: docker.pkg.github.com/swingletree-oss/scotty/scotty:VERSION
+    restart: always
+    volumes:
+      - ./swingletree.conf.yaml:/opt/scotty/swingletree.conf.yaml
+      - ./ca.pem:/opt/cert/ca.pem # mount certificate
+    expose:
+      - "3000"
+[ ... ]
+```
+
+#### GitHub Packages Docker Registry
+
+Some registries (like GitHub packages) allow only authenticated users to pull images. You will need to authenticate via `docker login docker.pkg.github.com`
+before pulling images. See [GitHub Packages Docs](https://docs.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-docker-for-use-with-github-packages)
+in case you require more information.
+
+### Deploying Swingletree
+
+Clone the [Swingletree Management Repository][mgmt] and switch to the directory `compose`. You will find 
+a `README.md` describing the next steps for the version you checked out.
+
+[mgmt]: https://github.com/swingletree-oss/swingletree/
diff --git a/docs/_docs/install/prepare.md b/docs/_docs/install/prepare.md
@@ -6,26 +6,38 @@ redirect_from: /docs/index.html
 
 This section covers the preparation steps to perform before installing Swingletree.
 
+### SCM Provider: GitHub
+
+In case you chose GitHub as your SCM provider perform following steps
+
 Create Swingletree GitHub App
   * Retrieve GitHub App Id
   * Retrieve GitHub App private key file
   * Set permissions (See section below)
 
-### GitHub Application
+#### GitHub Application
 
 In case you want to run your own Swingletree you will need to create a GitHub App on Github.com (or your GitHub Enterprise instance). Follow the instructions on this [GitHub Guide][create-gh-app] to create one.
 
-#### Permissions
+##### Permissions
 
 When creating your GitHub App you will need to specify the permissions required by the App. If the permissions are not granted, Swingletree will not be able to operate properly.
 
 * Read and Write access are required for `Checks`
 * Read access is required for `Single File`, set `Path` to `.swingletree.yml`
 
-#### GitHub App Private Key
+##### GitHub App Private Key
 
 You will notice that a private key file named `gh-app.pem` (by default) is required on startup. Swingletree needs this file to authenticate with GitHub.
 
 After you have created your GitHub App, you can generate and download the key from the App configuration page.
 
 [create-gh-app]: https://developer.github.com/apps/building-github-apps/creating-a-github-app/
+
+
+
+### SCM Provider: Gitea
+
+In case you chose Gitea as your SCM provider perform following steps:
+
+1. Create an API token
diff --git a/docs/_docs/install/prerequisites.md b/docs/_docs/install/prerequisites.md
@@ -9,7 +9,9 @@ Swingletree needs a Redis Database for caching purposes. SonarQube offers a bran
 obtain information about the quality of branches in relation to the `master` branch.
 
 * Redis Database (provided with k8s installation)
-* GitHub or GitHub Enterprise
+* One of the supported SCM Providers
+  * GitHub or GitHub Enterprise
+  * Gitea
 
 If you intend to use ElasticSearch to store your analysis reports you will need
 

diff --git a/docs/index.html b/docs/index.html
@@ -19,7 +19,7 @@
     </div>
 
     <div class="row">
-        <div class="col-md-3 col-md-offset-1" style="text-align:center">
+        <div class="col-md-4" style="text-align:center">
             <div style="height:5em">
                 <span class="fa-stack fa-2x">
                     <i class="fas fa-circle fa-stack-2x feat"></i>
@@ -29,27 +29,25 @@
             <div class="card-body">
                 <h5 class="card-title">GitHub Integration</h4>
                 <p class="card-text">
-                    No need to jump between tools to see what failed your Quality Gate. Swingletree uses the GitHub
-                    Checks API to annotate findings in your commits and pull requests. Supports GitHub Enterprise.
+                    Swingletree uses the GitHub Checks API to annotate findings in your commits and pull requests. Supports GitHub Enterprise.
                 </p>
             </div>
         </div>
-        <div class="col-md-3 col-md-offset-1" style="text-align:center">
+        <div class="col-md-4" style="text-align:center">
             <div style="height:5em">
                 <span class="fa-stack fa-2x">
                     <i class="fas fa-circle fa-stack-2x feat"></i>
-                    <i class="fa-stack-1x fas fa-database fa-inverse"></i>
+                    <svg height="100%" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" focusable="false" width="1em" height="1em" style="-ms-transform: rotate(360deg); -webkit-transform: rotate(360deg); transform: rotate(360deg);" preserveAspectRatio="xMidYMid meet" viewBox="0 0 24 24"><path d="M4.186 5.421C2.341 5.417-.13 6.59.006 9.531c.213 4.594 4.92 5.02 6.801 5.057c.206.862 2.42 3.834 4.059 3.99h7.18c4.306-.286 7.53-13.022 5.14-13.07c-3.953.186-6.296.28-8.305.296v3.975l-.626-.277l-.004-3.696c-2.306-.001-4.336-.108-8.189-.298c-.482-.003-1.154-.085-1.876-.087zm.261 1.625h.22c.262 2.355.688 3.732 1.55 5.836c-2.2-.26-4.072-.899-4.416-3.285c-.178-1.235.422-2.524 2.646-2.552zm8.557 2.315c.15.002.303.03.447.096l.749.323l-.537.979a.672.597 0 0 0-.241.038a.672.597 0 0 0-.405.764a.672.597 0 0 0 .112.174l-.926 1.686a.672.597 0 0 0-.222.038a.672.597 0 0 0-.405.764a.672.597 0 0 0 .86.36a.672.597 0 0 0 .404-.765a.672.597 0 0 0-.158-.22l.902-1.642a.672.597 0 0 0 .293-.03a.672.597 0 0 0 .213-.112c.348.146.633.265.838.366c.308.152.417.253.45.365c.033.11-.003.322-.177.694c-.13.277-.345.67-.599 1.133a.672.597 0 0 0-.251.038a.672.597 0 0 0-.405.764a.672.597 0 0 0 .86.36a.672.597 0 0 0 .404-.764a.672.597 0 0 0-.137-.202c.251-.458.467-.852.606-1.148c.188-.402.286-.701.2-.99c-.086-.289-.35-.477-.7-.65c-.23-.113-.517-.233-.86-.377a.672.597 0 0 0-.038-.239a.672.597 0 0 0-.145-.209l.528-.963l2.924 1.263c.528.229.746.79.49 1.26l-2.01 3.68c-.257.469-.888.663-1.416.435l-4.137-1.788c-.528-.228-.747-.79-.49-1.26l2.01-3.679c.176-.323.53-.515.905-.53h.064z" fill="white"/></svg>
                 </span>
             </div>
             <div class="card-body">
-                <h5 class="card-title">Auditable</h4>
+                <h5 class="card-title">Gitea Integration</h4>
                 <p class="card-text">
-                    Swingletree stores the results of received build reports in GitHub and
-                    ElasticSearch.
+                    Provides integration to Gitea using the Gitea Commit Status API.
                 </p>
             </div>
         </div>
-        <div class="col-md-3 col-md-offset-1" style="text-align:center">
+        <div class="col-md-4" style="text-align:center">
             <div style="height:5em">
                 <span class="fa-stack fa-2x">
                     <i class="fas fa-circle fa-stack-2x feat"></i>
@@ -59,16 +57,30 @@ <h5 class="card-title">Auditable</h4>
             <div class="card-body">
                 <h5 class="card-title">Keep track</h4>
                 <p class="card-text">
-                     Swingletree persists each received report to ElasticSearch. View build information via the Swingletree
-                     webinterface or use Grafana/Kibana to process the stored data into neat graphs.
+                     View build information via the Swingletree webinterface or use Grafana/Kibana to process the stored data into neat graphs.
                 </p>
             </div>
         </div>
     </div>
 
 
     <div class="row" style="padding-top:2em">
-        <div class="col-md-3 col-md-offset-3" style="text-align:center">
+        <div class="col-md-4" style="text-align:center">
+            <div style="height:5em">
+                <span class="fa-stack fa-2x">
+                    <i class="fas fa-circle fa-stack-2x feat"></i>
+                    <i class="fa-stack-1x fas fa-database fa-inverse"></i>
+                </span>
+            </div>
+            <div class="card-body">
+                <h5 class="card-title">Auditable</h4>
+                <p class="card-text">
+                    Swingletree stores the results of received build reports in GitHub and
+                    ElasticSearch.
+                </p>
+            </div>
+        </div>
+        <div class="col-md-4" style="text-align:center">
             <div style="height:5em">
                 <span class="fa-stack fa-2x">
                     <i class="fas fa-circle fa-stack-2x feat"></i>
@@ -83,7 +95,7 @@ <h5 class="card-title">Extendable</h4>
                 </p>
             </div>
         </div>
-        <div class="col-md-3 col-md-offset-1" style="text-align:center">
+        <div class="col-md-4" style="text-align:center">
             <div style="height:5em">
                 <span class="fa-stack fa-2x">
                     <i class="fas fa-circle fa-stack-2x feat"></i>

diff --git a/docs/showcase.html b/docs/showcase.html
@@ -62,7 +62,7 @@ <h3 class="underline">Code Annotations</h3>
 
             <div class="separator"></div>
 
-            <h3 class="underline">Check Runs</h3>
+            <h3 class="underline">GitHub Check Runs</h3>
             <p>
                 Posting and deleting analysis results as comments into the Pull Request conversation clutters
                 the discussion and may lead to misunderstandings due to automated deletions.
@@ -72,6 +72,27 @@ <h3 class="underline">Check Runs</h3>
             <p>
                 <img class="showcase img-thumbnail" style="max-width:75%" src="assets/images/swingletree-check-run.png" alt="" />
             </p>
+
+            <h3 class="underline">GitHub Code Annotations</h3>
+            <p>
+                Swingletree annotates the code inside the Pull Request with the SonarQube findings. Developers do not
+                have to leave GitHub.
+            </p>
+
+            <p>
+                <img class="showcase img-thumbnail" style="max-width:75%" src="assets/images/pull-request-files.png" alt="" />
+            </p>
+
+            <div class="separator"></div>
+
+            <h3 class="underline">Gitea Commit Status</h3>
+            <p>
+                Swingletree can integrate with Gitea to annotate commits using the Gitea Commit Status API. The results
+                are visible in the commits and Pull Requests
+            </p>
+            <p>
+                <img class="showcase img-thumbnail" style="max-width:75%" src="assets/images/gitea-checks.png" alt="" />
+            </p>
         </div>
     </div>
 </div>