feat(ui): Add setup wizard and improve initial load experience

Add setup wizard view with multi-step flow for first-time server
configuration. Show animated logo during initial load instead of
blank page. Populate sidebar nav counts from /stats API.

Signed-off-by: nfebe <fenn25.fn@gmail.com>

Author: nfebe

.env.production

@@ -0,0 +1 @@
+VITE_API_URL=/api

.node-version

@@ -0,0 +1 @@
+20

package-lock.json

@@ -31,6 +31,7 @@
     "@xterm/addon-web-links": "^0.11.0",
     "@xterm/xterm": "^5.5.0",
     "axios": "^1.6.7",
+    "codemirror": "^6.0.2",
     "lucide-vue-next": "^0.554.0",
     "pinia": "^2.1.7",
     "primeicons": "^6.0.1",

package.json

@@ -1,12 +1,33 @@
 <template>
   <div id="app">
     <ToastNotifications />
-    <router-view />
+    <div v-if="!ready" class="app-loading">
+      <Logo variant="icon" size="lg" />
+    </div>
+    <router-view v-else />
   </div>
 </template>
 
 <script setup lang="ts">
+import { ref, onMounted } from "vue";
 import ToastNotifications from "@/components/ToastNotifications.vue";
+import Logo from "@/components/base/Logo.vue";
+import { useSetupStore } from "@/stores/setup";
+import { useRouter } from "vue-router";
+
+const ready = ref(false);
+const router = useRouter();
+const setup = useSetupStore();
+
+onMounted(async () => {
+  await setup.checkSetupStatus();
+
+  if (setup.initialized === false) {
+    router.replace("/setup");
+  }
+
+  ready.value = true;
+});
 </script>
 
 <style>
@@ -21,4 +42,21 @@ body {
   background-color: #f8fafc;
   color: #1e293b;
 }
+
+.app-loading {
+  min-height: 100vh;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: #f8fafc;
+}
+
+.app-loading .logo-img {
+  animation: pulse 1.5s ease-in-out infinite;
+}
+
+@keyframes pulse {
+  0%, 100% { opacity: 1; transform: scale(1); }
+  50% { opacity: 0.5; transform: scale(0.95); }
+}
 </style>

src/App.vue

@@ -2,6 +2,7 @@ import { createRouter, createWebHistory } from "vue-router";
 import type { RouteRecordRaw } from "vue-router";
 import type { Permission } from "@/types";
 import { useAuthStore } from "@/stores/auth";
