TUTORIALS

🚀 Tutorial 1: Your First Deployment with Aether

30–45 min Level: Beginner

📑 Table of Contents¶

System Requirements
Installation Walkthrough
Create a Workload Spec
Validate the Spec
Deploy to Podman
Check Status and View Logs
Stop and Delete
Understanding the TUI Dashboard
Troubleshooting Common Issues
Next Steps

🖥 System Requirements¶

Component	Minimum	Recommended
OS	Linux (x86_64 / aarch64)	Fedora 40+, Ubuntu 24.04+
Rust	1.75+	latest stable
Podman	4.0+	5.0+
kubectl	1.28+ (optional)	1.30+
Disk	500 MB	2 GB
RAM	2 GB	8 GB

💡 Tip: Podman is the only runtime required for this beginner tutorial. Kubernetes and KubeVirt are covered in later guides.

📦 Installation Walkthrough¶

1. Install Rust toolchain¶

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

2. Clone and build Aether¶

git clone https://github.com/example/aether.git
cd aether
cargo build --release

3. Add to your PATH¶

sudo cp target/release/aether /usr/local/bin/

4. Verify the installation¶

aether --version

5. Run the first-time setup wizard¶

aether init

The wizard detects available runtimes, creates the default config at ~/.aether/config.yaml, and ensures the state directory exists.

6. Install shell completions (optional)¶

# Bash
aether completions bash > ~/.local/share/bash-completion/completions/aether

# Zsh
aether completions zsh > ~/.zsh/completions/_aether

# Fish
aether completions fish > ~/.config/fish/completions/aether.fish

📝 Create a Workload Spec¶

Create a file named workload.yaml in your project directory:

# workload.yaml — Aether Universal Workload Specification
apiVersion: aether/v1
kind: Workload

metadata:
  name: hello-web
  owner: my-team
  project: getting-started
  labels:
    app: hello-web
    environment: dev
  annotations:
    description: "A simple web application for the tutorial"

build:
  context: .
  dockerfile: Dockerfile
  registry: ghcr.io/my-org
  buildArgs:
    NODE_ENV: production

requirements:
  cpu: "2"
  memory: 4Gi
  storage: 20Gi

runtime:
  preferred: container          # auto | container | kube | kubevirt | metal
  allow:
    - container
    - kube

network:
  service: false
  serviceType: ClusterIP
  ports:
    - containerPort: 8080
      servicePort: 80
      protocol: TCP

persistence:
  enabled: false
  size: 10Gi
  accessMode: ReadWriteOnce

health:
  liveness:
    path: /healthz
    port: 8080
    initialDelaySeconds: 10
    periodSeconds: 30
  readiness:
    path: /ready
    port: 8080
    initialDelaySeconds: 5
    periodSeconds: 10

Spec anatomy at a glance¶

Section	Purpose
`metadata`	Name, owner, project, labels, annotations
`build`	Dockerfile context, registry, build arguments
`requirements`	CPU, memory, storage, optional GPU
`runtime`	Preferred runtime and allow-list
`network`	Service exposure, port mappings, service type
`persistence`	Persistent volume claims, access modes, storage classes
`health`	Liveness and readiness probes

✅ Validate the Spec¶

Before deploying, always validate:

aether validate

By default, Aether looks for workload.yaml in the current directory. To use a different file:

aether --spec my-workload.yaml validate

A successful validation prints a property table:

✔ Workload specification is valid
✔ Workload 'hello-web' is valid

  Name               hello-web
  Owner              my-team
  Project            getting-started
  CPU                2
  Memory             4Gi
  Storage            20Gi
  Preferred Runtime  Container

🐳 Deploy to Podman¶

Deploy the workload¶

aether run

Aether will:

Evaluate the runtime decision engine (rule-based + AI scoring)
Show an interactive runtime selector (unless --runtime is passed)
Build the container image via Podman
Start the workload instance
Persist the state to ~/.aether/state.json

Override the runtime explicitly¶

aether run --runtime podman

