OpenEMR on EKS Console Guide

Platform Support: The console supports macOS and Windows. Commands execute in separate Terminal windows (macOS) or PowerShell windows (Windows) to preserve script colors, formatting, and interactivity.

Overview
Features
Installation
Usage
Troubleshooting
Advanced Usage
Best Practices
Keyboard Shortcuts Reference
Support
Technical Details
License

Overview

The OpenEMR on EKS Console is a Terminal User Interface (TUI) built with the Bubbletea Go framework and Lipgloss for styling that provides an intuitive, menu-driven interface for managing your OpenEMR on EKS deployment. Instead of remembering complex command-line arguments, you can navigate through a simple menu and execute common operations with ease.

Platform Support: macOS and Windows. Commands execute in separate Terminal windows (macOS) or PowerShell windows (Windows) to preserve script colors, formatting, and interactivity.

Features

Categorized Menu: Commands grouped into Deployment, Operations, and Information sections
Simple Navigation: Use arrow keys or vim-style j/k to navigate through available commands
Clear Descriptions: Each command includes a brief description of what it does
Interactive Input Prompts: Commands that require arguments display styled inline forms with field validation, Tab/Shift+Tab navigation, and placeholder hints
Destructive Action Safety: Confirmation prompt before irreversible operations like infrastructure destruction
Status Bar: Shows the resolved project root path and console version
Integrated Execution: Commands run directly from the console interface
Error Handling: Clear error messages when commands fail
No Configuration Required: Automatically detects project structure and script locations

Installation

Prerequisites

macOS or Windows operating system
Go 1.25 or later installed on your system
Access to the OpenEMR on EKS project directory
Windows only: Git Bash or WSL installed (required to run .sh scripts)

Quick Start

The console can be launched directly using the provided launcher script:

macOS:

./start_console

Windows:

.\start_console.ps1

The launcher script will:

Check for Go installation
Navigate to the console directory
Download dependencies (if needed)
Build openemr-eks-console on macOS or openemr-eks-console.exe on Windows in the console/ directory
Launch the TUI

Windows Binary: After the first run, a static binary openemr-eks-console.exe is created in the console/ directory. This binary can be launched anytime by double-clicking it, and it will open the console interface for deploying, managing, and monitoring your OpenEMR on EKS infrastructure. The binary is self-contained and includes the embedded project root path, so it will automatically find your project scripts and configuration.

Manual Installation

If you prefer to build and install manually:

cd console
go mod download
go build -o openemr-eks-console main.go
./openemr-eks-console

Or use the provided Makefile (macOS only):

Note: The Makefile is designed for macOS systems only. For Windows, use start_console.ps1 instead.

cd console
make build   # Build the console
make install # Install to /usr/local/bin (requires sudo)
make run     # Build and run

Windows Users: Running start_console.ps1 creates a static binary openemr-eks-console.exe in the console/ directory. This binary can be launched anytime by double-clicking it, and it will open the console interface for deploying, managing, and monitoring your OpenEMR on EKS infrastructure. The binary is self-contained and includes the embedded project root path.

Usage

Launching the Console

Simply run:

./start_console

Navigation

↑/↓ Arrow Keys or k/j: Navigate up and down through the command list
g / Home: Jump to first command
G / End: Jump to last command
Enter: Execute the selected command (opens input form if arguments are needed, or confirmation for destructive actions)
?: Toggle expanded help panel
q, Esc, or Ctrl+C: Quit the console

Input Form Controls

When a command requires arguments (e.g., Restore from Backup, Search Codebase), a styled input form appears:

Tab / ↓: Move to next field
Shift+Tab / ↑: Move to previous field
Enter: Submit (on last field) or advance to next field
Esc: Cancel and return to menu
Home / End: Jump to start/end of text within a field

Required fields are marked with a red asterisk (*). Optional fields show placeholder hints. Validation errors appear if you try to submit with empty required fields.

Available Commands

The console provides access to 11 essential operations organized into three categories:

1. Validate Prerequisites

Script: ../scripts/validate-deployment.sh

