Skip to main content

Apps Catalogue (Stack Components Directory)

Overview​

The Apps Catalogue (also known as Stack Components Directory) is a browsable directory of pre-configured data tools and applications available for one-click installation in the Shakudo platform. This feature provides administrators with a visual catalogue of stack components (like databases, analytics tools, workflow orchestrators, etc.) that can be automatically deployed to the platform with minimal configuration. Each component is presented as a card with its logo, category, installation status, and an install action button.

Access & Location​

  • Route: ?panel=apps-catalogue
  • Navigation: Admin → Stack Components Catalogue
  • Access Requirements: dashboard-admin role
  • Feature Flags: selfInstalledAppsEnabled must be enabled

Key Capabilities​

Browse Available Stack Components​

Users can explore a visual catalogue of pre-configured data science and analytics tools, each represented by a card showing the tool's name, logo, category, and current installation status. The catalogue includes components ranging from databases to workflow orchestrators to visualization tools.

One-Click Installation​

For components marked as "CATALOGUED" (ready to install), administrators can install them with a single click. The system automatically creates a dedicated namespace (hyperplane-auto-{component-name}), configures necessary metadata, and initiates the Helm chart deployment without requiring manual configuration.

Search and Filter by Category​

The interface provides a search bar for finding specific stack components by name, and a category filter menu that allows filtering components by their functional category (e.g., databases, workflows, visualization, etc.). This makes it easy to discover relevant tools in large catalogues.

Monitor Installation Status​

Each component card displays its current installation status (CATALOGUED, SCALING, ACTIVE, PAUSED, ARCHIVED, etc.), allowing administrators to track which components are installed, which are being deployed, and which are available for installation.

User Interface​

Main View​

The panel features a two-column layout:

Left Sidebar (Filter Panel):

  • Search text field with search icon for filtering components by name
  • Category filter menu listing all available categories with an "All" option
  • Categories are dynamically populated based on available apps

Main Content Area:

  • Title: "Stack Component Directory"
  • Grid of app cards (responsive: 3 cards per row on desktop, 1 on mobile)
  • Each card displays:
    • Component logo/icon with background color
    • Component name
    • Category label
    • Install/status button in bottom-right corner
  • Loading indicator appears during data fetches

Dialogs & Modals​

  1. Installation Confirmation Dialog
    • Purpose: Confirm installation of a stack component before proceeding
    • Title: "Install {App Name}"
    • Prompt: "Are you sure you want to install '{App Name}'?"
    • Actions: Cancel or Install
    • Automatically displays success notification with namespace information after installation

Installation States & Actions​

Component Install States:

  1. CATALOGUED - Ready to install, shows "Install" button (blue, contained style)
  2. SCALING - Currently installing, shows "Scaling" button (disabled, loading spinner)
  3. ACTIVE - Installed and running, shows "Pause" button (outlined style)
  4. PAUSED - Installed but scaled down, shows "Activate" button (blue, contained style)
  5. PAUSING - Currently scaling down, shows "Pausing" button (disabled, loading spinner)
  6. ARCHIVED - Not auto-installable, requires manual configuration (disabled)
  7. UNKNOWN - Status cannot be determined (disabled)
  8. UNAVAILABLE - Deprecated status, component not available (disabled)

Special Cases:

  • Components in category "Shakudo Core" cannot be installed or uninstalled through this interface
  • Install buttons are disabled during state transitions (SCALING, PAUSING)
  • Hover tooltips provide detailed status explanations and namespace information

Technical Details​

GraphQL Operations​

Queries:

  • getCatalogue - Retrieves the list of all available stack components from the catalogue with their current installation status, category, description, Helm chart info, license details, and image metadata. Supports filtering by name and category. Uses polling interval of 5000ms for real-time status updates.

Mutations:

  • installOnePlatformApp - Creates and installs a new platform app from the catalogue. Takes PlatformAppCreateInput which includes name, namespace, component label, category, tooltip description, image details, and license information. Automatically generates namespace as hyperplane-auto-{app-name}.

