Layer5 Product Documentation

Explore tutorials and documentation by product in the docs.layer5.io website; documentation and developer resources of Layer5 products.

Contributions Welcome

If you find a typo or you feel like you can improve the HTML, CSS, or JavaScript, we welcome contributions. Feel free to open issues or pull requests like any normal GitHub project, and we'll merge it in 🚀

Running the Site Locally

The website can be run locally through Golang (Hugo) or Docker. If you choose to run through Docker, everything will be a little bit slower due to the additional overhead, so for frequent contributors it may be worth it to use Golang.

With Docker

Running the site locally is simple. Provided you have Docker installed, clone this repo, run make docker, and then visit http://localhost:1313.

[!IMPORTANT]
This requires Docker Desktop version 4.24 or later, or Docker Engine with Docker Compose version 2.22 or later.

With Golang

If your local development environment has a supported version (v1.21.0+) of Golang installed, next you'll need to install extended hugo version as it has necessary SCSS/SASS support. Find all the hugo packages here: https://github.com/gohugoio/hugo/releases/tag/v0.120.4

Now to setup and run the site locally run:

make setup followed by make site

...and then visit http://localhost:1313.

If you pull down new code from GitHub, you will occasionally need run make setup again. Otherwise, there's no need to re-run make setup each time the site is run, you can just run make site to get it going and have it automatically reload as you make and save site edits.

Layer5 Documentation Stucture

High-Level Outline & Information Architecture for Layer5 Documentation

Goal: Offer comprehensive, organized, and accessible documentation for diverse audiences, from new users to expert contributors.

Target Audience:

• Personas: Beginners, developers, admins, operators, security specialists, contributors, users of all experience levels.
• Needs: Varied - learning fundamentals, managing tasks, understanding advanced concepts, contributing code.

Cloud Docs

Getting Started

• Setting up Layer5 Account: With a personal account on Layer5 Cloud, you can import or create infrastructural designs, collaborate with others through workspaces and teams, manage your organizations and more.
• Creating a Design from Meshery Catalog Templates: With this guide, you can create amazing cloud native designs for your infrastructure from already avaliable templetes in the meshery catalog.

Concepts

An overview of Layer5 Cloud concepts and their relationships to one another.

Identity

• Organizations: Organizations, Managing Organization Permissions
• Teams: Teams, Managing Teams Permissions
• Users: User Management, Managing User Permissions

Security

• Tokens: API Tokens are used to authenticate to Layer5 Cloud’s REST API.
• Keychains: Keychains are a collection of keys
• Keys: Keys are the atomic unit of access control
• Roles: Roles map permissions to users.

Catalog

The Cloud Catalog is a web-based, public catalog to facilitate easy sharing and discovery of common cloud native architectures and design patterns.

Workspaces

Meshery Workspaces serve as a virtual space for your team-based work.

Tutorials

• MeshMap Snapshots: Connect MeshMap to your GitHub repo and see changes pull request-to-pull request.
• Sharing a Workspace: Learn how to control access to workspaces and their resources.
• Recognizing User and Contributor Milestones: Showcasing user and contributor achievements

Self-Hosted

Keep your MeshMap designs internal to your workplace. Get remote support from Layer5 when you need it.

Reference

Low-level ReST API reference for extending Layer5 Cloud.

Meshmap Docs

Getting Started with Designs

• Starting from a pattern: A Pattern is an entity that augments the operational behavior of a deployed instance of a Design.
• Creating Relationships: Relationships identify and facilitate genealogy between Components.
• Working with Components: Components represent entities in the Meshery ecosystem, exposing capabilities of the underlying platform.
• Starting from scratch: Emphasiz the underlying system behavior for each action you take.

Exploring Designer

• Reviewing Designs: Learn how to leverage comments in MeshMap’s Designer Mode to enhance collaboration and streamline design reviews.
• Whiteboarding: Whiteboarding and Freestyle Drawing inside meshmap
• Export Designs: How to export your designs for backup , sharing or offline use.

Working with Components

Meshery Designs are descriptive, declarative characterizations of how your Kubernetes infrastructure should be configured

Navigating Visualizer

Visualizer mode is for operating your Kubernetes clusters and cloud native infrastructure.

Core Tasks

• Whiteboarding: MeshMap Designer supports freestyle design, meaning that you can customize the appearance and layout of your diagrams without any constraints.

• Deploying Designs: Validating Designs, Undeploying Designs, Deploying Designs, Cloning a Design

Reference

• Keyboard Shortcuts: Learn the keyboard shortcuts for Meshmap to enhance your designing experience.

• Troubleshooting MeshMap: Learn to Troubleshoot the MeshMap

Contribution Guidelines

A detailed contribution guide for Layer5 Docs. Contributing to the docs.layer5.io

Editing Markdown Content

Documentation content is written in Markdown and you'll find all files listed under the /content directory.

To create a new page with Markdown, create a file ending in .md in a site/<subdirectory>. The path in the content directory will be the URL route. For example, site/docs/hello.md will be served from the /docs/hello URL.

---
title: 'My Title'
description: "A thorough, yet succinct description of the page's contents"
---

The significant keys in the YAML frontmatter are:

title (string) - This is the title of the page that will be set in the HTML title. description (string) - This is a description of the page that will be set in the HTML description. permalink (string - relative file path) - canonical location of the page category (string) - section to which the page belongs. redirect_from (string - relative file path) - in case the page was previously available elsewhere

Uploading Images to the site

To display images in a pop-up modal, use the following syntax: ![alt text](/path/to/image.svg).

Note-> For images to show correctly on subpages, always provide the complete image path

Adding Alert to the site

Use the following Syntax to add a Alert: {{< alert type="success" title="Note" >}} Your Note {{< /alert >}}

• type="danger": Alert used to indicate something related to security.
• type="info": Alert used to write some information.
• type="warning": Alert used to indicate a warning that might need attention.
• type="note": Alert used to indicate a neutral information.
• type="success": Alert used to indicate a positive information.

By default, if you don't specify a title title="Your Title", the title will be the same as the type name.

Note-> Using the wrong type will lead to the use of the default alert i.e. success

Our projects are community-built and welcome collaboration. 👍 Be sure to see the Layer5 Community Welcome Guide for a tour of resources available to you and jump into our Slack!

Find your MeshMate

MeshMates are experienced Layer5 community members, who will help you learn your way around, discover live projects and expand your community network. Become a Meshtee today!

✔️ Join any or all of the weekly meetings on community calendar.
✔️ Watch community meeting recordings.
✔️ Access the Community Drive by completing a community Member Form.
✔️ Discuss in the Community Forum.
✔️Explore more in the Community Handbook.

Not sure where to start? Grab an open issue with the help-wanted label.