Description: Check required tools, AWS credentials, and deployment readiness

What it does:

Verifies required command-line tools are installed (kubectl, aws, helm, jq)
Validates AWS credentials and authentication
Checks Terraform state and infrastructure status
Verifies EKS cluster accessibility
Validates AWS resources (VPC, RDS, ElastiCache, EFS)
Checks Kubernetes namespace and deployment status
Reviews security configuration

When to use: Before any deployment, when troubleshooting, or for routine health checks

2. Quick Deploy

Script: ../scripts/quick-deploy.sh

Description: Deploy infrastructure, OpenEMR, and monitoring stack in one command

What it does:

Deploys Terraform infrastructure (VPC, EKS, RDS, ElastiCache, EFS, S3, etc.)
Deploys OpenEMR application to Kubernetes
Installs comprehensive monitoring stack (Prometheus, Grafana, Loki, Tempo, Mimir, OTeBPF, AlertManager)
Prints login addresses and credentials

When to use: For fresh deployments or when you want to deploy everything in one go

Note: This is a long-running operation. Budget up to 60 minutes: infrastructure plus OpenEMR measured 41 minutes 22 seconds in the OpenEMR 8.2.0 full-run baseline, and the monitoring install/verify/uninstall cycle measured 18 minutes 15 seconds.

3. Check Deployment Health

Script: ../scripts/validate-deployment.sh

Description: Validate current deployment status and infrastructure health

What it does:

Performs the same comprehensive checks as "Validate Prerequisites"
Provides detailed feedback about deployment readiness
Identifies any issues that need attention
Shows current infrastructure state

When to use: After deployment, during troubleshooting, or for routine health monitoring

4. Backup Deployment

Script: ../scripts/backup.sh

Description: Create comprehensive backup of RDS, Kubernetes configs, and application data

What it does:

Creates RDS Aurora cluster snapshot
Exports Kubernetes namespace resources (deployments, services, secrets, configmaps, PVCs)
Backs up application data from EFS volumes
Uploads everything to S3 with encryption and versioning
Generates metadata and restore instructions

When to use: Before major changes, for disaster recovery planning, or as part of regular backup schedule

Note: Requires AWS credentials with appropriate permissions

5. Restore from Backup

Script: ../scripts/restore.sh

Description: Restore infrastructure and application data from a previous backup

Input prompts:

Backup Bucket (required): The S3 bucket name containing the backup
Snapshot ID: Supply an explicit snapshot for the default Python orchestrator. The console currently emits the legacy-only --latest-snapshot flag when this field is empty, which the default orchestrator does not accept.

What it does:

Restores RDS Aurora cluster from snapshot
Bootstraps the namespace, EFS PVC, and IRSA prerequisites
Restores the S3 application-data archive to EFS with a hardened Kubernetes Job
Deploys the current reviewed Kubernetes manifests against the restored data
Validates data integrity after restoration
Provides detailed restore status and reporting

When to use: After a disaster, for testing restore procedures, or to recover from a failed deployment

Note: Requires a prior backup created by "Backup Deployment"

6. Clean Deployment

Script: ../scripts/clean-deployment.sh

Description: Remove application layer while preserving infrastructure

What it does:

Removes OpenEMR Kubernetes namespace and all resources
Cleans up PVCs and PVs
Restarts EFS CSI controller
Removes backup files
Preserves EKS cluster, RDS database, and all infrastructure

When to use: Before fresh deployments, when deployment is corrupted, or for testing scenarios

Safety: Only removes application layer - infrastructure remains intact

7. Destroy Infrastructure

Script: ../scripts/destroy.sh

Description: Completely destroy all infrastructure resources (use with caution)

What it does:

Destroys all Terraform-managed infrastructure
Removes EKS cluster, RDS, ElastiCache, EFS, S3 buckets, VPC, etc.
Cleans up all associated resources
This action is irreversible

When to use: When you want to completely remove the deployment and all associated costs

Warning: This will permanently delete all data and infrastructure. Use with extreme caution.

