Landscape2 CLI

The Overlay feature allows you to apply different data sources to an existing landscape at runtime using WASM. This is useful for previewing changes to settings, data, or logos without a full rebuild.

Enable the overlay by adding any of the following query parameters to your landscape URL:

Note: This feature is experimental.

After building your landscape, use the serve subcommand to launch a local HTTP server to preview the static website.

landscape2 serve --landscape-dir build

The server typically runs at http://127.0.0.1:8000.

Landscape2 is distributed as a container image. This image is suitable for:

• Running the tool locally.
• Automating landscape generation in CI workflows.
• Using with the landscape2-validate-action to verify landscape data, settings, and guide files.

By default, the development server loads datasets and assets from ui/webapp/static. To develop against data from a live landscape (e.g., https://landscape.cncf.io), you must configure a proxy target in a local environment file.

1. Copy the example environment file: cp ui/webapp/.env.local.example ui/webapp/.env.local.
2. Set the VITE_PROXY_TARGET variable in ui/webapp/.env.local to the desired landscape URL.
3. Restart the development server for changes to take effect.

Note: The proxy only handles datasets, documents, images, and logos during development. Production builds are not affected by this setting. To revert to using local generated assets, remove the VITE_PROXY_TARGET variable.

VITE_PROXY_TARGET=https://landscape.cncf.io

The output of the build command is a Single-Page Application (SPA). When deploying to a web server or hosting provider (like GitHub Pages), you must ensure that all routes are handled by index.html to support client-side routing.

Deployment Tips:

• GitHub Pages: A common pattern is to copy index.html to 404.html so that the server serves the app when a non-existent path is requested.
• Subpaths: If hosting in a subpath (e.g., example.com/landscape/), you must set the base_path field in your settings.yml file to match that subpath.

The web application is built with SolidJS and uses Vite. To set up the development environment, install the dependencies and start the Vite development server from the repository root using yarn with the --cwd flag pointing to ui/webapp.

yarn --cwd ui/webapp install
yarn --cwd ui/webapp dev

Use the new subcommand to generate a new landscape directory populated with a built-in template. This template includes sample data source files (data.yml, settings.yml, guide.yml) to serve as a starting point.

landscape2 new --output-dir my-landscape

You can embed specific categories or subcategories of your landscape into external websites.

1. Visit the /embed-setup path on your hosted landscape website (e.g., https://landscape.cncf.io/embed-setup).
2. Use the provided UI to customize the view.
3. Copy the generated embed code.

Advanced Embedding: You can also use iframe-resizer by adding iframe-resizer=true to the embed URL.

The build subcommand generates the static website files from your data sources.

Key considerations:

• Screenshots: If settings.yml contains screenshot settings, landscape2 will attempt to take a screenshot using headless Chrome/Chromium. If not available, a warning will be raised.
• External Data: Without credentials for GitHub and Crunchbase, the build will proceed but will skip collecting data from those services (indicated by WARN messages).
• Caching: To speed up subsequent builds (especially when processing many logos or external data), use the --cache-dir flag and ensure this directory is persisted across runs in your CI/CD workflows.

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

The Landscape guide is defined in a YAML file (typically guide.yml). The data structure consists of a list of categories, each containing optional content (Markdown), keywords, and a list of subcategories. Each subcategory must have content (Markdown) and can optionally have keywords.

When the guide is loaded, the content fields are automatically converted from Markdown to HTML.

# Example guide.yml structure
categories:
  - category: "Cloud Native"
    content: "# Introduction to Cloud Native"
    keywords: ["cloud", "native"]
    subcategories:
      - subcategory: "Containers"
        content: "Information about containers."
        keywords: ["docker", "container"]