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¶
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.
Using Pre-built Images¶
To use the pre-built image from the registry instead of building from source, run:
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:
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.
Using the Wrapper Script (Recommended)¶
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.
-
Install the wrapper: From the root of the
sceptre-phenixrepository, run:# This command installs the `scripts/phenix-wrapper.sh` script to /usr/local/bin/phenix. sudo make install-wrapperWarning
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. -
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)' >> ~/.zshrcZsh completion needs
compinitto be loaded before thesourceline. Frameworks such as Oh My Zsh load it for you; otherwise, addautoload -U compinit && compinitto~/.zshrcabove 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.
📚 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.