prole/docs/ncurses-installer.md

Ncurses Installer Interface

Overview

The Knoe Database Installer now supports a command-line, ncurses-based interface as an alternative to the GUI. This allows installation on headless systems, remote servers via SSH, or any environment where a graphical interface is unavailable or undesirable.

Usage

From Source

To run the installer with the ncurses interface:

./install.py --no-gui

To run the traditional GUI interface:

./install.py --gui

To run with auto-detection (uses GUI if display available, otherwise ncurses):

./install.py

From Built Binary

# Auto-detect (default)
./dist/Knoe\ Installer.app/Contents/MacOS/knoe-installer

# Force ncurses mode
./dist/Knoe\ Installer.app/Contents/MacOS/knoe-installer --no-gui

# Force GUI mode
./dist/Knoe\ Installer.app/Contents/MacOS/knoe-installer --gui

# Or double-click the .app in Finder for GUI

Features

Same Screen Flow

The ncurses interface maintains the exact same screen order and operations as the GUI:

1. Welcome - Introduction and overview
2. Dependencies Summary - View all dependencies
3. Network Scan - Network configuration and scanning
4. Environment Setup - Configure KNOE_HOME and environment variables
5. Kerberos Configuration - Set up Kerberos authentication
6. Database Creation - Initialize database namespace and credentials
7. Build Container - Docker image build process
8. Initialize Cluster - PostgreSQL cluster setup
9. Initialization Scripts - Run database init scripts
10. Deploy CNPG - CloudNativePG deployment
11. Create Installer - Generate installation media

Navigation

The ncurses interface supports multiple navigation methods:

Keyboard Shortcuts:

• ↑/↓ or k/j - Navigate between screens
• ←/→ or h/l - Move between footer buttons
• Enter - Activate selected button
• n - Next screen
• p - Previous screen
• q or Q - Quit installer

Visual Layout:

• Header - Shows installer title and status messages
• Sidebar - Navigation menu showing all screens (left)
• Content Area - Main screen content (right)
• Footer - Action buttons (Previous, Next, Quit)

Architecture

The ncurses implementation shares the same business logic (KnoeController) as the GUI, ensuring consistent behavior across both interfaces.

Key Components:

1. knoe/ncurses_ui.py - UI primitives

   • CursesWindow - Basic window wrapper with rendering helpers
   • TerminalConsole - Scrollable console output
   • NavFooter - Navigation button bar
   • InputField - Text input widget
   • Checkbox - Checkbox widget

2. knoe/ncurses_installer.py - Main installer class

   • KnoeNcursesInstaller - Screen management and rendering
   • run_ncurses_installer() - Entry point for ncurses mode

3. install.py - Modified to support --no-gui argument

   • Parses command-line arguments
   • Routes to either Tk GUI or ncurses interface
   • Both modes use shared KnoeController

Development

Adding New Screens

To add a new screen to the ncurses interface:

1. Register the screen in _register_screens():

self.pages.append(("new_screen_id", self._render_new_screen))

2. Implement the render method:

def _render_new_screen(self):
    win = CursesWindow(self.main_content_win)
    win.render_title("New Screen Title", y=2)
    win.render_paragraph("Screen description...", y=5)
    # Add more content...

3. Add navigation item to sidebar in _render_sidebar():

("New Screen", "new_screen_id"),

Customizing Navigation Logic

Override _on_next() and _on_prev() methods to implement custom screen flow logic, similar to the GUI version's on_next() and on_prev() methods.

Limitations

The initial implementation provides basic screen rendering and navigation. Advanced features from the GUI may need additional implementation:

• Interactive input fields (passwords, text entry)
• Real-time console output during long-running operations
• Progress bars and spinners
• Complex form validation
• Dynamic dependency screen insertion

These features can be added incrementally as needed.

Testing

Test the ncurses interface:

# Verify modules load correctly
python3 -c "from knoe.ncurses_installer import run_ncurses_installer; print('OK')"

# Run the installer
./install.py --no-gui

# View help
./install.py --help

Troubleshooting

Terminal Too Small: If your terminal window is too small, the interface may not render correctly. Resize your terminal to at least 80x24 characters (larger recommended).

Colors Not Showing: Some terminals may not support colors. The interface will fall back to monochrome display automatically.

Keyboard Input Not Working: Ensure your terminal emulator is sending the correct escape sequences for arrow keys. Try using h/j/k/l as alternatives.

Future Enhancements

Potential improvements for the ncurses interface:

1. Interactive Forms - Full input field support for passwords, text entry
2. Real-time Logs - Streaming console output during builds/deployments
3. Progress Indicators - Visual feedback for long operations
4. Color Themes - Customizable color schemes
5. Mouse Support - Click navigation in supported terminals
6. Validation - Form validation with error messages
7. Help System - Context-sensitive help screens