feat: container controls & convienience scripts

Author: jakeaturner

.github/workflows/docker.yml

@@ -57,4 +57,6 @@ jobs:
           context: ./admin
           file: ./admin/Dockerfile
           push: true
-          tags: ghcr.io/crosstalk-solutions/project-nomad-admin:${{ inputs.version }}
+          tags: |
+            ghcr.io/crosstalk-solutions/project-nomad-admin:${{ inputs.version }}
+            ghcr.io/crosstalk-solutions/project-nomad-admin:latest

README.md

@@ -18,7 +18,7 @@ sudo bash install_nomad.sh
 Project N.O.M.A.D. is now installed on your device! Open a browser and navigate to `http://localhost:8080` (or `http://DEVICE_IP:8080`) to start exploring!
 
 ## How It Works
-From a technical standpoint, N.O.M.A.D. is primarily a management UI and API that orchestrates a goodie basket of containerized offline archive tools and resources such as 
+From a technical standpoint, N.O.M.A.D. is primarily a management UI ("Command Center") and API that orchestrates a goodie basket of containerized offline archive tools and resources such as 
 [Kiwix](https://kiwix.org/), [OpenStreetMap](https://www.openstreetmap.org/), [Ollama](https://ollama.com/), [OpenWebUI](https://openwebui.com/), and more.
 
 By abstracting the installation of each of these awesome tools, N.O.M.A.D. makes getting your offline survival computer up and running a breeze! N.O.M.A.D. also includes some additional built-in handy tools, such as a ZIM library managment interface, calculators, and more.
@@ -57,3 +57,25 @@ To test internet connectivity, N.O.M.A.D. attempts to make a request to Cloudfla
 
 ## About Security
 By design, Project N.O.M.A.D. is intended to be open and available without hurdles - it includes no authentication. If you decide to connect your device to a local network after install (e.g. for allowing other devices to access it's resources), you can block/open ports to control which services are exposed.
+
+# Helper Scripts
+Once installed, Project N.O.M.A.D. has a few helper scripts should you ever need to troubleshoot issues or perform maintenance that can't be done through the Command Center. All of these scripts are found in Project N.O.M.A.D.'s install directory, `/opt/project-nomad`
+
+###
+
+###### Start Script - Starts all installed project containers
+```bash
+sudo bash /opt/project-nomad/start_nomad.sh
+```
+###
+
+###### Stop Script - Stops all installed project containers
+```bash
+sudo bash /opt/project-nomad/start_nomad.sh
+```
+###
+
+###### Update Script - Attempts to pull the latest images for the Command Center and its dependencies (i.e. mysql) and recreate the containers. Note: this *only* updates the Command Center containers. It does not update the installable application containers - that should be done through the Command Center UI
+```bash
+sudo bash /opt/project-nomad/update_nomad.sh
+```

admin/app/controllers/system_controller.ts

@@ -1,6 +1,6 @@
 import { DockerService } from '#services/docker_service';
 import { SystemService } from '#services/system_service'
-import { installServiceValidator } from '#validators/system';
+import { affectServiceValidator, installServiceValidator } from '#validators/system';
 import { inject } from '@adonisjs/core'
 import type { HttpContext } from '@adonisjs/core/http'
 
@@ -26,6 +26,17 @@ export default class SystemController {
         }
     }
 
+    async affectService({ request, response }: HttpContext) {
+        const payload = await request.validateUsing(affectServiceValidator);
+        const result = await this.dockerService.affectContainer(payload.service_name, payload.action);
+        if (!result) {
+            response.internalServerError({ error: 'Failed to affect service' });
+            return;
+        }
+        response.send({ success: result.success, message: result.message });
+    }
+
+
     async simulateSSE({ response }: HttpContext) {
         this.dockerService.simulateSSE();
         response.send({ message: 'Started simulation of SSE' })

admin/app/services/docker_service.ts

@@ -5,6 +5,7 @@ import axios from 'axios';
 import logger from '@adonisjs/core/services/logger'
 import transmit from '@adonisjs/transmit/services/main'
 import { inject } from "@adonisjs/core";
+import { ServiceStatus } from "../../types/services.js";
 
 @inject()
 export class DockerService {
@@ -18,6 +19,108 @@ export class DockerService {
     this.docker = new Docker({ socketPath: '/var/run/docker.sock' });
   }
 
+  async affectContainer(serviceName: string, action: 'start' | 'stop' | 'restart'): Promise<{ success: boolean; message: string }> {
+    try {
+      const service = await Service.query().where('service_name', serviceName).first();
+      if (!service || !service.installed) {
+        return {
+          success: false,
+          message: `Service ${serviceName} not found or not installed`,
+        };
+      }
+
+      const containers = await this.docker.listContainers({ all: true });
+      const container = containers.find(c => c.Names.includes(`/${serviceName}`));
+      if (!container) {
+        return {
+          success: false,
+          message: `Container for service ${serviceName} not found`,
+        };
+      }
+
+      const dockerContainer = this.docker.getContainer(container.Id);
+      if (action === 'stop') {
+        await dockerContainer.stop();
+        return {
+          success: true,
+          message: `Service ${serviceName} stopped successfully`,
+        };
+      }
+
+      if (action === 'restart') {
+        await dockerContainer.restart();
+        return {
+          success: true,
+          message: `Service ${serviceName} restarted successfully`,
+        };
+      }
+
+      if (action === 'start') {
+        if (container.State === 'running') {
+          return {
+            success: true,
+            message: `Service ${serviceName} is already running`,
+          };
+        }
+        await dockerContainer.start();
+      }
+
+      return {
+        success: false,
+        message: `Invalid action: ${action}. Use 'start', 'stop', or 'restart'.`,
+      }
+    } catch (error) {
+      console.error(`Error starting service ${serviceName}: ${error.message}`);
+      return {
+        success: false,
+        message: `Failed to start service ${serviceName}: ${error.message}`,
+      };
+    }
+  }
+
+  async getServicesStatus(): Promise<{
+    service_name: string;
+    status: ServiceStatus;
+  }[]> {
+    try {
+      const services = await Service.query().where('installed', true);
+      if (!services || services.length === 0) {
+        return [];
+      }
+
+      const containers = await this.docker.listContainers({ all: true });
+      const containerMap = new Map<string, Docker.ContainerInfo>();
+      containers.forEach(container => {
+        const name = container.Names[0].replace('/', '');
+        if (name.startsWith('nomad_')) {
+          containerMap.set(name, container);
+        }
+      });
+
+      const getStatus = (state: string): ServiceStatus => {
+        switch (state) {
+          case 'running':
+            return 'running';
+          case 'exited':
+          case 'created':
+          case 'paused':
+            return 'stopped';
+          default:
+            return 'unknown';
+        }
+      };
+
+
+      return Array.from(containerMap.entries()).map(([name, container]) => ({
+        service_name: name,
+        status: getStatus(container.State),
+      }));
+    } catch (error) {
+      console.error(`Error fetching services status: ${error.message}`);
+      return [];
+    }
+  }
+
   async createContainerPreflight(serviceName: string): Promise<{ success: boolean; message: string }> {
     const service = await Service.query().where('service_name', serviceName).first();
     if (!service) {

admin/app/services/system_service.ts

@@ -1,15 +1,44 @@
 import Service from "#models/service"
+import { inject } from "@adonisjs/core";
+import { DockerService } from "#services/docker_service";
+import { ServiceStatus } from "../../types/services.js";
 
+@inject()
 export class SystemService {
+  constructor(
+    private dockerService: DockerService
+  ) {}
   async getServices({
     installedOnly = true,
   }:{
     installedOnly?: boolean
-  }): Promise<{ id: number; service_name: string; installed: boolean }[]> {
+  }): Promise<{ id: number; service_name: string; installed: boolean, status: ServiceStatus }[]> {
     const query =  Service.query().orderBy('service_name', 'asc').select('id', 'service_name', 'installed', 'ui_location').where('is_dependency_service', false)
     if (installedOnly) {
       query.where('installed', true);
     }
-    return await query;
+
+    const services = await query;
+    if (!services || services.length === 0) {
+      return [];
+    }
+
+    const statuses = await this.dockerService.getServicesStatus();
+
+    const toReturn = [];
+
+    for (const service of services) {
+      const status = statuses.find(s => s.service_name === service.service_name);
+      toReturn.push({
+        id: service.id,
+        service_name: service.service_name,
+        installed: service.installed,
+        status: status ? status.status : 'unknown',
+        ui_location: service.ui_location || ''
+      });
+    }
+
+    return toReturn;
+
   }
 }

admin/app/validators/system.ts

@@ -2,4 +2,9 @@ import vine from '@vinejs/vine'
 
 export const installServiceValidator = vine.compile(vine.object({
     service_name: vine.string().trim()
-}))
+}));
+
+export const affectServiceValidator = vine.compile(vine.object({
+    service_name: vine.string().trim(),
+    action: vine.enum(['start', 'stop', 'restart'])
+}));

admin/inertia/app/app.tsx

@@ -10,6 +10,7 @@ import { TransmitProvider } from 'react-adonis-transmit'
 import { generateUUID } from '~/lib/util'
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
 import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
+import NotificationsProvider from '~/providers/NotificationProvider'
 
 const appName = import.meta.env.VITE_APP_NAME || 'Project N.O.M.A.D.'
 const queryClient = new QueryClient()
@@ -35,10 +36,12 @@ createInertiaApp({
     createRoot(el).render(
       <QueryClientProvider client={queryClient}>
         <TransmitProvider baseUrl={window.location.origin} enableLogging={true}>
-          <ModalsProvider>
-            <App {...props} />
-            <ReactQueryDevtools initialIsOpen={false} />
-          </ModalsProvider>
+          <NotificationsProvider>
+            <ModalsProvider>
+              <App {...props} />
+              <ReactQueryDevtools initialIsOpen={false} />
+            </ModalsProvider>
+          </NotificationsProvider>
         </TransmitProvider>
       </QueryClientProvider>
     )

admin/inertia/context/NotificationContext.ts

@@ -0,0 +1,28 @@
+import { createContext, useContext } from "react";
+
+export interface Notification {
+  message: string;
+  type: "error" | "success" | "info";
+  duration?: number; // in milliseconds
+}
+
+export interface NotificationContextType {
+  notifications: Notification[];
+  addNotification: (notification: Notification) => void;
+  removeNotification: (id: string) => void;
+  removeAllNotifications: () => void;
+}
+
+export const NotificationContext = createContext<
+  NotificationContextType | undefined
+>(undefined);
+
+export const useNotifications = () => {
+  const context = useContext(NotificationContext);
+  if (!context) {
+    throw new Error(
+      "useNotifications must be used within a NotificationProvider"
+    );
+  }
+  return context;
+};

admin/inertia/hooks/useErrorNotification.ts

@@ -0,0 +1,14 @@
+// Helper hook to show error notifications
+import { useNotifications } from '../context/NotificationContext';
+
+const useErrorNotification = () => {
+  const { addNotification } = useNotifications();
+
+  const showError = (message: string) => {
+    addNotification({ message, type: 'error' });
+  };
+
+  return { showError };
+};
+
+export default useErrorNotification;

admin/inertia/hooks/useInternetStatus.ts

@@ -0,0 +1,27 @@
+// Helper hook to check internet connection status
+import { useQuery } from '@tanstack/react-query';
+import { useEffect, useState } from 'react';
+import { testInternetConnection } from '~/lib/util';
+
+const useInternetStatus = () => {
+    const [isOnline, setIsOnline] = useState<boolean>(false);
+    const { data } = useQuery<boolean>({
+        queryKey: ['internetStatus'],
+        queryFn: testInternetConnection,
+        refetchOnWindowFocus: false, // Don't refetch on window focus
+        refetchOnReconnect: false, // Refetch when the browser reconnects
+        refetchOnMount: false, // Don't refetch when the component mounts
+        retry: 2, // Retry up to 2 times on failure
+        staleTime: 1000 * 60 * 10, // Data is fresh for 10 minutes
+    });
+
+    // Update the online status when data changes
+    useEffect(() => {
+        if (data === undefined) return; // Avoid setting state on unmounted component
+        setIsOnline(data);
+    }, [data]);
+
+    return { isOnline };
+};
+
+export default useInternetStatus;