Skip to main content

Shakudo Sync

Overview​

Shakudo Sync is an administrative feature that enables synchronization and migration of applications between different Dify instances. It provides a centralized interface for importing Dify AI applications from a source Dify instance (exporter) to a target Dify instance (importer), making it easy to manage and replicate Dify apps across different environments.

The feature performs health checks on both the source and target Dify instances, displays available applications from the source instance, and allows administrators to selectively import applications with real-time status tracking.

Access & Location​

  • Route: ?panel=shakudo-sync
  • Navigation: Admin → Shakudo Sync
  • Access Requirements:
    • dashboard-admin role (RBAC level 0)
    • Must be a Keycloak admin or have admin privileges
  • Feature Flags: shakudoSyncEnabled must be enabled in platform parameters

Key Capabilities​

Health Monitoring​

Automatically checks the connectivity and health status of both the exporter (source) and importer (target) Dify instances. Displays connection status with visual indicators (check mark for healthy, X for unhealthy) and provides the URLs of both instances.

Application Discovery​

Fetches and displays all available Dify applications from the source instance, including application metadata such as name, icon, mode, creation date, last update timestamp, and previous import history.

Selective Import​

Allows administrators to select specific applications for import, either individually or in bulk using a "Select All" checkbox. The interface provides granular control over which applications to migrate.

Batch Import Operations​

Supports importing multiple applications simultaneously with parallel processing. Each import operation is tracked independently with loading states, success confirmations, and error handling.

Import History Tracking​

Displays the timestamp and ID of the most recent successful import for each application, allowing administrators to track when applications were last synchronized.

User Interface​

Main View​

The main panel displays a grid layout with cards for different sync integrations. Currently, only Dify integration is implemented, showing:

  • Dify logo and branding
  • Health status indicator (loading, healthy, or error state)
  • Source Dify instance URL
  • Clickable card to open the import dialog

Dialogs & Modals​

  1. Import Dify Apps Dialog
    • Purpose: Display available Dify applications and manage import operations
    • Fields:
      • Select All checkbox with application count
      • Source/Target Dify instance URLs
      • Individual application cards with selection checkboxes
    • Actions:
      • Select/deselect individual applications
      • Select/deselect all applications
      • Import selected applications
      • Cancel operation

Application Cards​

Each application card displays:

  • Columns/Information:
    • Application icon (emoji or default robot icon)
    • Application name (truncated with ellipsis if too long)
    • Application mode (e.g., chat, workflow)
    • Application ID (first 8 characters, linked to source Dify instance)
    • Created timestamp (formatted as YYYY-MM-DD HH:mm:ss)
    • Updated timestamp (formatted as YYYY-MM-DD HH:mm:ss)
    • Latest Import timestamp (when last synchronized)
    • Latest Imported App ID (linked to target Dify instance)
  • Actions:
    • Checkbox for selection
    • Loading spinner during import
    • Link to view app in source Dify instance
    • Link to view imported app in target Dify instance
  • Filtering: None (displays all available applications)

Technical Details​

API Endpoints​

Health Check:

  • GET /api/shakudo-sync/importer/apps/dify/health
    • Checks connectivity to both exporter and importer Dify instances
    • Returns status, URLs, and error messages for both instances
    • Backend service: http://shakudo-sync-importer.hyperplane-core:8000/v1/dify/health

Fetch Applications:

  • GET /api/shakudo-sync/importer/apps/dify/fetch-apps
    • Retrieves list of all available Dify applications from source instance
    • Returns application metadata including name, icon, mode, timestamps, and sync history
    • Backend service: http://shakudo-sync-importer.hyperplane-core:8000/v1/dify/apps

Import Application:

  • POST /api/shakudo-sync/importer/apps/dify/import-app
    • Imports a single Dify application by ID
    • Request body: { id: string }
    • Backend service: http://shakudo-sync-importer.hyperplane-core:8000/v1/dify/apps/migrate

Latest Sync Info:

  • GET /api/shakudo-sync/importer/apps/dify/latest-sync?id={app_id}
    • Retrieves the most recent import timestamp and ID for a specific application
    • Backend service: http://shakudo-sync-importer.hyperplane-core:8000/v1/dify/apps/{id}/latest_sync