Dry-run mode (preview without executing)¶

aether --dry-run run

This prints what would happen without creating any resources.

📊 Check Status and View Logs¶

Check status¶

aether status hello-web

Sample output:

  Workload   hello-web
  Runtime    podman
  State      running
  Ready      true
  Restarts   0

View logs¶

aether logs hello-web

Follow logs in real-time¶

aether logs hello-web --follow

List all running workloads¶

aether list

┌─────────────┬─────────┬─────────┬──────────────────────┐
│ Name        │ Runtime │ State   │ Created              │
├─────────────┼─────────┼─────────┼──────────────────────┤
│ hello-web   │ podman  │ running │ 2026-04-11T10:30:00Z │
└─────────────┴─────────┴─────────┴──────────────────────┘

Output formats¶

# JSON (machine-readable, great for scripting)
aether --output json list

# YAML
aether --output yaml status hello-web

# Wide table (extra columns)
aether --output wide list

🛑 Stop and Delete¶

Stop a workload (preserves state)¶

aether stop hello-web

Delete a workload (removes state and resources)¶

aether delete hello-web

⚠️ Warning: delete is irreversible. Use --dry-run to preview:
aether --dry-run delete hello-web

Automatic confirmation for CI/CD¶

aether --yes delete hello-web

🖥 Understanding the TUI Dashboard¶

Launch the interactive terminal dashboard:

aether tui

The TUI provides a live view of all deployed workloads with:

Panel	Description
Workload List	All tracked workloads, runtime, state
Status Detail	Selected workload details, health, restart count
Logs	Live log stream from the selected workload
Resource Usage	CPU/Memory utilization gauges

Keyboard shortcuts¶

Key	Action
`j` / `k`	Navigate up/down
`Enter`	Select workload
`l`	Toggle log panel
`q`	Quit dashboard
`r`	Refresh data
`/`	Search / filter

🔧 Troubleshooting Common Issues¶

"Workload not found" when running status or logs¶

Error: Workload 'hello-web' not found.
Hint: Run `aether list` to see deployed workloads.

Cause: The workload has not been deployed yet, or was deleted. Fix: Run aether list and verify the name. Redeploy with aether run.

"No suitable runtime found"¶

Error: No suitable runtime found for workload

Cause: The runtime.allow list in your spec is empty. Fix: Add at least one runtime to the allow list:

runtime:
  preferred: auto
  allow:
    - container

Podman not detected¶

Error: podman binary not found in PATH

Fix: Install Podman:

# Fedora
sudo dnf install podman

# Ubuntu
sudo apt install podman

Validation failures¶

Run aether validate and read the error message carefully. Common issues:

Error	Fix
Missing `metadata.name`	Add a `name` field under `metadata`
Invalid CPU format	Use `"2"` or `"2000m"` (quotes required)
Invalid memory format	Use `4Gi`, `4096Mi`, or `512Ki`
Unknown runtime in allow list	Valid values: `container`, `kube`, `kubevirt`, `metal`

Policy check blocks deployment¶

Error: Policy violation: CPU exceeds maximum allowed (16 cores)

Fix: Either reduce resources in your spec, or skip policy checks:

aether --skip-policy run

⚠️ Use --skip-policy only in development. Production policies exist for a reason.

🎯 Next Steps¶

Congratulations -- you have deployed your first workload with Aether! Here is where to go next:

Tutorial	Topics
02 - Intermediate Workflows	Compose files, migration, output formats
03 - Advanced Features	Policies, secrets, drift detection, plugins
CLI Reference	Complete command reference
Migration Checklist	Pre/post migration procedures

Quick wins to try now¶

# Compare your workload across all runtimes
aether compare

# Get AI-powered runtime recommendations
aether recommend

# Estimate deployment costs across cloud providers
aether cost

# Generate a workload from a template
aether template web-app --workload-name my-app --output my-app.yaml

# Run a policy check
aether policy-check

📚 Full documentation: CLI Reference 🏷 License: Proprietary HyperSDK