1 Star 0 Fork 0

CNCF/landscape2

Create your Gitee Account
Explore and code with more than 12 million developers,Free private repositories !:)
Sign up
Clone or Download
contribute
Sync branch
Cancel
Notice: Creating folder will generate an empty file .keep, because not support in Git
Loading...
README
Apache-2.0

Landscape2

Landscape2 is a tool that generates interactive landscapes websites.

You can check out how the generated landscapes look like by visiting the CNCF landscape. Additional landscapes generated by this tool can be found in the landscape2-sites repository.

[!WARNING] Landscape2 is at an early stage of development. There may be breaking changes in the future to the command usage, flags, and configuration file formats.


How it works

Landscape2 is a CLI tool that generates static websites from the information available in the data sources provided. These data sources are passed to the tool via arguments, usually in the form of urls or local paths, and are as follows:

  • Landscape data. The landscape data file is a YAML file that describes the items that will be displayed in the landscape website. For more information, please see the reference documentation.

  • Landscape settings. The settings file is a YAML file that allows customizing some aspects of the generated landscape website, such as the logo, colors, how to group items or which ones should be featured. For more information about the settings file, please see the reference documentation.

  • Landscape guide. The guide file is a YAML file that defines the content of the guide that will be displayed on the landscape website. For more information, please see the reference documentation.

  • Landscape games. The games data file is a YAML file that defines the content of the games that will be displayed on the landscape website. For more information, please see the reference documentation.

  • Logos location. Each landscape item must provide a valid relative reference to a logo image in SVG format in the landscape data file (item's logo field). The logos data source defines the location of those logos (base url or local path), so that the tool can get them as needed when processing the landscape items.

Data collection from external services

In addition to the information available in the landscape data file, the tool collects more data during the landscape generation from external sources (such as GitHub or Crunchbase) if the required credentials are provided. These credentials must be provided via environment variables.

  • GitHub: a list of comma separated GitHub tokens with public_repo scope can be provided in the GITHUB_TOKENS environment variable. When these tokens are not provided no information from GitHub will be collected. If the expected number of items in the landscape is large it is recommended to provide more than one token to avoid hitting rate limits and speed up the collection of data (the concurrency of the process will be based on the number of tokens provided).

  • Crunchbase: a Crunchbase API key can be provided in the CRUNCHBASE_API_KEY environment variable. If this token is not provided no information from Crunchbase will be collected. Please note that landscape2 needs access to the full Crunchbase API, which requires an Enterprise or Application license.

Installation

Pre-built binaries

Binary downloads of the landscape2 CLI tool can be found in the releases page.

Install via Homebrew

brew install cncf/landscape2/landscape2

Install via shell script

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/cncf/landscape2/releases/download/v0.10.0/landscape2-installer.sh | sh

Install via powershell script

irm https://github.com/cncf/landscape2/releases/download/v0.10.0/landscape2-installer.ps1 | iex

Container image

The landscape2 CLI tool is also distributed in a container image. This image can be used both to run the tool locally or from your CI workflows to automate the generation of landscapes. The landscape2-validate-action, which can be used to check that the landscape data, settings and guide files are valid, also uses this image.

Building from source

You can build landscape2 from the source by using Cargo, the Rust package manager. wasm-pack is required to build the wasm modules. yarn is also required during the installation process to build the web application, which will be embedded into the landscape2 binary as part of the build process.

cargo install --git https://github.com/cncf/landscape2
landscape2 --help

Landscape2 CLI tool

https://github.com/cncf/landscape2#usage

Usage: landscape2 <COMMAND>

Commands:
  build     Build landscape website
  deploy    Deploy landscape website (experimental)
  new       Create a new landscape from the built-in template
  serve     Serve landscape website
  validate  Validate landscape data sources files
  help      Print this message or the help of the given subcommand(s)

Usage

To see landscape2 in action, we will go through the process of creating, building and serving a new landscape from scratch. The following instructions will assume that the landscape2 binary is available in your PATH. Alternatively, you can launch a container from the image provided where the landscape2 CLI tool is ready to use.

Creating a new landscape

The new subcommand allows us to create a new landscape from a built-in template. This template includes some sample data source files that you can use as a starting point for your landscapes.

The following command will create the directory my-landscape if it doesn't already exist and will copy into it the files in the built-in template:

landscape2 new --output-dir my-landscape
INFO new: landscape2::new: creating new landscape from the built-in template..
INFO new: landscape2::new: landscape created! (took: 0.003s)

✅ Landscape created successfully!

You can build it by running the following command from the `my-landscape` directory:

👉 landscape2 build --data-file data.yml --settings-file settings.yml --guide-file guide.yml --logos-path logos --output-dir build

Building the landscape website

The build process is in charge of generating the landscape website from the information available in the data sources provided. Now we'll build the landscape we created in the previous step by using the build subcommand. Please note that the new subcommand already suggested us to do this in its output and even printed the full command to use for us.

[!NOTE] During the build process, landscape2 will try to take a screenshot of your landscape if the required settings were provided in the settings.yml file. This screenshot will be available for download from the generated web application (in PNG and PDF format), and is taken by launching Chrome/Chromium in headless mode. If Chrome/Chromium is not available, the screenshot won't be taken and a warning will be raised.

The following command will build the landscape and write the resulting files to the output-dir provided (build in this case):

cd my-landscape
landscape2 build \
  --data-file data.yml \
  --settings-file settings.yml \
  --guide-file guide.yml \
  --logos-path logos \
  --output-dir build
INFO build: landscape2::build: building landscape website..
WARN build:collect_crunchbase_data: landscape2::build::crunchbase: crunchbase api key not provided: no information will be collected from crunchbase
WARN build:collect_github_data: landscape2::build::github: github tokens not provided: no information will be collected from github
INFO build: landscape2::build: landscape website built! (took: 0.555s)

✅ Landscape built successfully!

You can see it in action by running the following command:

👉 landscape2 serve --landscape-dir build

[!IMPORTANT] Without the credentials required to collect data from external services (GitHub and Crunchbase) the resulting site won't contain all the information available on the CNCF demo site. In this case, we didn't provide them intentionally, so we were warned about it in the command output (see WARN entries).

Serving a landscape

The result of the build process is a static website that you can deploy on your favorite hosting provider. To make it easier to try your landscapes, landscape2 includes a serve subcommand that will launch an HTTP server and serve the contents of your landscape. In our example, the build output displayed the command to do this, so we'll go ahead and give it a try:

landscape2 serve --landscape-dir build
INFO serve: landscape2::serve: http server running (press ctrl+c to stop)

🔗 Landscape available at: http://127.0.0.1:8000

If you visit http://127.0.0.1:8000 in your browser you should see the landscape you just created in action. Now you can iterate by editing the files in the my-landscape directory until your landscape is ready.

One option to serve your landscape in production is to use a static site hosting service like GitHub Pages. In this repository you can find a full example of a landscape generated by the landscape2 new command that is automatically built and deployed to GitHub pages (using the build branch) on every commit to the main branch. Please note that the sample workflow used to build and deploy requires write permissions.

[!NOTE] The resulting website when building a landscape is a single-page application that handles routing on the client side. This means that you'll need to configure your webserver to serve the index.html file for the SPA route paths (like '/guide', '/stats', etc). One way of doing this would be to serve that file when a non existent path is requested. The serve subcommand included in landscape2 already handles this for us. In the GitHub pages example mentioned above, this is achieved by copying the content of the index.html file to the 404.html file, which will be served when a non existent path is requested.

Validating data, settings and guide files

The landscape2 CLI tool includes a subcommand named validate that allows you to check that your landscape data, settings and guide files are valid. If you are interested in integrating this validation in your CI workflows (i.e. to enforce that those files are valid before merging a PR), please take a look at the landscape2-validate-action.

landscape2 validate settings --settings-file cncf/settings.yml

Error: the landscape settings file provided is not valid

Caused by:
    0: the landscape settings file provided is not valid
    1: color1 is not valid (expected format: "rgba(0, 107, 204, 1)")

Performance considerations when building

Some operations like collecting data from external sources or processing a lot of logos images can take some time, specially in landscapes with lots of items. Landscape2 caches as much of this data as possible to make subsequent runs faster. Please keep this in mind when running the tool periodically from your workflows, and make sure the cache directory (set via --cache-dir) is saved and restored on each run. You can find some examples of how to achieve this in the workflows in the landscape2-sites repository.

Embeddable views

Landscape2 allows other websites to embed a view to display the items in a category or subcategory. The embed code can be easily obtained from the corresponding landscape website by visiting /embed-setup (i.e. in the case of the CNCF landscape, the url would be https://landscape.cncf.io/embed-setup). The customization options available can be adjusted as needed, and the generated embed code will be updated accordingly.

embed-setup

[!NOTE] In addition to the customization options available in the embed setup view, it's also possible to embed views using iframe-resizer. This feature can be enabled by adding iframe-resizer=true to the embed url (demo).

Overlay

Landscape2 supports applying one or more data source files to an existing landscape at runtime. Any of those files can -and often will- be different than the ones used originally to build the landscape. This feature aims to be the building blocks of a preview system.

Some examples of it in action (live demos!):

To achieve this, the overlay redoes part of the landscape build process in the browser, reusing the same codebase packed as a WASM module.

The overlay can be enabled by providing any of the following query parameters to the landscape url (they can be combined if needed):

  • overlay-data: data file url
  • overlay-settings: settings file url
  • overlay-guide: guide file url
  • overlay-games: games data file url
  • overlay-logos: logos base url

[!WARNING] The overlay feature is still experimental and may not work as expected in all cases. Please report any issues you find!

Adopters

A list of landscapes built using landscape2 is available at ADOPTERS.md. Please consider adding yours!

Contributing

Please see CONTRIBUTING.md for more details.

Code of Conduct

This project follows the CNCF Code of Conduct.

License

Landscape2 is an Open Source project licensed under the Apache License 2.0.

Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

About

Landscape2 is a tool that generates interactive landscapes websites expand collapse
Apache-2.0
Cancel

Releases

No release

Contributors

All

Activities

Load More
can not load any more
马建仓 AI 助手
尝试更多
代码解读
代码找茬
代码优化
1
https://gitee.com/cncf/landscape2.git
git@gitee.com:cncf/landscape2.git
cncf
landscape2
landscape2
main

Search