fix: print actionable startup errors to stderr; document non-default pg port mapping

Author: Serge Pauli

README.md

@@ -54,6 +54,10 @@ docker run -d --name yrestapi-pg \
   -p 5432:5432 \
   postgres:16-alpine
 
+# If local port 5432 is busy, use:
+# -p 5433:5432
+# and set POSTGRES_DSN host port to 5433 in .env.
+
 # 2) Wait until DB is ready
 until docker exec yrestapi-pg pg_isready -U postgres -d app >/dev/null 2>&1; do sleep 1; done
 

cmd/main.go

@@ -14,29 +14,38 @@ import (
 	"os"
 )
 
+func startupFatal(code string, err error) {
+	msg := err.Error()
+	if err == nil {
+		msg = "unknown error"
+	}
+	fmt.Fprintf(os.Stderr, "startup failed (%s): %s\n", code, msg)
+	fmt.Fprintf(os.Stderr, "see log/app.log for details\n")
+	os.Exit(1)
+}
+
 func main() {
 	debugFlag := flag.Bool("d", false, "enable debug logging")
 	flag.Parse()
 
 	cfg := config.LoadConfig()
 	if err := logger.Init("."); err != nil {
-		fmt.Fprintf(os.Stderr, "log init failed: %v\n", err)
-		os.Exit(1)
+		startupFatal("log_init_failed", err)
 	}
 	logger.SetDebug(*debugFlag)
 
 	// PostgreSQL
 
 	if err := db.InitPostgres(cfg.PostgresDSN); err != nil {
 		logger.Error("postgres_init_failed", map[string]any{"error": err.Error()})
-		os.Exit(1)
+		startupFatal("postgres_init_failed", err)
 	}
 	logger.Info("postgres_connected", nil)
 
 	// Initialize registry
 	if err := model.InitRegistry(cfg.ModelsDir); err != nil {
 		logger.Error("registry_init_failed", map[string]any{"error": err.Error()})
-		os.Exit(1)
+		startupFatal("registry_init_failed", err)
 	}
 	model.SetAliasCacheMaxBytes(cfg.AliasCache.MaxBytes)
 	logger.Info("models_initialized", nil)
@@ -52,13 +61,13 @@ func main() {
 	// Initialize routes
 	if err := router.InitRoutes(cfg); err != nil {
 		logger.Error("router_init_failed", map[string]any{"error": err.Error()})
-		os.Exit(1)
+		startupFatal("router_init_failed", err)
 	}
 	// Start HTTP server
 	logger.Info("server_start", map[string]any{"port": cfg.Port})
 	log.Printf("🚀 Starting server on port %s", cfg.Port)
 	if err := http.ListenAndServe(":"+cfg.Port, nil); err != nil {
 		logger.Error("server_error", map[string]any{"error": err.Error()})
-		os.Exit(1)
+		startupFatal("server_error", err)
 	}
 }