From 86d30cdee76732a3de151eb45a2f0c8db78a2450 Mon Sep 17 00:00:00 2001 From: Shay Nehmad Date: Wed, 17 Jun 2020 17:36:37 +0300 Subject: [PATCH] Moved config and readme around, fixed travis --- .travis.yml | 4 +- docs/README.md | 28 +---- docs/{ => config/_default}/config.toml | 7 +- docs/config/production/config.toml | 1 + docs/config/staging/config.toml | 1 + docs/content/_index.md | 4 +- .../development/contribute-documentation.md | 102 ++++++++++++++++++ docs/content/usage/file-checksums.md | 24 ++--- 8 files changed, 129 insertions(+), 42 deletions(-) rename docs/{ => config/_default}/config.toml (94%) create mode 100644 docs/config/production/config.toml create mode 100644 docs/config/staging/config.toml create mode 100644 docs/content/development/contribute-documentation.md diff --git a/.travis.yml b/.travis.yml index 247986cc4..2c1032cb0 100644 --- a/.travis.yml +++ b/.travis.yml @@ -41,6 +41,8 @@ install: # hugo (for documentation) - brew install hugo +# print hugo version (useful for debugging documentation build errors) +- hugo version before_script: # Set the server config to `testing`. This is required for for the UTs to pass. @@ -79,7 +81,7 @@ script: # Build documentation - cd $TRAVIS_BUILD_DIR/docs -- hugo --verbose +- hugo --verbose --environment staging after_success: # Upload code coverage results to codecov.io, see https://github.com/codecov/codecov-bash for more information diff --git a/docs/README.md b/docs/README.md index 07e92d85d..96129ce85 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,29 +1,5 @@ # Monkey documentation -This folder contains the Monkey Documentation site. The site is based on [Hugo](https://gohugo.io/) and the [learn](https://themes.gohugo.io/theme/hugo-theme-learn/en) theme. +This folder contains the Monkey Documentation site. -## Directory Structure - -The most important directory is `content`: This is the directory which contains the content files. [Read this to understand how pages are organized in that folder](https://themes.gohugo.io//theme/hugo-theme-learn/en/cont/pages/). - -## How to contribute - -### Requirements - -You have to install `hugo` and a text editor that's good for markdown (`vscode` and `vim` are good options). - -### Add content - -Run `hugo new folder/page.md`. Optionally add `--kind chapter` if this is a new chapter page. For example, `hugo new usage/getting-started.md` created the Getting Started page. - -### Editing content - -Edit the markdown file(s). [Here's a markdown cheatsheet](https://themes.gohugo.io//theme/hugo-theme-learn/en/cont/markdown/). If you want to add images, add them to the `static/images` folder and refer to them by name. - -### Test the content locally - -Run `hugo server -D`. The server will be available locally at `http://localhost:1313/infectionmonkey/docs/`. You can change the content and the site will refresh automatically - -### Build the content - -Run `hugo`. This will create a static site in the `public` directory. This directory should be ignored by `git` - **make sure you don't add and commit it by mistake!** +For more information see `content/development/contribute-documentation.md`. diff --git a/docs/config.toml b/docs/config/_default/config.toml similarity index 94% rename from docs/config.toml rename to docs/config/_default/config.toml index 9a098f127..e86950c04 100644 --- a/docs/config.toml +++ b/docs/config/_default/config.toml @@ -1,5 +1,6 @@ # when deploying to prod, use baseURL = "https://www.guardicore.com/infectionmonkey/docs" -baseURL = "https://staging-covuyicu.kinsta.cloud/infectionmonkey/docs/" +# baseURL = "https://staging-covuyicu.kinsta.cloud/infectionmonkey/docs/" +baseURL = "" languageCode = "en-us" title = "Guardicore Infection Monkey - Documentation Hub" @@ -60,3 +61,7 @@ name = " Email" identifier = "email" url = "https://join.slack.com/t/infectionmonkey/shared_invite/enQtNDU5MjAxMjg1MjU1LWM0NjVmNWE2ZTMzYzAxOWJiYmMxMzU0NWU3NmUxYjcyNjk0YWY2MDkwODk4NGMyNDU4NzA4MDljOWNmZWViNDU" weight = 40 + +# Enables raw html in markdown. +[markup.goldmark.renderer] +unsafe = true diff --git a/docs/config/production/config.toml b/docs/config/production/config.toml new file mode 100644 index 000000000..e59d2a44e --- /dev/null +++ b/docs/config/production/config.toml @@ -0,0 +1 @@ +baseURL = "https://www.guardicore.com/infectionmonkey/docs" diff --git a/docs/config/staging/config.toml b/docs/config/staging/config.toml new file mode 100644 index 000000000..75c9816cb --- /dev/null +++ b/docs/config/staging/config.toml @@ -0,0 +1 @@ +baseURL = "https://staging-covuyicu.kinsta.cloud/infectionmonkey/docs/" diff --git a/docs/content/_index.md b/docs/content/_index.md index 90e7cef56..92d21afff 100644 --- a/docs/content/_index.md +++ b/docs/content/_index.md @@ -4,7 +4,7 @@ date: 2020-05-26T18:15:37+03:00 draft: false --- -Welcome to the Infection Monkey documenation hub! +Welcome to the Infection Monkey documentation hub! ## What is Infection Monkey? @@ -19,7 +19,7 @@ To read more about the Monkey and download it, visit [our homepage](https://infe ## Getting Started -If you haven't downloaded Infection Monkey yet you can do so [from our homepage](https://infectionmonkey.com/). After downloadling the Monkey, install it using one of our [setup guides](setup), and read our [getting started guide](usage/getting-started) for a quick-start on Monkey! +If you haven't downloaded Infection Monkey yet you can do so [from our homepage](https://infectionmonkey.com/). After downloading the Monkey, install it using one of our [setup guides](setup), and read our [getting started guide](usage/getting-started) for a quick-start on Monkey! ## Support and community diff --git a/docs/content/development/contribute-documentation.md b/docs/content/development/contribute-documentation.md new file mode 100644 index 000000000..27f3e95ea --- /dev/null +++ b/docs/content/development/contribute-documentation.md @@ -0,0 +1,102 @@ +--- +title: "Contribute Documentation" +date: 2020-06-17T17:31:54+03:00 +draft: false +--- + +The `/docs` folder contains the Monkey Documentation site. + +The site is based on [Hugo](https://gohugo.io/) and the [learn](https://themes.gohugo.io/theme/hugo-theme-learn/en) theme. + +- [Directory Structure](#directory-structure) + - [content](#content) + - [static](#static) + - [config](#config) + - [themes](#themes) + - [layouts and archtypes](#layouts-and-archtypes) + - [public and resources](#public-and-resources) +- [How to contribute](#how-to-contribute) + - [Requirements](#requirements) + - [Adding and editing content](#adding-and-editing-content) + - [Add a new page](#add-a-new-page) + - [Editing an existing page](#editing-an-existing-page) + - [Building the content](#building-the-content) + - [Serve the documentation locally](#serve-the-documentation-locally) + - [Build the content for deployment](#build-the-content-for-deployment) + - [Troubleshooting](#troubleshooting) + - [`Error: Unable to locate config file or config directory. Perhaps you need to create a new site.`](#error-unable-to-locate-config-file-or-config-directory-perhaps-you-need-to-create-a-new-site) + - [`failed to extract shortcode: template for shortcode "children" not found`](#failed-to-extract-shortcode-template-for-shortcode-children-not-found) + - [CSS is missing](#css-is-missing) + +## Directory Structure + +By order of importance: + +### content + +The most important directory is `/content`: This is the directory which contains the content files. [Read this to understand how pages are organized in that folder](https://themes.gohugo.io//theme/hugo-theme-learn/en/cont/pages/). + +### static + +In this directory you should place images, `css` files, `js` files, and other static content the site should serve. To access that static content in a page, use something similar to this: + +```markdown +![AWS instance ID](../../images/setup/aws/aws-instance-id.png "AWS instance ID") +``` + +### config + +This folder controls a lot of parameters regarding the site generation. + +### themes + +This is the theme we're using. It's a submodule (so to get it you need to run `git submodule update`). It's our own fork of the [learn](https://themes.gohugo.io/hugo-theme-learn/) theme. If we want to make changes to the theme itself or pull updates from the upstream you'll do it here. + +### layouts and archtypes + +This directory includes custom [HTML partials](https://gohugo.io/templates/partials/), custom [shortcodes](https://gohugo.io/content-management/shortcodes/), and content templates. Best to not mess with the existing stuff here too much, but rather add new things. + +### public and resources + +These are the build output of `hugo` and should never be `commit`-ed to git. + +## How to contribute + +### Requirements + +You have to [install `hugo`](https://gohugo.io/getting-started/installing/) and a text editor that's good for markdown (`vscode` and `vim` are good options). + +### Adding and editing content + +#### Add a new page + +Run `hugo new folder/page.md`. Optionally add `--kind chapter` if this is a new chapter page. For example, `hugo new usage/getting-started.md` created the Getting Started page. + +#### Editing an existing page + +Edit the markdown file(s). [Here's a markdown cheatsheet](https://themes.gohugo.io//theme/hugo-theme-learn/en/cont/markdown/). If you want to add images, add them to the `static/images` folder and refer to them by name. + +### Building the content + +#### Serve the documentation locally + +Run `hugo server -D`. The server will be available locally at `http://localhost:1313/infectionmonkey/docs/`. You can change the content/theme and the site will refresh automatically to reflect your changes. + +#### Build the content for deployment + +Run `hugo --environment staging` or `hugo --environment production`. This will create a static site in the `public` directory. This directory should be ignored by `git` - **make sure you don't add and commit it by mistake!** + +#### Troubleshooting + +##### `Error: Unable to locate config file or config directory. Perhaps you need to create a new site.` + +What is your working directory? It should be `monkey/docs`. + +##### `failed to extract shortcode: template for shortcode "children" not found` + +Have you ran `git submodule update`? + +##### CSS is missing + +- Make sure that you're accessing the correct URL. +- Check the `config.toml` file. diff --git a/docs/content/usage/file-checksums.md b/docs/content/usage/file-checksums.md index fd0849d3c..56a1efb37 100644 --- a/docs/content/usage/file-checksums.md +++ b/docs/content/usage/file-checksums.md @@ -1,7 +1,7 @@ --- title: "Verify Integrity - Checksums" date: 2020-06-08T19:53:47+03:00 -draft: true +draft: false weight: 100 --- @@ -11,7 +11,7 @@ The official distribution of Infection Monkey is compiled and supplied by Guardi ### On Windows -Use the `Get-FileHash` powershell commandlet, like so: +Use the `Get-FileHash` PowerShell commandlet, like so: ```powershell Get-FileHash '.\Monkey Island v1.8.2_3536_windows.exe' | Format-List @@ -24,7 +24,7 @@ Get-FileHash '.\Monkey Island v1.8.2_3536_windows.exe' | Format-List ### On Linux -Use the `sha256sum` shell command, like so: +Use the `sha256sum` shell command, like so: ```sh sha256sum monkey-linux-64 @@ -36,15 +36,15 @@ sha256sum monkey-linux-64 | Filename | Type | Version | SHA256 hash | |-|-|-|-| -monkey-windows-64.exe | Windows Agent | 1.8.2 | 2e6a1cb5523d87ddfd48f75b10114617343fbac8125fa950ba7f00289b38b550 -monkey-windows-32.exe | Windows Agent | 1.8.2 | 86a7d7065e73b795e38f2033be0c53f3ac808cc67478aed794a7a6c89123979f -monkey-linux-64 | Linux Agent | 1.8.2 | 4dce4a115d41b43adffc11672fae2164265f8902267f1355d02bebb802bd45c5 -monkey-linux-32 | Linux Agent | 1.8.2 | 39d3fe1c7b33482a8cb9288d323dde17b539825ab2d736be66a9582764185478 -infection_monkey_deb.tgz | Debian Package | 1.8.2 | 2a6b4b9b846566724ff985c6cc8283222b981b3495dd5a8920b6bc3f34d556e2 -Monkey Island v1.8.2_3536_windows.exe | Windows Installer | 1.8.2 | 2be528685d675c882604d98382adb739f5ba0a7e234e3569b21f535173bd9569 -Monkey Island v1.8.2_3536_windowszt.exe | Windows Installer | 1.8.2 | f282ce4dd50abe54671948fb5b3baf913087459444e451660971290a72fe244a -infection_monkey_docker_docker_20200607_172156.tgz | Docker | 1.8.2 | 0e4bc731ef7e8bf19b759709672375890136c008526be454850d334d9ba5012d -infection_monkey_docker_dockerzt_20200607_172521.tgz | Docker | 1.8.2 | 0f4b0cd6fd54dc14ea50c5d2fb3fc711e9863518bd5bffd04e08a0f17eb99e75 +monkey-windows-64.exe | Windows Agent | 1.8.2 | `2e6a1cb5523d87ddfd48f75b10114617343fbac8125fa950ba7f00289b38b550` +monkey-windows-32.exe | Windows Agent | 1.8.2 | `86a7d7065e73b795e38f2033be0c53f3ac808cc67478aed794a7a6c89123979f` +monkey-linux-64 | Linux Agent | 1.8.2 | `4dce4a115d41b43adffc11672fae2164265f8902267f1355d02bebb802bd45c5` +monkey-linux-32 | Linux Agent | 1.8.2 | `39d3fe1c7b33482a8cb9288d323dde17b539825ab2d736be66a9582764185478` +infection_monkey_deb.tgz | Debian Package | 1.8.2 | `2a6b4b9b846566724ff985c6cc8283222b981b3495dd5a8920b6bc3f34d556e2` +Monkey Island v1.8.2_3536_windows.exe | Windows Installer | 1.8.2 | `2be528685d675c882604d98382adb739f5ba0a7e234e3569b21f535173bd9569` +Monkey Island v1.8.2_3536_windowszt.exe | Windows Installer | 1.8.2 | `f282ce4dd50abe54671948fb5b3baf913087459444e451660971290a72fe244a` +infection_monkey_docker_docker_20200607_172156.tgz | Docker | 1.8.2 | `0e4bc731ef7e8bf19b759709672375890136c008526be454850d334d9ba5012d` +infection_monkey_docker_dockerzt_20200607_172521.tgz | Docker | 1.8.2 | `0f4b0cd6fd54dc14ea50c5d2fb3fc711e9863518bd5bffd04e08a0f17eb99e75` ## All checksums