8. Check Component Versions

Script: ../scripts/version-manager.sh

Description: Check for available updates across all project components

What it does:

Checks versions of all project dependencies
Compares current versions with latest available
Identifies components with available updates
Generates detailed update reports
Shows where versions are referenced in the codebase

When to use: Before upgrades, for version planning, or to stay aware of available updates

Note: Some checks require AWS CLI credentials for EKS add-on version checking

9. Check OpenEMR Versions

Script: ../scripts/check-openemr-versions.sh

Description: Discover available OpenEMR Docker image versions from Docker Hub

Input prompts:

Search Pattern (optional): Filter versions (e.g., 7.0 or 8.0); leave empty to show latest

What it does:

Queries Docker Hub for available OpenEMR versions
Shows latest version, version count, or searches for specific patterns
Displays current deployment version
Provides versioning pattern awareness

When to use: Before version upgrades, checking for new releases, or version planning

10. Search Codebase

Script: ../scripts/search-codebase.sh

Description: Search for terms across the entire codebase

Input prompts:

Search Term (required): The term to search for (e.g., OPENEMR_VERSION, backup, deploy)

What it does:

Searches all files in the project for the specified term
Excludes build artifacts, temporary files, and logs
Displays results with file paths, line numbers, and context
Case-insensitive search by default
Color-coded output for easy reading

When to use: Finding where specific terms, functions, or configurations are used in the codebase

11. Deploy Training Setup

Script: ../scripts/deploy-training-openemr-setup.sh

Description: Deploy OpenEMR with synthetic patient data for training/testing

What it does:

Deploys OpenEMR with pre-configured synthetic patient data
Uses default dataset with configurable number of records
Provides a ready-to-use training environment
Automatically sets up all necessary components

When to use: For training, testing, or demonstration purposes when you need sample patient data

Credential Rotation: Credential rotation scripts (run-credential-rotation.sh, verify-credential-rotation.sh) are currently run directly from the command line. See Credential Rotation Guide for usage instructions.

Command Execution

When you select a command and press Enter:

The console will display "Executing: [Command Name]"
The selected script will run in the background
Output will be displayed in real-time
Any errors will be shown in red
Press Enter, Esc, or Ctrl+C to return to the menu

Troubleshooting

Console Won't Start

Issue: Error: Go is not installed or Error: Go version X is installed, but version 1.25 or later is required

Solution: Install or upgrade Go to version 1.25 or later:

Download from: https://golang.org/dl/
macOS: brew install go (may need brew upgrade go for latest version)
Windows: Download installer from https://golang.org/dl/ and run the installer

Note: The console requires Go 1.25 or later. Check your version with go version.

Scripts Not Found

Issue: Script not found: [path]

Solution: Ensure you're running the console from the project root directory. The console automatically detects the project structure, but if you're in a different location, navigate to the project root first.

Permission Denied

Issue: Scripts fail with permission errors

Solution: The console automatically makes scripts executable, but if issues persist:

