Write Documentation for new Docker Containers

CHANGELOG.md

@@ -10,12 +10,12 @@ and this project adheres to [Semantic Versioning](http://semver.org/)
 ### Fixed 🐞
 
 -   Rerender immediately after marking a folder with a color [#3067](https://github.com/MaibornWolff/codecharta/pull/3067)
--   Clicking the 'reset height metric settings' button resets the number of top labels to the dynamic default
-    value [#3066](https://github.com/MaibornWolff/codecharta/pull/3066)
+-   Clicking the 'reset height metric settings' button resets the number of top labels to the dynamic default value [#3066](https://github.com/MaibornWolff/codecharta/pull/3066)
 
-## Chore 👨‍💻 👩‍💻
+### Chore 👨‍💻 👩‍💻
 
 -   Update Docker Publish Action in Release Pipeline [#3060](https://github.com/MaibornWolff/codecharta/pull/3060)
+-   Write documentation for docker containers [#3063](https://github.com/MaibornWolff/codecharta/pull/3063)
 
 ## [1.108.1] - 2022-09-29
 
@@ -27,8 +27,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/)
 
 ### Added 🚀
 
--   Add new Analysis docker container, together with a docker-compose file that contains analysis, visualization and a
-    SonarQube instance [#3057](https://github.com/MaibornWolff/codecharta/pull/3057)
+-   Add new Analysis docker container, together with a docker-compose file that contains analysis, visualization and a SonarQube instance [#3057](https://github.com/MaibornWolff/codecharta/pull/3057)
 
 ### Removed 🗑
 

gh-pages/_data/navigation.yml

@@ -38,6 +38,8 @@ docs:
             url: /docs/custom-metrics/
           - title: "Analyze with SonarQube"
             url: /docs/analyze-with-sonarqube/
+          - title: "Docker Containers"
+            url: /docs/docker-containers/
 
     - title: Analysing-Tools
       children:

gh-pages/_docs/01-01-quick-start-guide.md

@@ -11,7 +11,7 @@ CodeCharta consists of two separate parts: [analysis]({{site.baseurl}}{% link _d
 
 > Please note that CodeCharta only runs on your client. No `.cc.json` that you analyze or visualize will ever leave your computer unless you distribute it yourself.
 
-You can [try the web visualization]({{site.web_visualization_link}}) immediately and explore CodeCharta Code in CodeCharta. No downloads necessary, though we do provide a [desktop client]({{site.baseurl}}{% link _docs/01-03-installation.md %}) for your convenience. The visualization interface is explained [here]({{site.baseurl}}{% link _docs/06-01-visualization.md %}) and if you want to explore another code base than the default one, you can use one of the files from the [showcase]({{site.baseurl}}{% link _pages/showcase.md %}).
+You can [try the web visualization]({{site.web_visualization_link}}) immediately and explore CodeCharta Code in CodeCharta. No downloads necessary, though we do provide a [desktop client]({{site.baseurl}}{% link _docs/01-03-installation.md %}) for your convenience. The visualization interface is explained [here]({{site.baseurl}}{% link _docs/06-01-visualization.md %}) and if you want to explore another code base from the default one, you can use one of the files from the [showcase]({{site.baseurl}}{% link _pages/showcase.md %}).
 
 However, if you want to **generate your own** `.cc.json`, you should read this guide first.
 
@@ -57,7 +57,7 @@ Please make sure you have [Tokei](https://github.com/XAMPPRocky/tokei#installati
 ```bash
 # Download code base of your choice
 git clone https://github.com/apache/httpd.git
-# Parse code with tokei
+# Parse code with Tokei
 cd httpd; tokei -o json . > ../httpd.tokei.json; cd ..
 # Parse sources
 ccsh tokeiimporter httpd.tokei.json -o httpd.tokei.cc.json
@@ -83,13 +83,11 @@ ccsh sonarimport [options] [file] [url] [project-id]
 
 # 5+2 min Combine Metrics Quickstart
 
-Please make sure you have [Git](https://git-scm.com/downloads) installed and that you have completed one of the previous quickstarts. Otherwise you won't have a `.cc.json` to combine with git metrics.
+Please make sure you have [Git](https://git-scm.com/downloads) installed and that you have completed one of the previous quickstarts. Otherwise, you won't have a `.cc.json` to combine with git metrics.
 
 ```bash
-# Generate <project>.git.log
-cd junit4; git log --numstat --raw --topo-order > ../junit4.git.log; cd ..
-# Parse git.log
-ccsh gitlogparser junit4.git.log -o junit4.git.cc.json --input-format GIT_LOG_NUMSTAT_RAW
+# Generate and parse a <project>.git.log
+cd junit4; ccsh gitlogparser repo-scan -o junit4.git.cc.json -nc
 ```
 
 We can now merge the files.
@@ -100,9 +98,9 @@ ccsh merge junit4.source.cc.json junit4.git.cc.json -o junit4.cc.json
 
 With the merge done you can now open it in the visualization again.
 
-Depending on what importer you use there might be a structural problem though. `ccsh merge` actually creates a union of all files you give it and only merges the metrics for which the path matches. That's great if one file only contains metrics for `.java` files and the other file has metrics for all files but it can create problems.
+Depending on what importer you use there might be a structural problem though. `ccsh merge` actually creates a union of all files you give it and only merges the metrics for which the path matches. That's great if one file only contains metrics for `.java` files and the other file has metrics for all files, but it can create problems.
 
-For example the path for a file Foo.java should be the same in both files. If the structures don't match, the metrics you got from different sources won't be merged into the same entity but stay separate. In the visualization you'll see one one building _root/Foo.java_ that has all source metrics and one _root/src/main/java/Foo.java_ that has all the git metrics. That's not what you want.
+For example the path for a file Foo.java should be the same in both files. If the structures don't match, the metrics you got from different sources won't be merged into the same entity but stay separate. In the visualization you'll see one building _root/Foo.java_ that has all source metrics and one _root/src/main/java/Foo.java_ that has all the git metrics. That's not what you want.
 
 A simple comparison you can do is to check that the `<project>.source.cc.json` has a folder src directly under root (root/src) and the git.cc.json has the same folder also under root.
 
@@ -114,6 +112,35 @@ ccsh modify junit4.git.cc.json -p 1
 # Use (--move-from and --move-to) or --set-root to correct wrong structure
 ```
 
+# 10 min Docker Quickstart
+
+To get started quickly, you can also use CodeCharta in a Docker container. For this you need to have [Docker](https://docs.docker.com/get-docker/) and [Docker compose](https://docs.docker.com/compose/install/) installed.
+
+```bash
+# Assuming you have the docker-compose.yml on hand
+docker compose pull && docker compose up --detach
+```
+
+Now that all containers are running, we can connect to the analysis container.
+
+```bash
+# You can see the name of all running containers with 'docker ps'
+docker exec -it codecharta-analysis-1 bash
+```
+
+You are now connected into the container, and are able to run ccsh by simply typing `ccsh`. You can try any of the other quickstart guides to create a .cc.json file.
+Once you have a .cc.json file, we can copy it to our hard drive.
+
+```bash
+# You can see the name of all running containers with 'docker ps'
+docker cp codecharta-analysis-1:path/to/ccjson/ docker-sample.cc.json
+```
+
+> You can also [check the docs of the docker cp command to learn more.](https://docs.docker.com/engine/reference/commandline/cp/)
+> To move files between containers (for example to and from sonar) you can use the shared volume, which you can access under /mnt/data in each container.
+
+Now you're almost done! Simply navigate to localhost:9001 in your browser to open the visualization and upload your file.
+
 # CodeCharta in a Tweet Quickstart
 
 `ccsh merge` is a powerful tool to merge multiple `.cc.json` files. Sometimes though you do not need the intermediate `.cc.json` files though and just want a combined file as fast as possible. For this purpose the most popular `ccsh` importers allow piping the `.cc.json` contents (see [ccsh docs]({{site.baseurl}}{% link _docs/05-03-ccsh.md %})). This allows us to generate a combine `.cc.json` in less than 280 characters :)

gh-pages/_docs/05-06-docker-containers.md

@@ -0,0 +1,66 @@
+---
+permalink: /docs/docker-containers/
+title: "Docker Containers"
+---
+
+CodeCharta also comes as a full Docker environment, where all supported tools come pre-installed. To start all
+containers, you can type `docker compose pull && docker compose up --detach` while you're in the same directory as our
+docker-compose.yml
+
+## The Container Landscape
+
+| Container-Name           | Description                             | How to use                                                      |
+| ------------------------ | --------------------------------------- | --------------------------------------------------------------- |
+| codecharta-sonar         | Hosts an instance of SonarQube          | localhost:9000 in the browser, follow the steps for Linux       |
+| codecharta-visualization | Runs the visualisation part o CodeChara | localhost:9001, load files from your hard-drive                 |
+| codecharta-analysis      | Contains all tools the ccsh can import  | Connect via terminal `docker exec -it codecharta-analysis bash` |
+
+> To see the actual names of the containers on your system, run `docker ps`
+
+All containers share a volume for the quick transfer of files. You can find it under /mnt/data in each container.
+Please note that you will need to copy finished cc.json files to **your** hard-drive to open them in Visualization.
+
+### codecharta-sonar
+
+See also [SonarQube Docs](https://docs.sonarqube.org/latest/setup/get-started-2-minutes/)
+
+Open `localhost:9000` in your browser and log in with
+
+-   login: admin
+-   password: admin
+
+Simply follow the steps for a manual, local project under Linux. You can also [check our tutorial for SonarQube](
+{{site.baseurl}}{% link _docs/analyze-with-sonarqube.md %})
+The sonar-scanner is already pre-installed in our analysis container.
+
+### codecharta-visualization
+
+See also [CodeCharta Visualization]({{site.baseurl}}{% link _docs/visualization.md %})
+
+Open `localhost:9001` in your browser and open any file you want from your hard drive.
+To open files you have created in the analysis container, copy them over using `docker cp`
+
+### codecharta-analysis
+
+See also [CodeCharta Analysis]({{site.baseurl}}{% link _docs/analysis.md %})
+
+Almost all tools the ccsh can import data from are included in the container, so you can get started immediately.
+Installed are:
+
+-   CodeCharta Shell `ccsh`
+-   Git `git`
+-   Tokei `tokei`
+-   CodeMaat `java -jar /opt/codemaat/codemaat.jar`
+-   MetricGardener `metric-gardener`
+-   SonarScanner `sonar-scanner`
+
+Once you have your .cc.json file ready, you can copy it to your machine.
+This is how the command could look like if I want to copy a file from the container to my current working directory:
+
+```bash
+docker cp codecharta-analysis-1:/root/junit4.cc.json.gz junit4.cc.json.gz
+```
+
+To check the name of the container, you can simply type `docker ps`.
+To analyze your code you can follow one of our quick-start guides or check out the in-depth documentation for a certain
+importer.