Subscriptions: None

Component Structure​

  • Main Component: /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/PlatformAppsCatalogue/PlatformAppsCataloguePanel.tsx
  • Grid View: /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/PlatformAppsCatalogue/PlatformAppsCatalogueGrid.tsx
  • App Cards: /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/PlatformAppsCatalogue/PlatformAppCatalogueCard.tsx
  • Install Component: /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/PlatformAppsCatalogue/PlatformAppsCatalogueInstall.tsx
  • Category Filter: /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/PlatformAppsCatalogue/PlatformCatalogueCategoryFilterMenu.tsx
  • Utility Functions: /root/gitrepos/monorepo/apps/hyperplane-dashboard/components/PlatformAppsCatalogue/getInstallStateDescription.ts

State Management​

  • Uses Jotai atom PlatformAppPageAtom for managing selected platform app state
  • Local component state for search query and selected category filter
  • Apollo Client cache for GraphQL query data with 5-second polling interval

Common Workflows​

Installing a New Stack Component​

  1. Navigate to Admin → Stack Components Catalogue
  2. Browse available components or use search/filter to find desired tool
  3. Locate component card showing "Install" button (must be in CATALOGUED state)
  4. Click "Install" button on the component card
  5. Confirm installation in the dialog that appears
  6. System displays success notification showing the installation namespace
  7. Component status changes to "SCALING" with loading spinner
  8. Wait for installation to complete (status will change to "ACTIVE")
  9. Component becomes available in the main Stack Components panel for configuration and management

Finding Components by Category​

  1. Open the Apps Catalogue panel
  2. Look at the category filter menu in the left sidebar
  3. Click on a category name (e.g., "Databases", "Workflows", "Visualization")
  4. The grid refreshes to show only components in that category
  5. Click "All" to remove category filter and see all components again

Searching for Specific Tools​

  1. Open the Apps Catalogue panel
  2. Type component name in the search field at top-left
  3. Results filter in real-time as you type
  4. Combine with category filter for more refined searches
  5. Clear search field to see all results again
  • Stack Components - Manage installed stack components (view details, pause/activate, configure, uninstall)
  • Platform Apps Management - Configure installed applications with Helm values and custom settings
  • Namespace Management - View and manage Kubernetes namespaces where components are deployed

Notes & Tips​

Installation Behavior:

  • All catalogue installations automatically create namespaces with the pattern hyperplane-auto-{component-name}
  • Component labels are automatically set as hyperplane.dev/app-name={component-name}
  • Installation success messages include the target namespace for reference
  • Components marked as "Shakudo Core" cannot be uninstalled as they are essential platform services

Status Monitoring:

  • The catalogue polls for updates every 5 seconds to keep installation states current
  • During installation (SCALING state), the install button shows a loading spinner and is disabled
  • ACTIVE components can be paused/scaled down from the main Stack Components panel
  • If a component shows UNKNOWN or UNAVAILABLE status, contact Shakudo support

Search & Filter Best Practices:

  • Use search for specific tool names (e.g., "PostgreSQL", "Airflow")
  • Use category filter to discover tools by function (e.g., all databases, all ML tools)
  • Combine search and filter for precise results (e.g., search "flow" within "Workflows" category)
  • Category list is dynamic and only shows categories present in the current catalogue

Permissions:

  • Only users with dashboard-admin role can access the Apps Catalogue
  • The selfInstalledAppsEnabled feature flag must be enabled at the platform level
  • Installation permissions are checked at the component level (some may require additional permissions)
  • Components in "Archived" state require manual intervention from Shakudo support to install

Component Lifecycle:

  • CATALOGUED → SCALING (installation in progress) → ACTIVE (running)
  • ACTIVE → PAUSING (scaling down) → PAUSED (scaled to zero)
  • PAUSED → SCALING (scaling up) → ACTIVE (running again)
  • Archived components cannot be installed through this interface (require manual configuration)
Last updated on by chyuen-devsentient