{"id":19199582,"url":"https://github.com/lf-edge/eden","last_synced_at":"2025-05-16T05:06:48.201Z","repository":{"id":37542127,"uuid":"250377978","full_name":"lf-edge/eden","owner":"lf-edge","description":"Eden is where EVE and Adam get tried and tested:","archived":false,"fork":false,"pushed_at":"2025-03-18T00:18:53.000Z","size":39220,"stargazers_count":52,"open_issues_count":47,"forks_count":50,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-04-08T15:13:40.634Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://projecteve.dev","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lf-edge.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-03-26T21:41:57.000Z","updated_at":"2025-04-07T15:11:46.000Z","dependencies_parsed_at":"2023-02-18T10:00:44.160Z","dependency_job_id":"7e21da37-a42c-4b69-a237-1a244a3e6dbd","html_url":"https://github.com/lf-edge/eden","commit_stats":{"total_commits":976,"total_committers":42,"mean_commits":"23.238095238095237","dds":0.507172131147541,"last_synced_commit":"68dba0e2e36d6e59b8b78120bbb3b19a77985b12"},"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lf-edge%2Feden","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lf-edge%2Feden/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lf-edge%2Feden/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lf-edge%2Feden/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lf-edge","download_url":"https://codeload.github.com/lf-edge/eden/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254471061,"owners_count":22076585,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T12:27:55.003Z","updated_at":"2025-05-16T05:06:43.186Z","avatar_url":"https://github.com/lf-edge.png","language":"Go","readme":"# Eden\n\nEden is the simplest way to setup \u0026 test [EVE](https://github.com/lf-edge/eve)\nand [Adam](https://github.com/lf-edge/adam).\n\nEden is a management harness that provides two layers of management.\n\n* infrastructure: deploy and/or delete nodes running [EVE](https://github.com/lf-edge/eve),\n  controller [Adam](https://github.com/lf-edge/adam) and [software-defined networks](./sdn/README.md)\n  between EVE and the controller\n* tasks: execute on EVE, via the controller, one or more tasks\n\nEden is particularly suited to running tests and test suites. These tests must\nmeet eden's test API. This repository also includes a framework for simplify\nrunning the tests on the managed EVE via Adam, and reporting on\nresults.\n\nEden is inspired by Kubernetes workflows and CLI\n\nNote that EVE by itself without a controller is useless in practice. It retrieves its entire\nconfiguration from the controller, and has no console commands that can be used standalone,\nlike general-purpose Linux distributions. You use the controller to tell EVE which workloads\nyou want to run. EVE, in turn, runs those workloads in containers or VMs.\n\nEVE supports the following workload formats:\n\n* OCI image from any OCI compliant registry\n* OS image in qcow2 format\n* OS image in raw format\n\nEden is controlled by a single (secretly-named) command `eden`.\nIt has multiple sub-commands and options. Run `eden help` to see sub-commands.\n\n## Running Eden\n\nYou need at least two devices, either or both of which can be virtual:\n\n* Edge: this is the device on which you will run EVE, and launch tasks such as tests.\n* Manager: this is where you will run Eden and, optionally, all of the management components.\n\nA typical eden workflow is:\n\n1. install the [prerequisites](#prerequisites)\n1. create a named context to store all of your configuration - `eden config add \u003cname\u003e`\n1. (optional) set options for the context - `eden config set \u003cname\u003e [options...]`\n1. run setup - `eden setup`, which extracts an eve-os qcow2 disk image from the docker image named in the context\n1. start Eden's components - `eden start`\n   * if running EVE as qemu, entirely under eden control, it will start automatically\n   * if running EVE as a separate EVE device:\n     1. create or download the EVE image you want\n     1. flash the image to the device's storage\n     1. start the device\n1. onboard EVE - `eden eve onboard`, explicitly allowing it to connect to the controller\n1. use the Eden CLI to perform tasks, such as install apps or run tests\n1. terminate Eden's components and, optionally, EVE - `eden stop`\n1. clean up - `eden clean`\n\nTo customize the device on which EVE is running, or the image launched, see\n[docs/eve-images.md](./docs/eve-images.md).\n\n### Prerequisites\n\nOn the manager, you need:\n\n* the `eden` binary\n* [docker](https://docker.com), to run eden's components, including the ability to execute commands. For Linux:\n\n```console\nsudo usermod -aG docker $USER\nnewgrp docker\n```\n\n* test binaries - eden ships with pre-compiled ones\n* a text editor to configure the system and create test scenarios\nand scripts using `eden`\n\nEden itself -- the main executable file `eden`,\ncomponents, and tests -- ships as stand-alone applications\nor docker images. You do not need to install and configure the development\nenvironment on your computer.\n\nThe manager hosts:\n\n* Eden - control layer CLI\n* Adam - the controller, running as a daemon process\n* SDN - software-defined networking between EVE (in Qemu) and the controller (to emulate various connectivity scenarios)\n* Redis - the log database, running as a daemon process\n* Eserver - the image/file database to expose http and ftp content for downloading to the edge device\n* Registry - an OCI-compliant registry to expose images for downloading to the edge device\n\nEden currently does not support interfacing with a commercial controller,\nalthough it is planned for the future.\n\n![Components](/eden_eve_components.png)\n\nAs the manager hosts the controller, which the edge device must connect to,\nthe edge device _must_ be able to connect via network to port 3333.\n\n![Architecture](/Eden_eve_architecture.png)\n\nFor the edge device, you need an [EVE](https://github.com/lf-edge/eve) OS image\nto install.\n\n**Important Note:** EVE's strong security model allows it to only connect to one\ncontroller, during onboarding. Once onboarded EVE will **not** switch its\nallegiance to any other controller. You simply cannot change the registered\ncertificates or controller IP for an onboarded device. This requires that you be\nspecify the right IP of the target controller when creating the EVE image.\n\nThere are additional requirements for certain use cases:\n\n#### Local Virtual Device\n\nIf you intend to run EVE in a virtual local device, you also will need:\n\n* qemu version 4.x or higher\n* Linux: [KVM](https://www.linux-kvm.org/page/Main_Page), including the ability to execute commands. For Linux:\n\n```console\n  sudo usermod -aG kvm $USER\n  newgrp kvm\n```\n\n* macOS: [machyve](https://github.com/machyve/xhyve) or [Parallels](./docs/parallels.md)\n* `telnet`\n* squashfs tools, available, depending on your OS, as `squashfs` or `squashfs-tools`\n\nEVE uses virtualization; to run in VM-based environments, see [the cloud document](./docs/virtual-eve.md).\n\n#### Raspberry Pi\n\nIf you want to use Eden with Raspberry Pi on Linux, you also need to install\n`binfmt-support` and `qemu-user-static`.\n\n### Quickstart Guides\n\nAll of the quickstart guides get you running quickly, and assume you already have\neden installed.\nThey start the official [nginx](https://hub.docker.com/_/nginx) image as a container,\nserving the content of [./data/helloeve/](./data/helloeve ) on port 8028. You will be able to access it via `http://\u003cEVE IP\u003e:8028`.\nNote that if you are running EVE as virtual device in Qemu with SDN enabled, you will not be able to\naccess EVE IP and your apps directly, instead `eden sdn fwd` command must be used (run with no arguments to print help).\nFeel free to change the content in [./data/helloeve/](./data/helloeve) and redeploy the pod.\n\nAt any time, to get the status of what is running and where, including `\u003cEVE IP\u003e`, run:\n\n```console\neden status\n```\n\n#### Quickstart Local (PC in qemu)\n\n```console\neden config add default\neden setup\neden start\neden eve onboard\neden pod deploy docker://nginx -p 8028:80 --mount=src=./data/helloeve,dst=/usr/share/nginx/html\neden status\n\n# if SDN is disabled (sdn.disable=true)\ncurl http://\u003cEVE IP\u003e:8028\n# if SDN is enabled (sdn.disable=false)\neden sdn fwd eth0 8028 curl http://FWD_IP:FWD_PORT\n```\n\nWhen done be sure to clean up:\n\n```console\nmake clean\n# OR\neden stop \u0026\u0026 eden clean --current-context=false\n```\n\n#### Quickstart Hardware (Build an image for real x86)\n\n```console\neden config add default --devmodel general\neden config set default --key adam.eve-ip --value \u003cIP of Manager\u003e\neden setup\n```\n\nBurn the image that was displayed to a the proper storage for you device, e.g.\nSD card or USB drive. There are many utilities and tools to do so,\nfrom the venerable `dd` to [balena etcher](https://www.balena.io/etcher/).\n\nBoot your device from the storage medium.\n\nThen on eden:\n\n```console\neden start\neden eve onboard\neden pod deploy docker://nginx -p 8028:80 --mount=src=./data/helloeve,dst=/usr/share/nginx/html\neden status\ncurl http://\u003cEVE IP\u003e:8028\n```\n\nWhen done be sure to clean up:\n\n```console\nmake clean\n# OR\neden stop \u0026\u0026 eden clean --current-context=false\n```\n\n### Target Platforms\n\nEVE can run on most platforms. However, there are some considerations when\nrunning on certain platforms. See [docs/eve-platforms.md](./docs/eve-platforms.md).\n\n## Eden shell settings\n\nFor more ease of use of Eden, you can use the automatically generated setup files for your shell:\n\n* for BASH/ZSH -- `source ~/.eden/activate.sh`\n* for TCSH -- `source ~/.eden/activate.csh`\n\nThese settings add the Eden's binaries directory to the PATH environment variable and add the \"EDEN\\_\u003ccurrent\\_config\u003e\\_\" label to the command prompt.\n\nIn setup files defined some functions (BASH/ZSH) and aliases (TCSH) for work with configs:\n\n* eden+config \u003cconfig\\_name\u003e -- add new config for Eden\n* eden-config \u003cconfig\\_name\u003e -- remove config from Eden and switch to 'default'\n* eden_config \u003cconfig\\_name\u003e -- switch Eden to config and change prompt\n\nTo deactivate this settings call `eden_deactivate` function.\n\nYou may configure Bash/Zsh/Fish shell completions for Eden by command `eden utils completion`.\n\n## Eden Configurations\n\nEden's config is controlled via a yaml file, overriddable using command-line options.\nIn most cases, the defaults will work just fine for you. If you want to change\nthe configuration of any of the services, or use multiple stored setups, see\n[docs/config.md](./docs/config.md).\n\n## Remote access to eve\n\nTo get a shell on the EVE device, once the device is fully registered to its\ncontroller:\n\n```console\neden eve ssh\n```\n\nYou can run a single command remotely by passing it as argument:\n\n```console\neden eve ssh \"ls -la\"\n```\n\nIf you need access to the actual device console, run:\n\n```console\neden eve console\n```\n\n## Applications on EVE\n\nApplications are controlled on an EVE device with the `eden pod` commands.\nFor details, see [applications](./docs/applications.md).\n\n## Tests\n\nRunning tests is simple:\n\n```console\neden test \u003ctest folder\u003e\n```\n\nFor example -- to run the reboot test:\n\n```console\neden test tests/reboot/\n```\n\nOr to run the workflow tests:\n\n```console\nEDEN_TEST=small eden test tests/workflow -v debug\n```\n\nBecause most workflow tests already contain a setup phase you only need minimal preparation before running them - here is an example of running smoke test workflow (as done in `.github/actions/setup-environment/action.yml` and `.github/actions/run-eden-test/action.yml`):\n\n```console\n(optional) make clean\nmake build\nmake build-tests\neden config add default\neden setup\neden test tests/workflow/ -s smoke.tests.txt\n```\n\nHere it is important not to do the setup with `make run`, because it doesn't include a call to `eden+ports.sh` that sets up port forwarding for the tests.\n\nFor tests that accept parameters, simply pass them after the test path. For\nexample, to run Log/Metrics/Info test\nin debug mode with timeout of 600 seconds and requiring 3 messages of each type:\n\n```console\neden test tests/lim/ -v debug -a '-timewait 600 -number 3'\n```\n\nAs of this writing, you must _build_ the tests before running them:\n\n```console\nmake build-tests\n```\n\nFor more information about running tests, as well as creating your own,\nstart [here](tests/README.md).\n\n## Help\n\nYou can get more information about `make` actions by running `make help`.\n\nMore information can be found at the\n[wiki](https://wiki.lfedge.org/display/EVE/EDEN) or in the #eve-help channel in\n[slack](https://slack.lfedge.org/).\n","funding_links":[],"categories":["Edge"],"sub_categories":["Tutorial"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flf-edge%2Feden","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flf-edge%2Feden","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flf-edge%2Feden/lists"}