Skip to main content

​
Introduction

Generating an EVE-OS image is the first step before installing EVE-OS on an edge device, live-booting from portable storage, or upgrading an existing installation. The procedures below use Docker to download EVE-OS from Docker Hub and produce a ready-to-flash image file. The current EVE-OS LTS version is 16.0.0-lts.

​
Prerequisites

  • You have read EVE-OS Overview and are familiar with EVE-OS image types.
  • Docker is installed and running on your local machine.
  • You know your cluster’s hostname (for example, zedcloud.gmwtus.zededa.net). If your enterprise uses zedcloud.zededa.net, the default, you do not need a custom server configuration file.

​
Configure Your Cluster Endpoint

During first boot, an edge device running EVE-OS connects to a Edge Infrastructure Services cluster to receive its initial configuration. Nodes connect to zedcloud.zededa.net by default. If your enterprise is on a different cluster, create a server configuration file before generating your image.

​
On macOS or Linux

  1. Open your terminal and navigate to a working directory.
  1. Create a directory for your custom configuration.
  1. Write your cluster hostname to a file named server.

​
On Windows

  1. Open PowerShell and navigate to a working directory.
  1. Create a directory for your custom configuration.
  1. Write your cluster hostname to a file named server.
Note: If you want to customize install-time storage parameters (for example, disk assignments or ZFS RAID configuration), include a grub.cfg file in your eve-overrides directory before running the docker run command. If no grub.cfg is present, EVE-OS uses default values. For configuration examples, see Configure grub.cfg for EVE-OS Multidisk Installation.

​
Choose an Image Type and Download

Open your terminal (macOS/Linux) or PowerShell (Windows) and run one of the following procedures based on your intended use. All examples use the latest LTS version (16.0.0-lts). If you need a different version or want to verify available releases, see Choose an Alternate Version before proceeding.

​
Installer Image (for USB or PXE installation)

Use this to install EVE-OS onto an edge device’s onboard storage.
  1. Navigate to a directory of your choice.
  1. Create a directory for your EVE-OS image and navigate into it.
  1. Download and generate your EVE-OS installer image. Choose the command for your node’s hardware architecture. If your controller cluster is zedcloud.zededa.net, omit the -v $HOME/eve-overrides:/in flag.
macOS/Linux — AMD64:
macOS/Linux — ARM64:
Windows — AMD64:
Windows — ARM64:
  1. Verify the file was created.
  1. Proceed to Flash an EVE-OS Installer or Live Image.

​
Live Image (for live-booting from USB or SD)

Use this to boot EVE-OS from portable storage without installing to onboard storage.
  1. Navigate to a directory of your choice.
  1. Create a directory for your EVE-OS image and navigate into it.
  1. Download and generate your EVE-OS live image. Choose the command for your node’s hardware architecture. If your controller cluster is zedcloud.zededa.net, omit the -v $HOME/eve-overrides:/in flag.
macOS/Linux — AMD64:
macOS/Linux — ARM64:
Windows — AMD64:
Windows — ARM64:
  1. Copy and save the soft serial number printed in the last line of output (a UUID string). You will need it when onboarding the node.
  2. Verify the file was created.
  1. Proceed to Flash an EVE-OS Installer or Live Image.

​
Rootfs Image (for updating existing EVE-OS installations)

Rootfs images are uploaded to Edge Infrastructure Services to update nodes remotely. A server configuration file is not required for rootfs images.
  1. Navigate to a directory of your choice.
  1. Create a directory for your EVE-OS image and navigate into it.
  1. Download and generate your EVE-OS rootfs image. Choose the command for your node’s hardware architecture.
macOS/Linux — AMD64:
macOS/Linux — ARM64:
Windows — AMD64:
Windows — ARM64:
  1. Verify the file was created.
  1. Proceed to Add a rootfs EVE-OS Image to Your Enterprise.

​
Optional: Choose an Alternate Version

Most deployments use the latest LTS version. To use a different version:
  1. Find available versions on the EVE-OS GitHub Releases page.
  2. Determine the image name by combining version, hypervisor, and architecture. For example: 16.0.0-lts-kvm-amd64.
  3. Verify the image is available on Docker Hub by searching the Tags tab.

​
Raspberry Pi Notes

For Raspberry Pi 4 or 5 Model B devices (ARM64, minimum 4 GB RAM), use a live image with a 16 GB or larger microSD card. Use the ARM64 live image commands above.

​
Next Steps

Add a rootfs EVE-OS Image to Your Enterprise

Upload a rootfs image to manage EVE-OS versions across your fleet.