+import { useSetupStore } from "@/stores/setup";
 import DashboardLayout from "@/layouts/DashboardLayout.vue";
 
 const routes: RouteRecordRaw[] = [
@@ -11,6 +12,12 @@ const routes: RouteRecordRaw[] = [
     component: () => import("@/views/LoginView.vue"),
     meta: { requiresAuth: false },
   },
+  {
+    path: "/setup",
+    name: "setup",
+    component: () => import("@/views/SetupView.vue"),
+    meta: { requiresAuth: false },
+  },
   {
     path: "/",
     component: DashboardLayout,
@@ -181,6 +188,18 @@ const router = createRouter({
 });
 
 router.beforeEach((to, _from, next) => {
+  const setup = useSetupStore();
+
+  if (setup.initialized === false && to.path !== "/setup") {
+    next("/setup");
+    return;
+  }
+
+  if (setup.initialized === true && to.path === "/setup") {
+    next("/login");
+    return;
+  }
+
   const token = localStorage.getItem("auth_token");
   const requiresAuth = to.matched.some((record) => record.meta.requiresAuth !== false);
 

src/router/index.ts

@@ -34,7 +34,7 @@ apiClient.interceptors.request.use((config) => {
 apiClient.interceptors.response.use(
   (response) => response,
   (error) => {
-    if (error.response?.status === 401) {
+    if (error.response?.status === 401 && !window.location.pathname.startsWith("/setup")) {
       localStorage.removeItem("auth_token");
       window.location.href = "/login";
     }

src/services/api.ts

@@ -0,0 +1,167 @@
+import { defineStore } from "pinia";
+import { ref } from "vue";
+import axios from "axios";
+
+const apiClient = axios.create({
+  baseURL: "/api",
+  headers: {
+    "Content-Type": "application/json",
+  },
+});
+
+export interface SetupCheck {
+  name: string;
+  status: "pass" | "fail" | "warn";
+  message: string;
+  required: boolean;
+}
+
+export interface DNSResult {
+  valid: boolean;
+  domain: string;
+  expected: string;
+  actual: string[];
+  message?: string;
+}
+
+export interface AuthResult {
+  auth_method: string;
+  username?: string;
+  user_uid?: string;
+  api_key?: string;
+  api_key_id?: string;
+}
+
+export const useSetupStore = defineStore("setup", () => {
+  const initialized = ref<boolean | null>(null);
+  const instanceIp = ref("");
+  const agentVersion = ref("");
+  const loading = ref(false);
+  const error = ref("");
+
+  async function checkSetupStatus() {
+    if (initialized.value !== null) return;
+    try {
+      const { data } = await apiClient.get("/setup/status");
+      initialized.value = data.initialized;
+    } catch (e: any) {
+      error.value =
+        e.code === "ERR_NETWORK"
+          ? "Unable to reach FlatRun Agent. Is the service running?"
+          : e.message || "Failed to check setup status";
+    }
+  }
+
+  const infoLoaded = ref(false);
+
+  async function fetchSetupInfo() {
+    try {
+      const { data } = await apiClient.get("/setup/info");
+      instanceIp.value = data.instance_ip;
+      agentVersion.value =
+        typeof data.agent_version === "object"
+          ? data.agent_version.version
+          : data.agent_version;
+    } catch {
+      // non-critical, setup wizard still works without it
+    } finally {
+      infoLoaded.value = true;
+    }
+  }
+
+  async function runValidation(): Promise<SetupCheck[]> {
+    loading.value = true;
+    error.value = "";
+    try {
+      const { data } = await apiClient.post("/setup/validate");
+      return data.checks || [];
+    } catch (e: any) {
+      error.value = e.response?.data?.error || "Validation failed";
+      return [];
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  async function verifyDNS(domain: string): Promise<DNSResult | null> {
+    loading.value = true;
+    error.value = "";
+    try {
+      const { data } = await apiClient.get("/setup/verify-dns", { params: { domain } });
+      return data;
+    } catch (e: any) {
+      error.value = e.response?.data?.error || "DNS verification failed";
+      return null;
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  async function saveSettings(payload: {
+    domain?: string;
+    auto_ssl?: boolean;
+    cors_origins?: string[];
+  }) {
+    loading.value = true;
+    error.value = "";
+    try {
+      const { data } = await apiClient.post("/setup/settings", payload);
+      return data;
+    } catch (e: any) {
+      error.value = e.response?.data?.error || "Failed to save settings";
+      return null;
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  async function configureAuth(payload: {
+    auth_method: string;
+    username?: string;
+    password?: string;
+    email?: string;
+  }): Promise<AuthResult | null> {
+    loading.value = true;
+    error.value = "";
+    try {
+      const { data } = await apiClient.post("/setup/authentication", payload);
+      return data;
+    } catch (e: any) {
+      error.value = e.response?.data?.error || "Failed to configure authentication";
+      return null;
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  async function completeSetup() {
+    loading.value = true;
+    error.value = "";
+    try {
+      const { data } = await apiClient.post("/setup/complete");
+      initialized.value = true;
+      return data;
+    } catch (e: any) {
+      error.value = e.response?.data?.error || "Failed to complete setup";
+      return null;
+    } finally {
+      loading.value = false;
+    }
+  }
+
+  return {
+    initialized,
+    instanceIp,
+    agentVersion,
+    infoLoaded,
+    loading,
+    error,
+    checkSetupStatus,
+    fetchSetupInfo,
+    runValidation,
+    verifyDNS,
+    saveSettings,
+    configureAuth,
+    completeSetup,
+  };
+});

src/stores/setup.ts

@@ -70,6 +70,12 @@ export const useStatsStore = defineStore("stats", () => {
         docker.volumes = data.volumes?.total || 0;
         docker.networks = data.networks?.total || 0;
         docker.ports = data.ports?.total || 0;
+
+        system.ports = data.system_ports?.total || 0;
+        system.services = data.services?.total || 0;
+        system.infrastructure = data.infrastructure?.total || 0;
+        system.certificates = data.certificates?.total || 0;
+        system.apps = data.apps?.total || 0;
       }
 
       if (statsRes.data?.system) {

src/stores/stats.ts

@@ -3,7 +3,7 @@
     <div class="login-left">
       <div class="brand">
         <Logo variant="full" size="lg" />
-        <p>Docker Deployment Manager</p>
+        <p>Containerized apps and server management</p>
       </div>
 
       <div class="features">