feat: update install and setup wizard flows

Author: zhaojing1987

apphub/src/api/v1/routers/auth.py

@@ -72,11 +72,21 @@ def check_embedded_gateway_access(
     if not status_payload["enabled"]:
         return Response(status_code=204)
 
+    if status_payload.get("cloud_marketplace_setup_pending") and status_payload.get("initialization_required"):
+        return Response(
+            status_code=403,
+            headers={"X-Websoft9-Setup-Route": "/setup"},
+        )
+
     if status_payload["initialization_required"]:
-        raise CustomException(
+        if status_payload.get("cloud_marketplace_setup"):
+            return Response(
+                status_code=403,
+                headers={"X-Websoft9-Setup-Route": "/setup"},
+            )
+        return Response(
             status_code=403,
-            message="Product Authentication Setup Required",
-            details="Initialize the product operator account before opening embedded workspaces",
+            headers={"X-Websoft9-Setup-Route": "/auth/setup"},
         )
 
     if not status_payload["authenticated"]:

apphub/src/api/v1/routers/setup_wizard.py

@@ -0,0 +1,85 @@
+from typing import Optional
+
+from fastapi import APIRouter, Cookie, Query
+
+from src.core.exception import CustomException
+from src.schemas.errorResponse import ErrorResponse
+from src.schemas.setupWizard import (
+    SetupWizardAppResponse,
+    SetupWizardCompleteResponse,
+    SetupWizardInstallAcceptedResponse,
+    SetupWizardInstallRequest,
+    SetupWizardInstallStatusResponse,
+    SetupWizardPlatformInitCompleteResponse,
+    SetupWizardStateResponse,
+)
+from src.services.product_auth import PRODUCT_AUTH_COOKIE_NAME
+from src.services.setup_wizard import SetupWizardService
+
+router = APIRouter()
+
+
+@router.get(
+    "/setup-wizard/state",
+    summary="Get setup wizard state",
+    responses={200: {"model": SetupWizardStateResponse}, 400: {"model": ErrorResponse}, 500: {"model": ErrorResponse}},
+)
+def get_setup_wizard_state(
+    session_token: Optional[str] = Cookie(default=None, alias=PRODUCT_AUTH_COOKIE_NAME),
+):
+    return SetupWizardService().get_state(session_token=session_token)
+
+
+@router.get(
+    "/setup-wizard/app",
+    summary="Get marketplace app metadata",
+    responses={200: {"model": SetupWizardAppResponse}, 400: {"model": ErrorResponse}, 404: {"model": ErrorResponse}, 500: {"model": ErrorResponse}},
+)
+def get_setup_wizard_app(
+    locale: str = Query("en", regex="^(zh|en)(-[A-Za-z]{2})?$"),
+):
+    return SetupWizardService().get_app(locale)
+
+
+@router.post(
+    "/setup-wizard/platform-init-complete",
+    summary="Advance setup wizard after platform initialization",
+    responses={200: {"model": SetupWizardPlatformInitCompleteResponse}, 401: {"model": ErrorResponse}, 500: {"model": ErrorResponse}},
+)
+def complete_platform_initialization(
+    session_token: Optional[str] = Cookie(default=None, alias=PRODUCT_AUTH_COOKIE_NAME),
+):
+    return SetupWizardService().mark_platform_init_complete(session_token=session_token)
+
+
+@router.post(
+    "/setup-wizard/install",
+    summary="Start marketplace app installation",
+    responses={200: {"model": SetupWizardInstallAcceptedResponse}, 400: {"model": ErrorResponse}, 401: {"model": ErrorResponse}, 500: {"model": ErrorResponse}},
+)
+def install_marketplace_app(
+    payload: SetupWizardInstallRequest,
+    endpointId: int = Query(None, description="Endpoint ID to install app on, if not set install on the local endpoint"),
+    session_token: Optional[str] = Cookie(default=None, alias=PRODUCT_AUTH_COOKIE_NAME),
+):
+    return SetupWizardService().install_app(payload.model_dump(), session_token=session_token, endpoint_id=endpointId)
+
+
+@router.get(
+    "/setup-wizard/install/{tracking_id}",
+    summary="Get marketplace app installation status",
+    responses={200: {"model": SetupWizardInstallStatusResponse}, 404: {"model": ErrorResponse}, 500: {"model": ErrorResponse}},
+)
+def get_marketplace_app_install_status(tracking_id: str):
+    return SetupWizardService().get_install_status(tracking_id)
+
+
+@router.post(
+    "/setup-wizard/complete",
+    summary="Mark setup wizard complete",
+    responses={200: {"model": SetupWizardCompleteResponse}, 400: {"model": ErrorResponse}, 401: {"model": ErrorResponse}, 500: {"model": ErrorResponse}},
+)
+def complete_setup_wizard(
+    session_token: Optional[str] = Cookie(default=None, alias=PRODUCT_AUTH_COOKIE_NAME),
+):
+    return SetupWizardService().complete(session_token=session_token)

apphub/src/cli/apphub_cli.py

@@ -8,6 +8,7 @@
 
 import click
 from src.core.runtime_paths import resolve_apphub_config_path
+from src.services.marketplace_bootstrap import MarketplaceBootstrapService
 from src.services.product_metadata import write_product_edition
 from src.services.settings_manager import SettingsManager
 from src.services.product_auth import ProductAuthService
@@ -86,6 +87,18 @@ def setedition(edition_key):
     except Exception as e:
         raise click.ClickException(str(e))
 
+
+@cli.command()
+@click.option('--app-slug', required=True, help='Marketplace app slug')
+@click.option('--default-locale', required=True, type=click.Choice(['en', 'zh-CN'], case_sensitive=True), help='Default setup locale')
+def setmarketplace(app_slug, default_locale):
+    """Set marketplace bootstrap metadata"""
+    try:
+        payload = MarketplaceBootstrapService().write(app_slug=app_slug, default_locale=default_locale)
+        click.echo(json.dumps(payload, ensure_ascii=False))
+    except Exception as e:
+        raise click.ClickException(str(e))
+
 @cli.command()
 @click.argument('target', required=True, type=click.Choice(['apps'], case_sensitive=False))
 @click.option('--channel', type=click.Choice(['release', 'rc', 'dev'], case_sensitive=False), help='Upgrade using the specified artifact channel')

apphub/src/main.py

@@ -18,6 +18,7 @@
 from src.api.v1.routers import backup as api_backup
 from src.api.v1.routers import compose_app as api_compose_app
 from src.api.v1.routers import appstore_sync as api_appstore_sync
+from src.api.v1.routers import setup_wizard as api_setup_wizard
 from src.core.config import ConfigManager
 from src.core.exception import CustomException
 from src.core.api_key_auth import should_skip_api_key_auth
@@ -160,5 +161,6 @@ async def validation_exception_handler(request: Request, exc: RequestValidationE
 app.include_router(api_settings.router,tags=["settings"])
 app.include_router(api_compose_app.router,tags=["compose-apps"])
 app.include_router(api_appstore_sync.router,tags=["appstore-sync"])
+app.include_router(api_setup_wizard.router,tags=["setup-wizard"])
 
 remove_422_responses()

apphub/src/schemas/productAuth.py

@@ -77,6 +77,8 @@ class ProductAuthStatusResponse(BaseModel):
     enabled: bool
     initialization_required: bool
     authenticated: bool
+    cloud_marketplace_setup: bool = False
+    cloud_marketplace_setup_pending: bool = False
     protected_modules: list[str]
     current_user: Optional[ProductAuthOperator] = None
     storage_boundary: ProductAuthStorageBoundary

apphub/src/schemas/setupWizard.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+from src.core.exception import CustomException
+
+
+SetupWizardStep = Literal[
+    "welcome",
+    "platform_init",
+    "app_init_ready",
+    "app_init_running",
+    "app_init_failed",
+    "complete",
+]
+
+SetupWizardInstallStatus = Literal["running", "succeeded", "failed"]
+SetupWizardInputType = Literal["text", "number", "password"]
+
+
+class SetupWizardError(BaseModel):
+    code: str
+    message: str
+    retryable: bool = True
+    field_names: list[str] = Field(default_factory=list)
+
+
+class SetupWizardStateResponse(BaseModel):
+    enabled: bool
+    current_step: SetupWizardStep
+    app_slug: Optional[str] = None
+    default_locale: str = "en"
+    installed_app_id: Optional[str] = None
+    completed: bool
+    tracking_id: Optional[str] = None
+    pending_app_id: Optional[str] = None
+    last_error: Optional[SetupWizardError] = None
+    updated_at: str
+    completed_at: Optional[str] = None
+
+
+class SetupWizardInputField(BaseModel):
+    name: str
+    label: str
+    type: SetupWizardInputType = "text"
+    required: bool = True
+    default_value: Optional[str] = None
+    placeholder: Optional[str] = None
+    description: Optional[str] = None
+
+
+class SetupWizardAppResponse(BaseModel):
+    app_slug: str
+    default_locale: str = "en"
+    display_name: str
+    edition: str
+    default_app_id: str
+    is_web_app: bool
+    requires_user_inputs: bool
+    required_inputs: list[SetupWizardInputField] = Field(default_factory=list)
+    settings: dict[str, str] = Field(default_factory=dict)
+
+
+class SetupWizardPlatformInitCompleteResponse(BaseModel):
+    current_step: SetupWizardStep
+    updated_at: str
+
+
+class SetupWizardInstallRequest(BaseModel):
+    app_id: str = Field(min_length=2, max_length=20)
+    edition: str = Field(min_length=1, max_length=128)
+    domain_name: str = Field(min_length=1, max_length=255)
+    user_inputs: dict[str, str] = Field(default_factory=dict)
+
+    @field_validator("app_id", mode="before")
+    @classmethod
+    def normalize_app_id(cls, value: str) -> str:
+        normalized = str(value or "").strip().lower()
+        if not normalized:
+            raise CustomException(400, "Invalid Request", "'app_id' cannot be empty.")
+        return normalized
+
+    @field_validator("edition", mode="before")
+    @classmethod
+    def normalize_edition(cls, value: str) -> str:
+        normalized = str(value or "").strip()
+        if not normalized:
+            raise CustomException(400, "Invalid Request", "'edition' cannot be empty.")
+        return normalized
+
+    @field_validator("domain_name", mode="before")
+    @classmethod
+    def normalize_domain_name(cls, value: str) -> str:
+        normalized = str(value or "").strip().lower()
+        if not normalized:
+            raise CustomException(400, "Invalid Request", "'domain_name' cannot be empty.")
+        return normalized
+
+
+class SetupWizardInstallAcceptedResponse(BaseModel):
+    tracking_id: str
+    current_step: SetupWizardStep
+
+
+class SetupWizardInstallStatusResponse(BaseModel):
+    status: SetupWizardInstallStatus
+    current_step: SetupWizardStep
+    installed_app_id: Optional[str] = None
+    last_error: Optional[SetupWizardError] = None
+
+
+class SetupWizardCompleteResponse(BaseModel):
+    current_step: SetupWizardStep
+    installed_app_id: str
+    completed: bool
+    completed_at: str

apphub/src/services/app_manager.py

@@ -1316,7 +1316,17 @@ def install_app(self,appInstall: appInstall, endpointId: int = None, tracked_app
                 except Exception:
                     portainerManager.remove_vloumes(app_id,endpointId)
             else:
-                portainerManager.remove_vloumes(app_id,endpointId)
+                # create_stack_from_repository raised before returning stack_info,
+                # but Portainer may have created a stack record before the compose
+                # up failure.  Look it up by name so we can clean it up completely.
+                try:
+                    stack = portainerManager.get_stack_by_name(app_id, endpointId)
+                    if stack and stack.get("Id"):
+                        portainerManager.remove_stack_and_volumes(stack["Id"], endpointId)
+                    else:
+                        portainerManager.remove_vloumes(app_id, endpointId)
+                except Exception:
+                    portainerManager.remove_vloumes(app_id, endpointId)
             # modify app status: error
             modify_app_information(app_uuid,e.details)
             remove_installation_logs(app_uuid)
@@ -1331,7 +1341,14 @@ def install_app(self,appInstall: appInstall, endpointId: int = None, tracked_app
                 except Exception:
                     portainerManager.remove_vloumes(app_id,endpointId)
             else:
-                portainerManager.remove_vloumes(app_id,endpointId)
+                try:
+                    stack = portainerManager.get_stack_by_name(app_id, endpointId)
+                    if stack and stack.get("Id"):
+                        portainerManager.remove_stack_and_volumes(stack["Id"], endpointId)
+                    else:
+                        portainerManager.remove_vloumes(app_id, endpointId)
+                except Exception:
+                    portainerManager.remove_vloumes(app_id, endpointId)
             # modify app status: error
             modify_app_information(app_uuid,"Create stack error")
             remove_installation_logs(app_uuid)

apphub/src/services/marketplace_bootstrap.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+RUNTIME_BOOTSTRAP_PATH = Path("/websoft9/marketplace/bootstrap.json")
+REPO_BOOTSTRAP_PATH = REPO_ROOT / "marketplace" / "bootstrap.json"
+
+
+def get_marketplace_bootstrap_path() -> Path:
+    if RUNTIME_BOOTSTRAP_PATH.exists() or RUNTIME_BOOTSTRAP_PATH.parent.exists():
+        return RUNTIME_BOOTSTRAP_PATH
+    return REPO_BOOTSTRAP_PATH
+
+
+def normalize_marketplace_locale(value: str | None) -> str:
+    locale = str(value or "").strip().lower()
+    return "zh-CN" if locale.startswith("zh") else "en"
+
+
+class MarketplaceBootstrapService:
+    def __init__(self, file_path: Path | None = None):
+        self.file_path = file_path or get_marketplace_bootstrap_path()
+
+    def read(self) -> dict[str, Any]:
+        try:
+            raw = self.file_path.read_text(encoding="utf-8")
+        except FileNotFoundError:
+            return {}
+        except Exception:
+            return {}
+
+        try:
+            payload = json.loads(raw)
+        except json.JSONDecodeError:
+            return {}
+
+        if not isinstance(payload, dict):
+            return {}
+
+        app_slug = str(payload.get("app_slug") or "").strip().lower()
+        if not app_slug:
+            return {}
+
+        return {
+            "app_slug": app_slug,
+            "default_locale": normalize_marketplace_locale(str(payload.get("default_locale") or "en")),
+        }
+
+    def write(self, app_slug: str, default_locale: str) -> dict[str, str]:
+        payload = {
+            "app_slug": str(app_slug or "").strip().lower(),
+            "default_locale": normalize_marketplace_locale(default_locale),
+        }
+        if not payload["app_slug"]:
+            raise ValueError("app_slug cannot be empty")
+        self.file_path.parent.mkdir(parents=True, exist_ok=True)
+        self.file_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True), encoding="utf-8")
+        return payload