nomad_mcp/USER_GUIDE.md

Nomad Job Manager UI - User Guide

This guide provides instructions on how to use the Nomad Job Manager web interface to monitor and manage your Nomad jobs.

Accessing the UI

The Nomad Job Manager UI is available at the root URL of the Nomad MCP service:

http://your-server-address:8000

Interface Overview

The UI is divided into two main sections:

1. Job List (left panel): Displays all jobs in the selected namespace
2. Job Details (right panel): Shows detailed information about the selected job and its logs

Header Controls

• Namespace Selector: Dropdown to switch between different Nomad namespaces
• Refresh Button: Updates the job list with the latest information from Nomad

Managing Jobs

Viewing Jobs

1. Select the desired namespace from the dropdown in the header
2. The job list will display all jobs in that namespace with their:
   • Job ID
   • Type (service, batch, system)
   • Status (running, pending, dead)
   • Action buttons

Job Actions

For each job in the list, you can perform the following actions:

• View: Display detailed information about the job and its logs
• Restart: Stop and restart the job with its current configuration
• Stop: Stop the job (with an option to purge it)

Viewing Job Details

When you click the "View" button for a job, the right panel will display:

1. Job Information:

   • Job ID
   • Status
   • Type
   • Namespace
   • Datacenters

2. Allocation Information (if available):

   • Allocation ID
   • Status
   • Description

3. Logs:

   • Tabs to switch between stdout and stderr logs
   • Scrollable log content

Working with Logs

The logs section allows you to view the output from your job's tasks:

1. Click on a job to view its details
2. Scroll down to the "Logs" section
3. Use the tabs to switch between:
   • stdout: Standard output logs
   • stderr: Standard error logs

The logs are automatically retrieved from the most recent allocation of the job.

Common Tasks

Restarting a Failed Job

1. Find the job in the job list
2. Click the "Restart" button
3. Confirm the restart when prompted
4. The job status will update once the restart is complete

Stopping a Job

1. Find the job in the job list
2. Click the "Stop" button
3. Choose whether to purge the job when prompted
4. Confirm the stop operation
5. The job will be removed from the list if purged, or shown as "dead" if not purged

Troubleshooting a Job

1. Select the job to view its details
2. Check the status and any error messages in the job details
3. Review the stderr logs for error information
4. If needed, restart the job to attempt recovery

Tips and Tricks

• Regular Refreshes: Use the refresh button to get the latest job status
• Log Navigation: For large log files, use your browser's search function (Ctrl+F) to find specific messages
• Multiple Namespaces: Switch between namespaces to manage different environments (development, production, etc.)
• Job Status Colors:
  • Green: Running jobs
  • Orange: Pending jobs
  • Red: Dead or failed jobs

Troubleshooting the UI

If you encounter issues with the UI:

1. UI Doesn't Load:

   • Check that the Nomad MCP service is running
   • Verify your browser can reach the server
   • Check browser console for JavaScript errors

2. Jobs Not Appearing:

   • Ensure you've selected the correct namespace
   • Verify that your Nomad server is accessible
   • Check that your Nomad token has permission to list jobs

3. Cannot Perform Actions:

   • Verify that your Nomad token has appropriate permissions
   • Check the browser console for API errors
   • Review the Nomad MCP service logs for backend errors

Next Steps

For more advanced operations or programmatic access, consider:

1. Using the REST API directly (see the API documentation)
2. Setting up Claude AI integration for natural language job management
3. Creating job configuration mappings for repository-based job management