This commit is contained in:
376
docs/TUI.md
Normal file
376
docs/TUI.md
Normal file
@@ -0,0 +1,376 @@
|
||||
# Terminal User Interface (TUI)
|
||||
|
||||
## Overview
|
||||
|
||||
AtlasOS provides a Terminal User Interface (TUI) for managing the storage system from the command line. The TUI provides an interactive menu-driven interface that connects to the Atlas API.
|
||||
|
||||
## Features
|
||||
|
||||
- **Interactive Menus**: Navigate through system features with simple menus
|
||||
- **Authentication**: Secure login to the API
|
||||
- **ZFS Management**: View and manage pools, datasets, and ZVOLs
|
||||
- **Storage Services**: Manage SMB shares, NFS exports, and iSCSI targets
|
||||
- **Snapshot Management**: Create snapshots and manage policies
|
||||
- **System Information**: View system health and diagnostics
|
||||
- **Backup & Restore**: Manage configuration backups
|
||||
|
||||
## Installation
|
||||
|
||||
Build the TUI binary:
|
||||
|
||||
```bash
|
||||
go build ./cmd/atlas-tui
|
||||
```
|
||||
|
||||
Or use the Makefile:
|
||||
|
||||
```bash
|
||||
make build
|
||||
```
|
||||
|
||||
This creates the `atlas-tui` binary.
|
||||
|
||||
## Configuration
|
||||
|
||||
### API URL
|
||||
|
||||
Set the API URL via environment variable:
|
||||
|
||||
```bash
|
||||
export ATLAS_API_URL=http://localhost:8080
|
||||
./atlas-tui
|
||||
```
|
||||
|
||||
Default: `http://localhost:8080`
|
||||
|
||||
## Usage
|
||||
|
||||
### Starting the TUI
|
||||
|
||||
```bash
|
||||
./atlas-tui
|
||||
```
|
||||
|
||||
### Authentication
|
||||
|
||||
On first run, you'll be prompted to login:
|
||||
|
||||
```
|
||||
=== AtlasOS Login ===
|
||||
Username: admin
|
||||
Password: ****
|
||||
Login successful!
|
||||
```
|
||||
|
||||
### Main Menu
|
||||
|
||||
```
|
||||
=== AtlasOS Terminal Interface ===
|
||||
1. ZFS Management
|
||||
2. Storage Services
|
||||
3. Snapshots
|
||||
4. System Information
|
||||
5. Backup & Restore
|
||||
0. Exit
|
||||
```
|
||||
|
||||
## Menu Options
|
||||
|
||||
### 1. ZFS Management
|
||||
|
||||
**Sub-menu:**
|
||||
- List Pools
|
||||
- List Datasets
|
||||
- List ZVOLs
|
||||
- List Disks
|
||||
|
||||
**Example - List Pools:**
|
||||
```
|
||||
=== ZFS Pools ===
|
||||
1. tank
|
||||
Size: 10TB
|
||||
Used: 2TB
|
||||
```
|
||||
|
||||
### 2. Storage Services
|
||||
|
||||
**Sub-menu:**
|
||||
- SMB Shares
|
||||
- NFS Exports
|
||||
- iSCSI Targets
|
||||
|
||||
**SMB Shares:**
|
||||
- List Shares
|
||||
- Create Share
|
||||
|
||||
**Example - Create SMB Share:**
|
||||
```
|
||||
Share name: data-share
|
||||
Dataset: tank/data
|
||||
Path (optional, press Enter to auto-detect):
|
||||
Description (optional): Main data share
|
||||
SMB share created successfully!
|
||||
Share: data-share
|
||||
```
|
||||
|
||||
**NFS Exports:**
|
||||
- List Exports
|
||||
- Create Export
|
||||
|
||||
**Example - Create NFS Export:**
|
||||
```
|
||||
Dataset: tank/data
|
||||
Path (optional, press Enter to auto-detect):
|
||||
Clients (comma-separated, e.g., 192.168.1.0/24,*): 192.168.1.0/24
|
||||
NFS export created successfully!
|
||||
Export: /tank/data
|
||||
```
|
||||
|
||||
**iSCSI Targets:**
|
||||
- List Targets
|
||||
- Create Target
|
||||
|
||||
**Example - Create iSCSI Target:**
|
||||
```
|
||||
IQN (e.g., iqn.2024-12.com.atlas:target1): iqn.2024-12.com.atlas:target1
|
||||
iSCSI target created successfully!
|
||||
Target: iqn.2024-12.com.atlas:target1
|
||||
```
|
||||
|
||||
### 3. Snapshots
|
||||
|
||||
**Sub-menu:**
|
||||
- List Snapshots
|
||||
- Create Snapshot
|
||||
- List Snapshot Policies
|
||||
|
||||
**Example - Create Snapshot:**
|
||||
```
|
||||
Dataset name: tank/data
|
||||
Snapshot name: backup-2024-12-20
|
||||
Snapshot created successfully!
|
||||
Snapshot: tank/data@backup-2024-12-20
|
||||
```
|
||||
|
||||
### 4. System Information
|
||||
|
||||
**Sub-menu:**
|
||||
- System Info
|
||||
- Health Check
|
||||
- Dashboard
|
||||
|
||||
**System Info:**
|
||||
```
|
||||
=== System Information ===
|
||||
Version: v0.1.0-dev
|
||||
Uptime: 3600 seconds
|
||||
Go Version: go1.21.0
|
||||
Goroutines: 15
|
||||
|
||||
Services:
|
||||
smb: running
|
||||
nfs: running
|
||||
iscsi: stopped
|
||||
```
|
||||
|
||||
**Health Check:**
|
||||
```
|
||||
=== Health Check ===
|
||||
Status: healthy
|
||||
|
||||
Component Checks:
|
||||
zfs: healthy
|
||||
database: healthy
|
||||
smb: healthy
|
||||
nfs: healthy
|
||||
iscsi: stopped
|
||||
```
|
||||
|
||||
**Dashboard:**
|
||||
```
|
||||
=== Dashboard ===
|
||||
Pools: 2
|
||||
Datasets: 10
|
||||
SMB Shares: 5
|
||||
NFS Exports: 3
|
||||
iSCSI Targets: 2
|
||||
```
|
||||
|
||||
### 5. Backup & Restore
|
||||
|
||||
**Sub-menu:**
|
||||
- List Backups
|
||||
- Create Backup
|
||||
- Restore Backup
|
||||
|
||||
**Example - Create Backup:**
|
||||
```
|
||||
Description (optional): Weekly backup
|
||||
Backup created successfully!
|
||||
Backup ID: backup-1703123456
|
||||
```
|
||||
|
||||
**Example - Restore Backup:**
|
||||
```
|
||||
=== Backups ===
|
||||
1. backup-1703123456
|
||||
Created: 2024-12-20T10:30:56Z
|
||||
Description: Weekly backup
|
||||
|
||||
Backup ID: backup-1703123456
|
||||
Restore backup? This will overwrite current configuration. (yes/no): yes
|
||||
Backup restored successfully!
|
||||
```
|
||||
|
||||
## Navigation
|
||||
|
||||
- **Select Option**: Enter the number or letter corresponding to the menu option
|
||||
- **Back**: Enter `0` to go back to the previous menu
|
||||
- **Exit**: Enter `0`, `q`, or `exit` to quit the application
|
||||
- **Interrupt**: Press `Ctrl+C` for graceful shutdown
|
||||
|
||||
## Keyboard Shortcuts
|
||||
|
||||
- `Ctrl+C`: Graceful shutdown
|
||||
- `0`: Back/Exit
|
||||
- `q`: Exit
|
||||
- `exit`: Exit
|
||||
|
||||
## Examples
|
||||
|
||||
### Complete Workflow
|
||||
|
||||
```bash
|
||||
# Start TUI
|
||||
./atlas-tui
|
||||
|
||||
# Login
|
||||
Username: admin
|
||||
Password: admin
|
||||
|
||||
# Navigate to ZFS Management
|
||||
Select option: 1
|
||||
|
||||
# List pools
|
||||
Select option: 1
|
||||
|
||||
# Go back
|
||||
Select option: 0
|
||||
|
||||
# Create SMB share
|
||||
Select option: 2
|
||||
Select option: 1
|
||||
Select option: 2
|
||||
Share name: myshare
|
||||
Dataset: tank/data
|
||||
...
|
||||
|
||||
# Exit
|
||||
Select option: 0
|
||||
Select option: 0
|
||||
```
|
||||
|
||||
## API Client
|
||||
|
||||
The TUI uses an HTTP client to communicate with the Atlas API:
|
||||
|
||||
- **Authentication**: JWT token-based authentication
|
||||
- **Error Handling**: Clear error messages for API failures
|
||||
- **Timeout**: 30-second timeout for requests
|
||||
|
||||
## Error Handling
|
||||
|
||||
The TUI handles errors gracefully:
|
||||
|
||||
- **Connection Errors**: Clear messages when API is unreachable
|
||||
- **Authentication Errors**: Prompts for re-authentication
|
||||
- **API Errors**: Displays error messages from API responses
|
||||
- **Invalid Input**: Validates user input before sending requests
|
||||
|
||||
## Configuration File
|
||||
|
||||
Future enhancement: Support for configuration file:
|
||||
|
||||
```yaml
|
||||
api_url: http://localhost:8080
|
||||
username: admin
|
||||
# Token can be stored (with appropriate security)
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Password Input**: Currently visible (future: hidden input)
|
||||
2. **Token Storage**: Token stored in memory only
|
||||
3. **HTTPS**: Use HTTPS for production API URLs
|
||||
4. **Credentials**: Never log credentials
|
||||
|
||||
## Limitations
|
||||
|
||||
- **Password Visibility**: Passwords are currently visible during input
|
||||
- **No Token Persistence**: Must login on each TUI start
|
||||
- **Basic Interface**: Text-based menus (not a full TUI library)
|
||||
- **Limited Error Recovery**: Some errors require restart
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
1. **Hidden Password Input**: Use library to hide password input
|
||||
2. **Token Persistence**: Store token securely for session persistence
|
||||
3. **Advanced TUI**: Use Bubble Tea or similar for rich interface
|
||||
4. **Command Mode**: Support command-line arguments for non-interactive use
|
||||
5. **Configuration File**: Support for config file
|
||||
6. **Auto-completion**: Tab completion for commands
|
||||
7. **History**: Command history support
|
||||
8. **Color Output**: Colored output for better readability
|
||||
9. **Progress Indicators**: Show progress for long operations
|
||||
10. **Batch Operations**: Support for batch operations
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Connection Errors
|
||||
|
||||
```
|
||||
Error: request failed: dial tcp 127.0.0.1:8080: connect: connection refused
|
||||
```
|
||||
|
||||
**Solution**: Ensure the API server is running:
|
||||
```bash
|
||||
./atlas-api
|
||||
```
|
||||
|
||||
### Authentication Errors
|
||||
|
||||
```
|
||||
Error: login failed: invalid credentials
|
||||
```
|
||||
|
||||
**Solution**: Check username and password. Default credentials:
|
||||
- Username: `admin`
|
||||
- Password: `admin`
|
||||
|
||||
### API URL Configuration
|
||||
|
||||
If API is on a different host/port:
|
||||
|
||||
```bash
|
||||
export ATLAS_API_URL=http://192.168.1.100:8080
|
||||
./atlas-tui
|
||||
```
|
||||
|
||||
## Comparison with Web GUI
|
||||
|
||||
| Feature | TUI | Web GUI |
|
||||
|---------|-----|---------|
|
||||
| **Access** | Local console | Browser |
|
||||
| **Setup** | No browser needed | Requires browser |
|
||||
| **Network** | Works offline (local) | Requires network |
|
||||
| **Rich UI** | Text-based | HTML/CSS/JS |
|
||||
| **Initial Setup** | Ideal for setup | Better for daily use |
|
||||
| **Maintenance** | Good for maintenance | Good for monitoring |
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use TUI for Initial Setup**: TUI is ideal for initial system configuration
|
||||
2. **Use Web GUI for Daily Operations**: Web GUI provides better visualization
|
||||
3. **Keep API Running**: TUI requires the API server to be running
|
||||
4. **Secure Credentials**: Don't share credentials or tokens
|
||||
5. **Use HTTPS in Production**: Always use HTTPS for production API URLs
|
||||
Reference in New Issue
Block a user