Component Structure​

  • Main Component: components/ShakudoSync/Panel.tsx
  • App Container: components/ShakudoSync/Apps/AppContainer.tsx
  • Dify Integration:
    • components/ShakudoSync/Apps/Dify/DifySyncContainer.tsx - Main Dify card
    • components/ShakudoSync/Apps/Dify/DifySyncDialog.tsx - Import dialog
    • components/ShakudoSync/Apps/Dify/DifyHealthCheck.tsx - Health status display
    • components/ShakudoSync/Apps/Dify/DifyAllAppsGrid.tsx - Application list
    • components/ShakudoSync/Apps/Dify/DifyAppCard.tsx - Individual app card
    • components/ShakudoSync/Apps/Dify/DifyAppCardLatestImport.tsx - Import history display
    • components/ShakudoSync/Apps/Dify/DifySyncAppsButton.tsx - Import action button
    • components/ShakudoSync/Apps/Dify/DifyExporterTitle.tsx - Source/target URL display
  • State Management: components/ShakudoSync/atoms.ts

State Management (Jotai Atoms)​

ExporterDetails

  • Stores health status, URL, and error messages for the source Dify instance
  • Fields: { health: boolean | null, url: string, message: string }

ImporterDetails

  • Stores health status, URL, and error messages for the target Dify instance
  • Fields: { health: boolean | null, url: string, message: string }

SelectedDifyApps

  • Array of selected application IDs for import
  • Type: string[]

AllDifyAppsSelected

  • Boolean flag indicating whether all applications are selected
  • Type: boolean

AllDifyApps

  • Array of all available Dify applications from the source instance
  • Type: Array<DifyApp>

AppSyncStatesAtom

  • Reducer-based atom tracking the sync state of each application
  • States per application:
    • loading: Import operation in progress
    • success: Import completed successfully
    • error: Import failed with error details
    • latest_sync_attempt: Timestamp of most recent sync attempt

Backend Service​

The feature relies on a microservice called shakudo-sync-importer running in the hyperplane-core namespace on port 8000. This service handles the actual communication with both Dify instances and performs the application migration logic.

Common Workflows​

Importing Dify Applications​

  1. Navigate to Admin → Shakudo Sync in the dashboard sidebar
  2. Wait for health checks to complete (green check mark indicates healthy connection)
  3. Click on the Dify card to open the Import dialog
  4. Review the source and target Dify instance URLs at the top of the dialog
  5. Select individual applications by clicking their checkboxes, or click "Select All" to choose all applications
  6. Review the application details (name, mode, creation date, last sync date)
  7. Click the "Import" button to begin the import process
  8. Monitor the import progress (loading spinners appear on selected apps)
  9. Wait for import completion notifications:
    • Success: "Imported all selected apps successfully!"
    • Partial success: "Imported X apps successfully. Failed to sync Y apps."
    • Failure: "Failed to import any of the selected apps."
  10. Check the "Latest Import" column to verify successful imports
  11. Click the app ID links to view the imported applications in the target Dify instance

Checking Import History​

  1. Open the Shakudo Sync panel
  2. Click on the Dify card to open the dialog
  3. Review the "Latest Import" column for each application
  4. The timestamp shows when the application was last imported
  5. The "Latest Imported App" link (app ID) navigates to the imported app in the target Dify instance

Troubleshooting Connection Issues​

  1. Open the Shakudo Sync panel
  2. Check the health status indicator on the Dify card
  3. If the indicator shows an X (unhealthy):
    • Hover over the X icon to see the error message
    • Verify the source Dify URL is accessible
    • Contact the administrator to check the shakudo-sync-importer service
  4. Review the source URL displayed below the health indicator
  5. Ensure both exporter and importer Dify instances are running and accessible
  • Stack Components - For managing other platform integrations
  • Service Accounts - For authentication credentials used by the sync service
  • Secrets - For storing Dify API keys and connection credentials

Notes & Tips​

  • The feature currently supports only Dify application synchronization, but the architecture is designed to support additional integration types in the future
  • Import operations are performed in parallel for better performance when selecting multiple applications
  • The sync service maintains a history of imports, allowing you to track when each application was last synchronized
  • Application IDs are truncated to 8 characters in the UI but full IDs are used for operations
  • The dialog automatically resets selected applications when closed and reopened
  • Failed imports do not prevent other imports from completing - each import operation is independent
  • Health checks are performed automatically when opening the panel
  • The feature uses the shakudo-sync-importer microservice which must be running and properly configured for the feature to work
  • Application icons default to a robot emoji if the source application doesn't have a custom icon or emoji
Last updated on by chyuen-devsentient