feat: add setup wizard for initial system configuration (#60)

* feat(api): add setup wizard endpoints for initial configuration

Add backend support for first-time system initialization:
- GET /setup/status - check if system is initialized
- POST /setup/initialize - create first admin user

The system is considered initialized when at least one admin user exists.
This allows new installations to configure admin credentials through the UI.

* feat(portal): add setup wizard page for initial configuration

Add modern setup wizard UI with:
- Admin email and password fields with validation
- Confirm password verification
- Optional admin name field
- Success animation and redirect to login
- Responsive design matching existing UI patterns

* feat(portal): add SetupGuard component for route protection

Add wrapper component that:
- Checks setup status on mount
- Redirects to /setup if system is not initialized
- Shows loading state while checking
- Falls back to initialized=true if API is unreachable

* feat(portal): integrate setup wizard into routing

- Add /setup route for the setup wizard page
- Wrap /login and authenticated routes with SetupGuard
- Ensures users are redirected to setup on first access

* docs(docker): add SKIP_SETUP configuration option

- Add SKIP_SETUP env var documentation to .env.example
- Add SKIP_SETUP and TRON_SECRETS_KEY to docker-compose.prod.yaml
- Allows automated deployments to skip the setup wizard

---------

Co-authored-by: rafaelrsantosti <11065120+rafaelrsantosti@users.noreply.github.com>

Author: rafaelrsantosti

api/app/main.py

@@ -26,6 +26,7 @@
 from app.webapps.api.webapp_handlers import router as webapps_router
 from app.workers.api.worker_handlers import router as workers_router
 from app.cron.api.cron_handlers import router as crons_router
+from app.setup.api.setup_handlers import router as setup_router
 
 # Version is injected at build time via APP_VERSION environment variable
 APP_VERSION = os.getenv("APP_VERSION", "dev")
@@ -101,6 +102,7 @@
 app.include_router(webapps_router)
 app.include_router(workers_router)
 app.include_router(crons_router)
+app.include_router(setup_router)
 
 # Legacy routers removed - all features migrated to new structure
 

api/app/setup/__init__.py

@@ -0,0 +1 @@
+"""Setup module for initial system configuration."""

api/app/setup/api/__init__.py

@@ -0,0 +1 @@
+"""Setup API module."""

api/app/setup/api/setup_dto.py

@@ -0,0 +1,26 @@
+"""DTOs for setup endpoints."""
+
+from pydantic import BaseModel, EmailStr, Field
+
+
+class SetupStatus(BaseModel):
+    """Response for setup status check."""
+
+    initialized: bool
+    message: str
+
+
+class SetupInitialize(BaseModel):
+    """Request to initialize the system."""
+
+    admin_email: EmailStr = Field(..., description="Admin user email")
+    admin_password: str = Field(..., min_length=6, description="Admin user password")
+    admin_name: str = Field(default="Administrator", description="Admin user full name")
+
+
+class SetupInitializeResponse(BaseModel):
+    """Response after successful initialization."""
+
+    success: bool
+    message: str
+    admin_email: str

api/app/setup/api/setup_handlers.py

@@ -0,0 +1,93 @@
+"""Setup API handlers."""
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.orm import Session
+
+from app.shared.database.database import get_db
+from app.setup.core.setup_service import SetupService
+from app.setup.api.setup_dto import (
+    SetupStatus,
+    SetupInitialize,
+    SetupInitializeResponse,
+)
+
+router = APIRouter(prefix="/setup", tags=["Setup"])
+
+
+def get_setup_service(db: Session = Depends(get_db)) -> SetupService:
+    """Dependency to get SetupService instance."""
+    return SetupService(db)
+
+
+@router.get("/status", response_model=SetupStatus)
+def get_setup_status(service: SetupService = Depends(get_setup_service)):
+    """
+    Check if the system has been initialized.
+
+    Returns:
+        SetupStatus with initialized flag and message
+    """
+    initialized = service.is_initialized()
+    skip_setup = service.should_skip_setup()
+
+    if skip_setup and not initialized:
+        return SetupStatus(
+            initialized=False,
+            message="Setup skipped via SKIP_SETUP environment variable",
+        )
+
+    if initialized:
+        return SetupStatus(
+            initialized=True,
+            message="System is ready",
+        )
+
+    return SetupStatus(
+        initialized=False,
+        message="System requires initial setup",
+    )
+
+
+@router.post("/initialize", response_model=SetupInitializeResponse)
+def initialize_setup(
+    data: SetupInitialize,
+    service: SetupService = Depends(get_setup_service),
+):
+    """
+    Initialize the system with the first admin user.
+
+    This endpoint can only be called once, when no admin users exist.
+
+    Args:
+        data: SetupInitialize with admin credentials
+
+    Returns:
+        SetupInitializeResponse on success
+
+    Raises:
+        HTTPException 400: If system is already initialized
+    """
+    if service.is_initialized():
+        raise HTTPException(
+            status_code=400,
+            detail="System is already initialized. Cannot run setup again.",
+        )
+
+    try:
+        admin_user = service.initialize(
+            admin_email=data.admin_email,
+            admin_password=data.admin_password,
+            admin_name=data.admin_name,
+        )
+
+        return SetupInitializeResponse(
+            success=True,
+            message="System initialized successfully! You can now login with your admin credentials.",
+            admin_email=admin_user.email,
+        )
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+    except Exception as e:
+        raise HTTPException(
+            status_code=500, detail=f"Failed to initialize system: {str(e)}"
+        )

api/app/setup/core/__init__.py

@@ -0,0 +1 @@
+"""Setup core module."""

api/app/setup/core/setup_service.py

@@ -0,0 +1,65 @@
+"""Setup service for initial system configuration."""
+
+import os
+from sqlalchemy.orm import Session
+
+from app.users.infra.user_model import User, UserRole
+from app.auth.core.auth_service import AuthService
+
+
+class SetupService:
+    """Business logic for system setup."""
+
+    def __init__(self, db: Session):
+        self.db = db
+        self.auth_service = AuthService()
+
+    def is_initialized(self) -> bool:
+        """Check if the system has been initialized (has at least one admin user)."""
+        admin_count = (
+            self.db.query(User).filter(User.role == UserRole.ADMIN.value).count()
+        )
+        return admin_count > 0
+
+    def should_skip_setup(self) -> bool:
+        """Check if setup should be skipped (for dev environments)."""
+        return os.getenv("SKIP_SETUP", "false").lower() == "true"
+
+    def initialize(
+        self,
+        admin_email: str,
+        admin_password: str,
+        admin_name: str = "Administrator",
+    ) -> User:
+        """
+        Initialize the system with the first admin user.
+
+        Args:
+            admin_email: Email for the admin user
+            admin_password: Password for the admin user
+            admin_name: Full name for the admin user
+
+        Returns:
+            The created admin user
+
+        Raises:
+            ValueError: If the system is already initialized
+        """
+        if self.is_initialized():
+            raise ValueError("System is already initialized")
+
+        # Create admin user
+        hashed_password = self.auth_service.get_password_hash(admin_password)
+        admin_user = User(
+            email=admin_email,
+            hashed_password=hashed_password,
+            full_name=admin_name,
+            role=UserRole.ADMIN.value,
+            is_active=True,
+        )
+
+        self.db.add(admin_user)
+        self.db.commit()
+        self.db.refresh(admin_user)
+
+        return admin_user

docker/.env.example

@@ -35,6 +35,15 @@ CORS_ORIGINS=https://your-domain.com
 # API URL for Portal (use /api when behind nginx proxy)
 API_URL=/api
 
+# =============================================================================
+# Initial Setup
+# =============================================================================
+
+# Skip the initial setup wizard (use for automated deployments)
+# If true, you must create the admin user through other means (e.g., scripts)
+# Default: false (setup wizard required on first access)
+SKIP_SETUP=false
+
 # =============================================================================
 # Secrets Encryption
 # =============================================================================

docker/docker-compose.prod.yaml

@@ -89,6 +89,8 @@ services:
       CORS_ALLOW_CREDENTIALS: "true"
       CORS_ALLOW_METHODS: "GET,POST,PUT,DELETE,OPTIONS"
       CORS_ALLOW_HEADERS: "Content-Type,Authorization,Accept,Origin,X-Requested-With"
+      SKIP_SETUP: ${SKIP_SETUP:-false}
+      TRON_SECRETS_KEY: ${TRON_SECRETS_KEY:-}
     expose:
       - "8000"
     depends_on:

portal/src/App.tsx

@@ -1,8 +1,10 @@
 import { Routes, Route } from 'react-router-dom'
 import { AuthProvider } from './contexts/AuthContext'
 import { ProtectedRoute, AdminRoute, Layout } from './shared/components'
+import SetupGuard from './components/SetupGuard'
 import Home from './pages/home'
 import Login from './pages/Login'
+import Setup from './pages/setup/Setup'
 import Clusters from './pages/clusters/Clusters'
 import Environments from './pages/environments/Environments'
 import Applications from './pages/applications/Applications'
@@ -21,8 +23,9 @@ function App() {
   return (
     <AuthProvider>
       <Routes>
-        <Route path="/login" element={<Login />} />
-        <Route path="/" element={<Layout />}>
+        <Route path="/setup" element={<Setup />} />
+        <Route path="/login" element={<SetupGuard><Login /></SetupGuard>} />
+        <Route path="/" element={<SetupGuard><Layout /></SetupGuard>}>
           <Route index element={<ProtectedRoute><Home /></ProtectedRoute>} />
           <Route path="clusters" element={<ProtectedRoute><AdminRoute><Clusters /></AdminRoute></ProtectedRoute>} />
           <Route path="environments" element={<ProtectedRoute><AdminRoute><Environments /></AdminRoute></ProtectedRoute>} />