Deploying Report with `MkDocs`

Objective

The aim of this section is to create documentation in Markdown and use MkDocs to deploy the documentation generated as a static site in reference to the 7th point of the problem statement under Task 1.

Format and Tools

The report was written in Markdown as required by the problem statement. Markdown is a markup language that allows text formatting using a defined syntax. It is used extensively for documentation and can be converted to various other formats, including HTML, which allows many tools to build static sites with markdown documentation.

MkDocs was the tool used, as required by the problem statement, to build a static site with the report. MkDocs is a static site generator that creates sites with content written in Markdown and the site is configured with a YAML (YAML is a human-friendly data serialization standard and has various applications) file.

Installing `MkDocs`

I installed MkDocs with the command 'pip install mkdocs' as mentioned in the official documentation. I only referred to the 'Installing MkDocs' section under 'Manual Installation' as the rest of the steps were not required in the context of the task/problem statement.

Selecting a Theme

MkDocs allows users to use various themes to customize the style and look of the site. For the report's site generated with MkDocs to look nice, I used the 'Material' theme as suggested during the preliminary review of the task. To use this theme with MkDocs, it is required to be installed with pip so, I installed Material theme using the command 'pip install mkdocs-material' as mentioned in the official documentation. Lastly, I specified the theme in MkDocs's configuration YAML file which can be seen in the next section.

Site Configuration

To build the static site, MkDocs needs a YAML file, called mkdocs.yml, be present in the root directory of the project that configures the site structure, site title, pages, themes, etc. It is used to define properties for the site. The YAML file that I wrote for the report is below:

site_name: 'Jenkins Pipeline'

pages:
- Introduction: 'index.md'
- Contents: 'intro.md'
- Problem Statement: 'problem_statement.md'
- Glossary: 'glossary.md'
- Setting Up VMs: 'setting_up_vms.md'
- Setting Up Pipeline: setting_up_pipeline.md
- Static Analysis: 'static_analysis.md'
- Comparing SAST Tools: 'comparing_sast_tools.md'
- Configuring Webhook: 'configuring_webhook.md'
- Deploying the Report: 'deploying_report.md'
- Dynamic Analysis: 'dynamic_analysis.md'
- Comparing DAST Tools: 'comparing_dast_tools.md'
- Code Quality Analysis: 'code_quality_analysis.md'
- Generating Software Bill of Materials: 'generating_sbom.md'
- Final Pipeline Structure: 'final_pipeline.md'
- Shifting Local Setup to AWS: 'moving_setup_to_aws.md'
- Secrets Management: 'secrets_management.md'
- Limitations: 'limitations.md'
- Resources: 'resources.md'


theme: material

site_name defines the title for the site generated by MkDocs.
pages defines the various pages that the site will consist of. Within this section, the title for the different pages, along with the Markdown file they are to be associated with, are also declared in a key-value pair structure.
theme defines which theme MkDocs should use while generating/serving the static site.

Deploying Static Site

To generate the static site, in the root directory of the report, I ran the command 'mkdocs build' as mentioned in the documentation. This creates a /site directory containing all the required files to deploy the site.

Note: To just preview how the site looks, I used 'mkdocs serve' in the terminal to serve the site locally on my machine.

Now, to serve the site I needed a web server for which I installed Apache, following Digital Ocean's documentation, as the server. I chose Apache as it is popular, has great support and is easy to work with, in my opinion. The documentation was concise and complete in the context of the task and hence, I went with it. I, however, skipped step 4, 'Setting Up Virtual Hosts', as I was only going to host one site and thus, did not require to configure virtual hosts which are used to serve multiple websites on the same server.

Lastly, I copied the contents from static site directory (/site) generated with MkDocs to the web root directory (/var/www/html) to serve the report as a static site.

Deploying Report with MkDocs