feat: switch to interactive wizard as default deployment mode

CodeMonkeyCybersecurity · CodeMonkeyCybersecurity · commit 0b8c4c16f77e · 2025-10-28T16:08:50.000+08:00
- Changed default deployment mode from YAML config to interactive wizard for better user experience
- Updated help text to clarify wizard is now the recommended approach for human users
- Added suggested modules list (bionicgpt, wazuh, nextcloud) in interactive prompts
- Improved Authentik credential management and documentation:
  - Added detailed instructions for API token creation in .env template
  - Clarified difference between bootstrap
diff --git a/cmd/create/hecate.go b/cmd/create/hecate.go
@@ -16,7 +16,6 @@ import (
 	"github.com/spf13/cobra"
 	"github.com/uptrace/opentelemetry-go-extra/otelzap"
 	"go.uber.org/zap"
-	"gopkg.in/yaml.v3"
 )
 
 func init() {
@@ -36,8 +35,18 @@ var CreateHecateCmd = &cobra.Command{
 	Short: "Deploy Hecate reverse proxy framework",
 	Long: `Deploy Hecate reverse proxy framework using Docker Compose.
 
-MODE 1: YAML Configuration (Recommended)
-  Deploy from a simple YAML config file that defines your apps and their backends.
+MODE 1: Interactive Wizard (Default - Human-Centric)
+  Run without any flags to start an interactive wizard that guides you through:
+  - Adding apps and their domains
+  - Configuring backends (upstream services)
+  - Optional SSO integration via Authentik
+  - WebRTC/TCP port forwarding setup
+
+  eos create hecate                                 # Interactive wizard (recommended)
+
+MODE 2: YAML Configuration (For Automation)
+  Deploy from a YAML config file that defines your apps and backends.
+  Useful for scripted deployments or complex multi-service setups.
 
   Example config.yaml:
     apps:
@@ -52,22 +61,18 @@ MODE 1: YAML Configuration (Recommended)
       authentik:
         domain: hera.cybermonkey.dev
 
-  eos create hecate --config config.yaml
-
-MODE 2: Interactive Wizard
-  Interactive setup that guides you through configuration.
-
-  eos create hecate
+  eos create hecate --config config.yaml            # Deploy from YAML
 
 The deployment creates configuration files at /opt/hecate/:
 - docker-compose.yml - Container orchestration
 - Caddyfile - Caddy reverse proxy configuration
-- .env - Environment variables (if Authentik is configured)
+- .env - Environment variables (includes Authentik bootstrap credentials)
 
 Examples:
+  eos create hecate                                 # Interactive wizard (starts automatically)
   eos create hecate --config example.yaml           # Deploy from YAML config
   eos create hecate --config example.yaml --output /opt/hecate  # Custom output dir
-  eos create hecate                                 # Interactive wizard
+  eos create config --hecate                        # Generate YAML config only (no deployment)
   eos create hecate --help                          # Show this help message`,
 	RunE: eos.Wrap(func(rc *eos_io.RuntimeContext, cmd *cobra.Command, args []string) error {
 		log := otelzap.Ctx(rc.Ctx)
@@ -95,6 +100,7 @@ Examples:
 		}
 
 		var config *hecate.YAMLHecateConfig
+		var tempConfigPath string
 
 		// Check if config file was provided (YAML override)
 		if configFile != "" {
@@ -108,52 +114,36 @@ Examples:
 				return fmt.Errorf("failed to load YAML config: %w", err)
 			}
 		} else {
-			// No YAML file provided - try loading from Consul KV
-			log.Info("No config file provided, checking Consul KV")
-
-			configStorage, err := hecate.NewConfigStorage(rc)
-			if err != nil {
-				return fmt.Errorf("failed to initialize Consul storage: %w\n\n"+
-					"Either:\n"+
-					"  1. Provide a YAML config file: eos create hecate --config hecate-config.yaml\n"+
-					"  2. Generate config first: eos create config --hecate\n"+
-					"  3. Ensure Consul is running and accessible", err)
-			}
-
-			rawConfig, err := configStorage.LoadConfig(rc)
-			if err != nil {
-				return fmt.Errorf("failed to load config from Consul KV: %w", err)
-			}
-
-			if rawConfig == nil || len(rawConfig.Apps) == 0 {
-				return fmt.Errorf("no configuration found in Consul KV\n\n" +
-					"Please run one of:\n" +
-					"  1. Generate config: eos create config --hecate\n" +
-					"  2. Provide YAML file: eos create hecate --config hecate-config.yaml")
-			}
+			// No YAML file provided - run interactive wizard
+			log.Info("No config file provided, starting interactive wizard")
+
+			// Generate temporary config file path
+			tempConfigPath = "/tmp/hecate-config-wizard.yaml"
+			defer func() {
+				if tempConfigPath != "" {
+					_ = os.Remove(tempConfigPath)
+				}
+			}()
 
-			log.Info("Configuration loaded from Consul KV",
-				zap.Int("app_count", len(rawConfig.Apps)))
+			// Run interactive config generator (same as 'eos create config --hecate')
+			log.Info("terminal prompt: ")
+			log.Info("terminal prompt: No configuration file provided.")
+			log.Info("terminal prompt: Starting interactive wizard to configure Hecate...")
+			log.Info("terminal prompt: ")
 
-			// Convert RawYAMLConfig to parsed YAMLHecateConfig
-			// We need to create a temporary YAML file to reuse LoadYAMLConfig
-			// Or we can parse it directly here
-			tempYAMLPath := "/tmp/hecate-config-from-consul.yaml"
-			yamlData, err := yaml.Marshal(rawConfig)
-			if err != nil {
-				return fmt.Errorf("failed to marshal config: %w", err)
-			}
-			if err := os.WriteFile(tempYAMLPath, yamlData, 0644); err != nil {
-				return fmt.Errorf("failed to write temp config: %w", err)
+			if err := hecate.GenerateConfigFile(rc, tempConfigPath, true); err != nil {
+				return fmt.Errorf("interactive configuration failed: %w", err)
 			}
-			defer func() { _ = os.Remove(tempYAMLPath) }()
 
-			config, err = hecate.LoadYAMLConfig(rc, tempYAMLPath)
+			// Load the generated config
+			config, err = hecate.LoadYAMLConfig(rc, tempConfigPath)
 			if err != nil {
-				return fmt.Errorf("failed to parse config from Consul: %w", err)
+				return fmt.Errorf("failed to load generated config: %w", err)
 			}
 
-			log.Info("terminal prompt: Using configuration from Consul KV")
+			log.Info("terminal prompt: ")
+			log.Info("terminal prompt: Configuration complete! Proceeding with deployment...")
+			log.Info("terminal prompt: ")
 		}
 
 		// Display detected apps
diff --git a/pkg/hecate/add/bionicgpt.go b/pkg/hecate/add/bionicgpt.go
@@ -145,14 +145,18 @@ func (b *BionicGPTIntegrator) ConfigureAuthentication(rc *eos_io.RuntimeContext,
 	}
 
 	// Step 1: Get Authentik credentials from .env file
-	logger.Info("    Getting Authentik credentials from /opt/bionicgpt/.env")
+	logger.Info("    Getting Authentik credentials from /opt/hecate/.env")
 	authentikToken, authentikBaseURL, err := b.getAuthentikCredentials(rc.Ctx)
 	if err != nil {
 		logger.Warn("Authentik credentials not found, skipping proxy provider setup", zap.Error(err))
-		logger.Warn("To enable authentication, add to /opt/bionicgpt/.env:")
-		logger.Warn("  AUTHENTIK_TOKEN=your_authentik_api_token")
-		logger.Warn("  AUTHENTIK_BASE_URL=http://localhost:9000")
-		logger.Warn("Get API token from: https://hera.your-domain/if/admin/#/core/tokens")
+		logger.Warn("")
+		logger.Warn("To enable authentication:")
+		logger.Warn("  1. Login to Authentik admin: https://hera.codemonkey.net.au/if/admin/")
+		logger.Warn("  2. Create API token: Directory → Tokens → Create")
+		logger.Warn("  3. Add to /opt/hecate/.env:")
+		logger.Warn("     echo 'AUTHENTIK_API_TOKEN=<your_token>' | sudo tee -a /opt/hecate/.env")
+		logger.Warn("  4. Re-run this command")
+		logger.Warn("")
 		return nil // Non-fatal: generic route still works
 	}
 
@@ -286,36 +290,63 @@ func (b *BionicGPTIntegrator) Rollback(rc *eos_io.RuntimeContext) error {
 }
 
 // getAuthentikCredentials retrieves Authentik API credentials from .env files
-// TODO: Migrate to Vault once BionicGPT and Authentik are fully migrated to Vault-based secrets
+//
+// TODO (ROADMAP - 6-12 months): Migrate to Vault-based secret management
+// For now, credentials stored in /opt/hecate/.env (acceptable per CLAUDE.md requirements)
 func (b *BionicGPTIntegrator) getAuthentikCredentials(ctx context.Context) (string, string, error) {
-	// TEMPORARY: Read from .env files until Vault migration is complete
-	// BionicGPT stores Authentik token in /opt/bionicgpt/.env
-	// Authentik base URL can be inferred from Hecate or use default
-
-	bionicgptEnv, err := readEnvFile("/opt/bionicgpt/.env")
+	// ARCHITECTURE NOTE: Authentik runs in Hecate stack, credentials are in /opt/hecate/.env
+	// NOT in /opt/bionicgpt/.env (BionicGPT is a separate service proxied through Authentik)
+	//
+	// TODO (UPSTREAM BLOCKER): Automate API token creation when Authentik provides capability
+	// CURRENT STATUS: Authentik doesn't support programmatic API token creation without UI access
+	// (see: https://github.com/goauthentik/authentik/issues/12882)
+	//
+	// WORKAROUND: Manual token creation via Authentik admin UI (one-time setup)
+	//
+	// NOTE: AUTHENTIK_BOOTSTRAP_TOKEN (from .env) is for initial admin user creation,
+	// NOT for API access. We need a separate API token created via UI.
+
+	hecateEnv, err := readEnvFile("/opt/hecate/.env")
 	if err != nil {
-		return "", "", fmt.Errorf("failed to read /opt/bionicgpt/.env: %w\n"+
-			"Ensure BionicGPT is installed with: eos create bionicgpt", err)
+		return "", "", fmt.Errorf("failed to read /opt/hecate/.env: %w\n"+
+			"Authentik configuration should be in Hecate .env file", err)
 	}
 
-	// Check for AUTHENTIK_TOKEN in BionicGPT .env
-	apiKey := bionicgptEnv["AUTHENTIK_TOKEN"]
+	// Check for AUTHENTIK_API_TOKEN (preferred) or legacy variants
+	apiKey := hecateEnv["AUTHENTIK_API_TOKEN"]
 	if apiKey == "" {
-		// Fallback: Try AUTHENTIK_API_KEY
-		apiKey = bionicgptEnv["AUTHENTIK_API_KEY"]
+		apiKey = hecateEnv["AUTHENTIK_TOKEN"]
 	}
+	if apiKey == "" {
+		apiKey = hecateEnv["AUTHENTIK_API_KEY"]
+	}
+
+	// NOTE: We do NOT fallback to AUTHENTIK_BOOTSTRAP_TOKEN - that's for initial setup,
+	// not API access. Authentik requires a separate API token created via UI.
 
 	if apiKey == "" {
-		return "", "", fmt.Errorf("AUTHENTIK_TOKEN not found in /opt/bionicgpt/.env\n" +
-			"Add to .env file:\n" +
-			"  AUTHENTIK_TOKEN=your_authentik_api_token\n" +
-			"Get token from: https://hera.your-domain/if/admin/#/core/tokens")
+		return "", "", fmt.Errorf("AUTHENTIK_API_TOKEN not found in /opt/hecate/.env\n\n" +
+			"To configure Authentik API access:\n\n" +
+			"1. Login to Authentik admin UI:\n" +
+			"   https://hera.codemonkey.net.au/if/admin/\n\n" +
+			"2. Login with bootstrap credentials:\n" +
+			"   Email: (from AUTHENTIK_BOOTSTRAP_EMAIL in /opt/hecate/.env)\n" +
+			"   Password: (from AUTHENTIK_BOOTSTRAP_PASSWORD in /opt/hecate/.env)\n\n" +
+			"3. Navigate to: Directory → Tokens → Create\n" +
+			"   - User: Select your admin user\n" +
+			"   - Intent: API\n" +
+			"   - Expiry: Never (or long duration like 365 days)\n\n" +
+			"4. Copy the generated token and add to /opt/hecate/.env:\n" +
+			"   echo 'AUTHENTIK_API_TOKEN=<your_token_here>' | sudo tee -a /opt/hecate/.env\n\n" +
+			"5. Re-run this command\n\n" +
+			"NOTE: This is a one-time manual step. Authentik doesn't yet support automated\n" +
+			"API token creation (tracked in https://github.com/goauthentik/authentik/issues/12882)")
 	}
 
 	// Get base URL from env or use default
-	baseURL := bionicgptEnv["AUTHENTIK_BASE_URL"]
+	baseURL := hecateEnv["AUTHENTIK_BASE_URL"]
 	if baseURL == "" {
-		// Default to localhost:9000 (Authentik default in Hecate stack)
+		// Default to localhost:9000 (Authentik server container exposed port)
 		baseURL = "http://localhost:9000"
 	}
 
diff --git a/pkg/hecate/bootstrap_credentials.go b/pkg/hecate/bootstrap_credentials.go
@@ -17,6 +17,14 @@ const (
 	ConsulAuthentikBootstrapEmail    = ConsulHecatePrefix + "secrets/authentik/bootstrap_email"
 	ConsulAuthentikBootstrapPassword = ConsulHecatePrefix + "secrets/authentik/bootstrap_password"
 	ConsulAuthentikBootstrapToken    = ConsulHecatePrefix + "secrets/authentik/bootstrap_token"
+
+	// NOTE: AUTHENTIK_API_TOKEN is NOT stored in Consul for now
+	// RATIONALE: API tokens are created manually via Authentik UI (upstream limitation)
+	// STORAGE: Stored in /opt/hecate/.env (one-time manual setup)
+	// TODO (ROADMAP - 6-12 months): Migrate to Vault when we add full Vault integration
+	//
+	// When we do migrate to Vault, the path should be:
+	// ConsulAuthentikAPIToken = ConsulHecatePrefix + "secrets/authentik/api_token"
 )
 
 // AuthentikBootstrapCredentials holds the bootstrap credentials for Authentik first-time setup
diff --git a/pkg/hecate/config_generator.go b/pkg/hecate/config_generator.go
@@ -130,7 +130,14 @@ func gatherApps(rc *eos_io.RuntimeContext, previousConfig *RawYAMLConfig) (map[s
 		logger.Info("terminal prompt: --- Add Application ---")
 
 		// App name
-		logger.Info("terminal prompt: App name (e.g., main, wazuh, nextcloud) [Enter to finish]: ")
+		logger.Info("terminal prompt: App name (e.g., main, wazuh, nextcloud, bionicgpt) [Enter to finish]: ")
+		logger.Info("terminal prompt: ")
+		logger.Info("terminal prompt: Suggested modules:")
+		logger.Info("terminal prompt:   • bionicgpt - AI chatbot with RAG (Retrieval-Augmented Generation)")
+		logger.Info("terminal prompt:   • wazuh     - Security monitoring and SIEM platform")
+		logger.Info("terminal prompt:   • nextcloud - File sharing and collaboration")
+		logger.Info("terminal prompt:   • main      - Your main application/website")
+		logger.Info("terminal prompt: ")
 		fmt.Print("App name: ")
 		appName := strings.TrimSpace(mustReadLine(reader))
 		if appName == "" {
diff --git a/pkg/hecate/lifecycle_compat.go b/pkg/hecate/lifecycle_compat.go
@@ -150,12 +150,33 @@ AUTHENTIK_TAG=%s
 AUTHENTIK_IMAGE=ghcr.io/goauthentik/server
 AUTHENTIK_WORKER__THREADS=%s
 
-# Authentik Bootstrap Credentials
-# These are used for initial admin user creation
+# Authentik Bootstrap Credentials - ADMIN LOGIN CREDENTIALS
+# Use these to login to Authentik admin UI: https://hera.your-domain/if/admin/
+#
+# Login Email: %s
+# Login Password: %s
+#
+# NOTE: If these values are missing from this file, they may be stored in Consul KV.
+# Retrieve with: consul kv get hecate/secrets/authentik/bootstrap_email
+#                consul kv get hecate/secrets/authentik/bootstrap_password
+#
 AUTHENTIK_BOOTSTRAP_EMAIL=%s
 AUTHENTIK_BOOTSTRAP_PASSWORD=%s
 AUTHENTIK_BOOTSTRAP_TOKEN=%s
 
+# Authentik API Token (REQUIRED for automated service integration)
+# This token is used by 'eos update hecate --add <service>' to configure SSO automatically
+#
+# To create this token (one-time setup):
+#   1. Login to Authentik admin UI: https://hera.your-domain/if/admin/
+#   2. Use bootstrap credentials above (email + password)
+#   3. Navigate to: Directory → Tokens → Create
+#   4. Set: User = admin, Intent = API, Expiry = Never (or 365 days)
+#   5. Copy the generated token and replace the placeholder below
+#
+# Leave empty if you don't plan to use automated SSO integration
+AUTHENTIK_API_TOKEN=
+
 # Compose Port Configuration
 COMPOSE_PORT_HTTP=%s
 COMPOSE_PORT_HTTPS=%s
diff --git a/pkg/hecate/yaml_generator.go b/pkg/hecate/yaml_generator.go
@@ -722,12 +722,33 @@ AUTHENTIK_TAG=%s
 AUTHENTIK_IMAGE=ghcr.io/goauthentik/server
 AUTHENTIK_WORKER__THREADS=%s
 
-# Authentik Bootstrap Credentials
-# Use these to login for the first time - Email: %s, Password: %s
+# Authentik Bootstrap Credentials - ADMIN LOGIN CREDENTIALS
+# Use these to login to Authentik admin UI: https://hera.your-domain/if/admin/
+#
+# Login Email: %s
+# Login Password: %s
+#
+# NOTE: If these values are missing from this file, they may be stored in Consul KV.
+# Retrieve with: consul kv get hecate/secrets/authentik/bootstrap_email
+#                consul kv get hecate/secrets/authentik/bootstrap_password
+#
 AUTHENTIK_BOOTSTRAP_EMAIL=%s
 AUTHENTIK_BOOTSTRAP_PASSWORD=%s
 AUTHENTIK_BOOTSTRAP_TOKEN=%s
 
+# Authentik API Token (REQUIRED for automated service integration)
+# This token is used by 'eos update hecate --add <service>' to configure SSO automatically
+#
+# To create this token (one-time setup):
+#   1. Login to Authentik admin UI: https://hera.your-domain/if/admin/
+#   2. Use bootstrap credentials above (email + password)
+#   3. Navigate to: Directory → Tokens → Create
+#   4. Set: User = admin, Intent = API, Expiry = Never (or 365 days)
+#   5. Copy the generated token and replace the placeholder below
+#
+# Leave empty if you don't plan to use automated SSO integration
+AUTHENTIK_API_TOKEN=
+
 # Ports
 COMPOSE_PORT_HTTP=%s
 COMPOSE_PORT_HTTPS=%s