chmod +x scripts/*.sh

Build Errors

Issue: Go build fails

Solution:

Ensure Go 1.25 or later is installed: go version
Clean and rebuild: cd console && go clean && go mod tidy && go build
Check for network issues when downloading dependencies
Verify Go version meets minimum requirement: go version | grep -q "go1.2[5-9]\|go[2-9]" (should return 0)

Command Execution Fails

Issue: Commands execute but fail with errors

Solution:

Check the error message displayed in the console
Verify prerequisites are met (AWS credentials, tools installed, etc.)
Review the script documentation in scripts/README.md
Some commands may require additional parameters or environment variables

Advanced Usage

Custom Script Paths

The console automatically detects the project structure. If you need to use custom paths, you can modify the initialModel() function in console/main.go to point to different script locations.

Adding New Commands

To add new commands to the console:

Edit console/main.go
Add a new command entry to the commands slice in initialModel()
Rebuild the console: cd console && go build -o console main.go

Example:

{
    title:       "Your New Command",
    description: "What your command does",
    script:      filepath.Join(scriptsPath, "your-script.sh"),
    args:        []string{"arg1", "arg2"},
},

To add a command with interactive input prompts:

{
    title:       "Your Prompted Command",
    description: "Asks the user for input before running",
    script:      filepath.Join(scriptsPath, "your-script.sh"),
    prompts: []inputField{
        {label: "Name", placeholder: "e.g. my-resource", required: true},
        {label: "Region", placeholder: "us-east-1", required: false, flag: "region"},
    },
},

Fields with flag set produce --flag value arguments; fields without produce positional arguments.

Running Commands Directly

If you prefer to run commands directly without the console, all scripts are available in the scripts/ directory and can be executed manually:

./scripts/validate-deployment.sh
./scripts/quick-deploy.sh
# etc.

Best Practices

Always Validate First: Run "Validate Prerequisites" before any deployment operations
Backup Before Changes: Use "Backup Deployment" before making significant changes
Check Versions Regularly: Use "Check Component Versions" to stay aware of available updates
Monitor Health: Use "Check Deployment Health" for routine monitoring

Keyboard Shortcuts Reference

Key	Action
↑ / k	Move selection up
↓ / j	Move selection down
g / Home	Jump to first command
G / End	Jump to last command
Enter	Execute selected command
Y	Confirm destructive action
?	Toggle help panel
q	Quit console
Esc	Quit / close help / cancel input
Ctrl+C	Quit console

Input Form Keys (when filling in arguments):

Key	Action
Tab / ↓	Next field
Shift+Tab / ↑	Previous field
Enter	Submit form (last field) / next field
Home / End	Start / end of text
Esc	Cancel and return to menu

Support

For issues or questions:

Check the script documentation in scripts/README.md
Review the main project README
Check troubleshooting guides in docs/TROUBLESHOOTING.md
Review individual script help: ./scripts/[script-name].sh --help

Technical Details

Architecture

Framework: Bubbletea (Go TUI framework)
Language: Go 1.25+
Dependencies:
- charm.land/bubbletea/v2 v2.0.0 - TUI framework
- charm.land/lipgloss/v2 v2.0.0 - Styling

Version Management: All Go dependencies are tracked in versions.yaml under the go_packages section for automated version checking and update notifications.

Project Structure

.
├── console/
│   ├── main.go   # Main console application
│   ├── go.mod    # Go module definition
│   └── Makefile  # Build automation
├── scripts/      # Scripts executed by console
└── start_console # Launcher script

Script Execution

The console executes scripts by:

Locating the script file in the scripts/ directory
Making it executable (if needed)
Opening it in a new terminal window:
- macOS: Uses osascript to open a new Terminal window
- Windows: Uses PowerShell Start-Process to open a new PowerShell window (scripts run via bash)
Displaying success/error messages
Handling errors gracefully

Note for Windows users: The console scripts are bash scripts (.sh files). On Windows, these are executed through bash, which requires Git Bash or WSL to be installed and available in your PATH.

License

This console is part of the OpenEMR on EKS project and follows the same license terms.

Uh oh!

FilesExpand file tree

CONSOLE_GUIDE.md

Latest commit

History

CONSOLE_GUIDE.md

File metadata and controls

OpenEMR on EKS Console Guide

Table of Contents

Overview

Features

Installation

Prerequisites

Quick Start

Manual Installation

Usage

Launching the Console

Navigation

Input Form Controls

Available Commands

1. Validate Prerequisites

2. Quick Deploy

3. Check Deployment Health

4. Backup Deployment

5. Restore from Backup

6. Clean Deployment

7. Destroy Infrastructure

8. Check Component Versions

9. Check OpenEMR Versions

10. Search Codebase

11. Deploy Training Setup

Command Execution

Troubleshooting

Console Won't Start

Scripts Not Found

Permission Denied

Build Errors

Command Execution Fails

Advanced Usage

Custom Script Paths

Adding New Commands

Running Commands Directly

Best Practices

Keyboard Shortcuts Reference

Support

Technical Details

Architecture

Project Structure

Script Execution

License