Skip to content

phēnix

phēnix provides a framework for defining, deploying, and managing complex cyber-physical experiments. It orchestrates virtual machines, networks, and applications to create realistic emulation environments.

🚀 Getting Started

The easiest way to get phēnix running is using Docker.

Prerequisites

  • Linux environment (Ubuntu 22.04+ recommended)
  • Docker & Docker Compose

Running with Docker

The phēnix repository includes a docker-compose.yml file in the docker/ directory for running phēnix and its dependencies.

1. Clone the Repository

git clone https://github.com/sandialabs/sceptre-phenix.git
cd sceptre-phenix/docker

2. Start Services

The docker-compose.yml file allows you to either build from source or use a pre-built image.

Building from Source (Default)

This is the recommended method for development.

docker compose up -d --build
Using Pre-built Images

To use the pre-built image from the registry instead of building from source, run:

docker compose up -d --pull always

This will pull the latest images specified in the image key for each service (e.g., ghcr.io/sandialabs/sceptre-phenix/phenix:main and ghcr.io/sandia-minimega/minimega:latest) and skip the build step.

Each GitHub release attaches SPDX JSON software bills of materials (SBOMs) of the phenix and JIT UI images and of the Debian package, listing the packages and Go modules each one contains.

3. Check Status

After starting the services with either method, view the logs to see the initialization progress:

docker compose logs -f

Note

The Docker image includes the user apps from the sceptre-phenix-apps repository.

To build the image with Podman instead, run podman build -f docker/Dockerfile -t phenix . from the repository root. See podman/README.md for running phēnix and minimega as a Podman pod.

Accessing the CLI & Shell Completion

With phenix running in a container, you can execute commands. For the best experience, including shell (tab) completion, you should install the provided wrapper script.

The phenix repository includes a wrapper script that simplifies running phenix commands against the Docker container and is required for shell completion to work correctly.

  1. Install the wrapper: From the root of the sceptre-phenix repository, run:

    # This command installs the `scripts/phenix-wrapper.sh` script to /usr/local/bin/phenix.
    sudo make install-wrapper
    

    Warning

    If you previously used a shell alias for phenix (e.g., alias phenix="docker exec ..."), you must remove it from your shell profile (e.g., ~/.bashrc, ~/.zshrc) for the wrapper and completion to work.

  2. Enable Shell Completion: Add the completion script to your shell's startup file so it's available in new terminal sessions.

    # For Bash (requires the bash-completion package)
    echo 'source <(phenix completion bash)' >> ~/.bashrc
    
    # For Zsh
    echo 'source <(phenix completion zsh)' >> ~/.zshrc
    

    Zsh completion needs compinit to be loaded before the source line. Frameworks such as Oh My Zsh load it for you; otherwise, add autoload -U compinit && compinit to ~/.zshrc above that line.

    Now, you can use Tab to autocomplete commands, flags, and even dynamic values like experiment and VM names. For more details, run phenix completion --help.

Manual Execution

You can also execute commands directly, but shell completion will not work.

docker exec -it phenix phenix <command>

📚 Documentation

  • Configuration: Learn about Topologies, Scenarios, and Experiments.
  • Settings: Configure the phÄ“nix daemon (logging, storage, UI).
  • Experiments: Manage the lifecycle of your experiments.
  • Builder: Draw topology diagrams and publish them as Topology and Experiment configs.
  • Apps: Extend functionality with Apps.
  • Logging: Learn about the logging facilities in phÄ“nix and how to increase verbosity
  • API: Explore the interactive Swagger/OpenAPI docs served by phÄ“nix and integrate with the API.