Getting Started with Substation¶

Welcome to Substation! This guide will help you understand the concepts and get started with the OpenStack TUI (Terminal User Interface).

Overview¶

Substation provides a powerful terminal-based interface for managing OpenStack infrastructure. Whether you're managing a small development cloud or a large production environment, Substation streamlines your operational workflows.

Substation Dashboard

Installation and Configuration¶

Before using Substation, you'll need to install it and configure your OpenStack credentials:

Installation Guide - Install via Docker, pre-built binary, or build from source
Configuration Guide - Set up clouds.yaml with your OpenStack credentials

Quick Install¶

Using Docker¶

# Docker (easiest)
docker run --volume ~/.config/openstack:/root/.config/openstack \
           --interactive --tty --env TERM --rm \
           ghcr.io/cloudnull/substation/substation:latest

Using Pre-Built Binary¶

# Or download binary
curl -L "https://github.com/cloudnull/substation/releases/latest/download/substation-$(uname -s)-$(uname -m)" -o substation
chmod +x substation
sudo mv substation /usr/local/bin/

Quick Configuration¶

mkdir -p ~/.config/openstack
cat > ~/.config/openstack/clouds.yaml << 'EOF'
clouds:
  mycloud:
    auth:
      auth_url: https://keystone.example.com:5000/v3
      username: operator
      password: secret
      project_name: operations
      project_domain_name: default
      user_domain_name: default
    region_name: RegionOne
EOF
chmod 600 ~/.config/openstack/clouds.yaml

See the guides above for complete details on all installation methods, authentication options, and configuration settings.

First Steps¶

1. Launch Substation¶

Start Substation with your configured cloud:

substation --cloud mycloud

When you start Substation, you'll see the main dashboard showing an overview of your OpenStack resources:

Substation Startup

Initial Loading:

Phase 1: Critical resources (servers, networks, flavors) load first (~1s)
Phase 2: Secondary resources (volumes, images, keypairs) load next (~2s)
Phase 3: Expensive resources (ports, security groups) load in background (~5s)

2. Understanding the Dashboard¶

The dashboard shows:

Resource Summary: Count of servers, networks, volumes, images
Recent Activity: Latest changes in your cloud
Health Status: OpenStack service health indicators
Performance Metrics: Cache hit rate, API response times

Substation emphasizes command-based navigation as the primary method. This approach is discoverable, forgiving, and teaches you the interface as you learn.

Your First Command:

:                    Press colon to enter command input
: <Tab>              Press Tab to see all available commands
: servers<Enter>     Type "servers" and press Enter to navigate

Command Discovery Features:

Tab Completion: Press : then Tab to see all available commands
Auto-Complete: Type :serv<Tab> to complete to :servers
Fuzzy Matching: :servrs suggests :servers (handles typos)
Command History: Use Up/Down arrows to recall previous commands
Multiple Aliases: :servers, :srv, :s, :nova all work

Progressive Learning Path:

Week 1: Use full command names (:servers, :networks, :volumes)
Discoverable and self-documenting
Tab completion teaches you the commands
Week 2: Learn common aliases (:srv, :net, :vol)
Faster typing with shorter names
Still clear what you're doing
Week 3+: Master short aliases (:s, :n, :v)
Very fast navigation for experienced users
Command input remains the primary method

4. Navigate Between Views¶

Command-Based Navigation (Recommended):

Command	Aliases	Description
`:dashboard`	`:dash`, `:d`	Resource overview and health
`:servers`	`:srv`, `:s`, `:nova`	Compute instances (VMs)
`:networks`	`:net`, `:n`, `:neutron`	Virtual networks
`:volumes`	`:vol`, `:v`, `:cinder`	Block storage
`:images`	`:img`, `:i`, `:glance`	OS images and snapshots
`:flavors`	`:flav`, `:f`	Instance sizes/types
`:servergroups`	`:srvgroups`, `:sg`, `:g`	Anti-affinity groups
`:securitygroups`	`:secgroups`, `:e`	Firewall rules
`:subnets`	`:sub`, `:u`	Network subnets
`:ports`	`:p`	Network interfaces
`:routers`	`:rtr`, `:r`	Virtual routers
`:floatingips`	`:fips`, `:l`	Public IP addresses
`:barbican`	`:secrets`, `:b`	Secrets management
`:swift`	`:objects`, `:j`	Object storage

5. Working with Resource Lists¶

Navigate Lists:

^/v or j/k    Move selection up/down
Page Up/Down  Scroll by page
Home/End      Jump to start/end

View Details:

Navigate to resource view: :servers<Enter>
Use arrow keys to select a server
Press Space or Enter to view full details
Press Esc to return to the list

Substation Image Show

6. Searching for Resources¶

Local Search (fast, filters current view):

/ (slash)     Start local search
Type query    Results filter as you type
Esc           Clear search

Cross-Service Search:

:search<Enter>     Open advanced search (or :find<Enter> or :z<Enter>)
Type query         Searches Nova, Neutron, Cinder, Glance, Keystone, Swift
Enter              Execute search (< 500ms target)

7. Refreshing Data¶

Command-Based:

:refresh<Enter>         Refresh current view (uses cache if available)
:cache-purge<Enter>     Purge ALL caches and force fresh data from API

Note: Using :cache-purge clears L1, L2, and L3 caches. Next operations will be slower while cache rebuilds.

8. Creating Resources¶

Example: Creating a Server¶

Navigate to servers: :servers<Enter>
Create server: :create<Enter> (or :new<Enter> or :add<Enter>)
Fill in the form:
Server name
Select flavor (instance size)
Select image (OS)
Select network(s)
Optional: Add security groups, keypairs
Press Enter to create
Watch real-time status as server builds

Context-Aware Action Commands¶

These commands adapt to your current view:

Command	Aliases	Action	Context
`:create`	`:new`, `:add`	Create resource	All resource lists
`:delete`	`:remove`, `:rm`	Delete selected	All resources
`:start`	`:boot`	Start server	Server view
`:stop`	`:shutdown`	Stop server	Server view
`:restart`	`:reboot`	Restart server	Server view

Other Creation Workflows¶

Networks: :networks<Enter> then :create<Enter>
Volumes: :volumes<Enter> then :create<Enter>
Security Groups: :securitygroups<Enter> then :create<Enter>

Essential Commands Reference¶

Global Commands¶

Command	Aliases	Description
`:help`	`:?`	Context-aware help for current view
`:quit`	`:exit`, `:q`	Exit Substation
`:refresh`	`:reload`	Refresh current view data
`:cache-purge`	`:clear-cache`	Clear ALL caches (use when data is stale)
`:reload-all`	-	Reload all modules (advanced)
`:search`	`:find`, `:z`	Cross-service search
`:dashboard`	`:dash`, `:d`	Return to dashboard

Key	Action	Alternative
`^/v`	Navigate up/down	`j/k` (vim-style)
`Page Up/Down`	Scroll by page	-
`Home/End`	Jump to start/end	`g/G` (vim-style)
`Space`	View details	`Enter`
`/`	Local search/filter	-
`Esc`	Go back	-

Resource Management¶

Command	Aliases	Context
`:create`	`:new`, `:add`	Create resource in any list
`:delete`	`:remove`, `:rm`	Delete selected resource

Common Workflows¶

Workflow 1: List Your Servers¶

# Launch Substation
substation --cloud mycloud

# Enter command input and navigate to servers
:servers<Enter>     # Or :srv<Enter> or :s<Enter>

# Use ^/v to navigate
# Press Space to view details
# Press Esc to go back

Workflow 2: Create a New Server¶

# Launch Substation
substation --cloud mycloud

# Navigate to servers and create
:servers<Enter>     # Navigate to servers view
:create<Enter>      # Open create server form

# Fill in:
#   - Name: web-server-01
#   - Flavor: m1.medium
#   - Image: Ubuntu 22.04
#   - Network: private-network
# Press Enter to create

Workflow 3: Search Across All Resources¶

# Launch Substation
substation --cloud mycloud

# Open search
:search<Enter>      # Or :find<Enter> or :z<Enter>

# Type: "prod"
# Press Enter
# Results show all resources matching "prod" from:
#   - Servers (Nova)
#   - Networks (Neutron)
#   - Volumes (Cinder)
#   - Images (Glance)
#   - Users (Keystone)
#   - Containers (Swift)

Workflow 4: Manage Server Lifecycle¶

# Start server
:servers<Enter>     # Navigate to servers
# Select stopped server with ^/v
:start<Enter>       # Start server (or :boot<Enter>)

# Stop server
# Select running server with ^/v
:stop<Enter>        # Stop server (or :shutdown<Enter>)

# Restart server
# Select running server with ^/v
:restart<Enter>     # Restart server (or :reboot<Enter>)

# Delete server
# Select server to delete with ^/v
:delete<Enter>      # Delete server (confirmation required)

Workflow 5: Force Fresh Data¶

# When your data looks stale or wrong
:cache-purge<Enter>  # Purge ALL caches (or :clear-cache<Enter> or :cc<Enter>)
:refresh<Enter>      # Refresh current view (or :reload<Enter>)
# Fresh data loaded from OpenStack API (slower, but accurate)

Troubleshooting¶

If you encounter issues, consult the comprehensive troubleshooting guide:

Troubleshooting Guide - Solutions to common problems

Quick Troubleshooting Tips:

Authentication Failed:

Verify auth_url includes /v3
Check domain fields are present
Test with: substation --cloud mycloud --wiretap

Slow Performance:

Most likely your OpenStack API is slow, not Substation
Enable wiretap to measure: substation --cloud mycloud --wiretap
Check logs: tail -f ~/substation.log | grep "ms)"

Stale Data:

Use :cache-purge<Enter> (or :cc<Enter>) to purge all caches
Use :refresh<Enter> (or :reload<Enter>) to refresh current view

For detailed troubleshooting, connection issues, performance debugging, and more, see the Troubleshooting Guide.

Next Steps¶

Now that you're up and running, explore:

Navigation Guide - Master all keyboard shortcuts
Common Workflows - Everyday operations and best practices
OpenStack Integration - Which OpenStack services are supported
Performance - Tuning cache settings for your environment
Architecture - Understanding how Substation works
Troubleshooting - Solutions to common problems

Key Concepts¶

Understanding these concepts will help you use Substation effectively:

Caching - How the multi-level cache is designed to reduce API calls by 60-80%
Search - Local search vs. cross-service advanced search
Security - How credentials are protected and encrypted
Features - Complete feature overview

Getting Help¶

Built-in Help: Press ? at any time for context-aware help
Documentation: Complete guides in this documentation site
GitHub Issues: Report bugs and request features
FAQ: Common questions
Logs: Enable --wiretap and check ~/substation.log for debugging