empeira 0.1.0.pre.alpha.1

data/README.md

@@ -0,0 +1,150 @@
+# empeira
+
+**Ephemeral Manifest Playground for Exploring Infrastructure, Roles & Automation**
+
+[![Build & Tests](https://img.shields.io/github/actions/workflow/status/c8m6/empeira/ci.yml?branch=main&label=Build%20%26%20Tests)](https://github.com/c8m6/empeira/actions/workflows/ci.yml)
+[![OpenVox E2E](https://img.shields.io/github/actions/workflow/status/c8m6/empeira/openvox.yml?branch=main&label=OpenVox%20E2E)](https://github.com/c8m6/empeira/actions/workflows/openvox.yml)
+[![Release](https://img.shields.io/github/v/release/c8m6/empeira?include_prereleases&sort=date&label=Release)](https://github.com/c8m6/empeira/releases)
+[![Ruby: 3.4 / 4.0](https://img.shields.io/badge/Ruby-3.4%20%7C%204.0-CC342D)](docs/installation.md)
+[![License: AGPL-3.0-only](https://img.shields.io/badge/License-AGPL--3.0--only-blue)](LICENSE)
+
+**ἐμπειρία (empeiría)** — experience gained through practice. The name reflects
+learning about infrastructure by experimenting, testing and seeing what happens.
+
+empeira gives your local Puppet control repository a disposable, isolated lab with
+real agents, catalogs, Hiera and PuppetDB. Test infrastructure changes against an
+OpenVox environment without connecting to production infrastructure.
+
+![Local manifests, modules and Hiera data feed an isolated OpenVox Server, OpenVoxDB and PostgreSQL lab with disposable container and VM nodes; Puppet runs return catalog and application feedback without a Git push or deployment.](docs/images/empeira-overview.png)
+
+## Edit. Save. Test.
+
+**No Git push. No deployment.**
+
+Edit your manifests, roles, modules or Hiera data locally. empeira works directly
+with your development files, so there is no need to commit, push or deploy changes
+before testing them. Run `empeira node puppet host1` on a disposable node to compile
+a fresh catalog, apply it and see the results.
+
+Saving a file does not start Puppet. Managed servers disable environment caching,
+so the next catalog request reloads live code without a content scan or cache API call. Puppetfile changes
+may require `empeira update modules`; `up` does not synchronize modules. See
+[environment caching](docs/nodes.md#environment-cache-and-live-code) and
+[Puppetfile modules](docs/hiera-and-eyaml.md#puppetfile-modules).
+
+## Features
+
+OpenVox Server, OpenVoxDB, PostgreSQL and OpenVox Agent are the defaults. Server and
+database OCI images are independently replaceable; agent packages, versions and
+signed repositories or verified package artifacts are selected separately.
+
+- Docker or rootless Podman container nodes; accelerated QEMU VM nodes.
+- A workspace CA, certificate enrollment, live control code and Hiera/EYAML mounts.
+- Shared DNS and container/VM networking, isolated by default.
+- Allowlisted HTTP/HTTPS proxy access and explicit TCP egress rules.
+- Node stop/start/destroy, direct shell access and real SSH.
+- An internal Chromium desktop and small additional infrastructure services.
+- Explicit Puppetfile module and image updates.
+
+Hosts: Linux, macOS and Windows through WSL2/Linux. Ruby 3.4 is the minimum;
+Ruby 3.4 and 4.0 are supported; CI runs deterministic tests with both versions.
+Podman with Netavark is the default; Docker requires a Linux engine 28+ with
+isolated bridge support. VMs require usable KVM or HVF. Platform setup and
+validation limits are in [installation](docs/installation.md).
+
+## Installation
+
+Until a release is available, install from source with Ruby, Bundler and Git:
+
+```bash
+git clone https://github.com/c8m6/empeira.git
+cd empeira
+bundle install
+export EMPEIRA_SOURCE="$PWD"
+empeira() { BUNDLE_GEMFILE="$EMPEIRA_SOURCE/Gemfile" bundle exec ruby "$EMPEIRA_SOURCE/bin/empeira" "$@"; }
+empeira --version
+```
+
+The function lets you invoke the source CLI from your control repository. See
+[installation](docs/installation.md) for runtime prerequisites, release-gem
+installation and Bash completion.
+
+## Quickstart
+
+Use a dedicated Git control repository and an empty configuration marker:
+
+```bash
+cd ..
+mkdir control-repo
+cd control-repo
+git init
+touch .empeira.yaml
+mkdir -p manifests
+printf "file { '/tmp/empeira-example': content => 'managed by Puppet\n' }\n" > manifests/site.pp
+
+empeira config validate
+empeira up
+empeira node run host1
+empeira node puppet host1
+empeira node exec host1 -- id
+empeira node shell host1
+```
+
+`node run` creates an Ubuntu 24.04 container, installs the default OpenVox Agent,
+enrolls its certificate and applies the catalog. Inside the shell, inspect
+`/tmp/empeira-example`; `exit` returns to the host. Select Docker with
+`--container-engine docker` when Podman is not installed. Optional workstation
+preferences can set that runtime in `~/.empeira.yaml`.
+
+After editing your control code, run `empeira node puppet host1` again. If the
+repository uses a Puppetfile, run `empeira update modules` before `up`.
+
+```console
+empeira status
+empeira node list
+empeira browser
+empeira node destroy host1
+empeira destroy
+```
+
+`destroy` permanently removes the workspace's owned nodes, CA and database data.
+The control repository, module directory and shared image caches are preserved.
+Destroy works independently of release requirements and guest management versions.
+Use `destroy --project-path <former-absolute-git-root>` when the control repository no longer exists.
+`node shell` opens a root terminal; `node console` keeps the VM serial login separate.
+See [diagnostic access and recovery](docs/nodes.md#root-diagnostic-commands-and-interactive-shell).
+
+## Documentation
+
+- [Configuration](docs/configuration.md): defaults, software selection and overrides.
+- [Standalone addons](docs/addons.md): Git-based helper programs, manifests and environment API.
+- [Nodes](docs/nodes.md): lifecycle, shell/SSH, VM images and bootstrap.
+- [Hiera and EYAML](docs/hiera-and-eyaml.md): local data mounts and Puppetfile modules.
+- [Networking](docs/networking.md) and [proxy policy](docs/proxy.md).
+- [Troubleshooting](docs/troubleshooting.md).
+- [Architecture](docs/architecture.md) and [development](docs/development.md).
+
+## Alpha status
+
+empeira is being prepared for its first public alpha. Interfaces and inventory
+schemas may change; unsupported inventory fails closed without automatic migration.
+Use synthetic control code and disposable credentials. The shared network is a
+cooperative lab, and its internal PuppetDB API is unauthenticated.
+
+Container process mode does not provide a full booted OS. Systemd requires Podman
+and cgroup v2. VM and shared-network support require actual host capabilities;
+macOS/HVF and arm64 runtime validation are manual gates. Native Windows, automatic
+self-update, aggregate `update all` and standalone platform binaries are unavailable.
+The initial release distribution is a Ruby gem.
+
+## Community and license
+
+[Contributions](CONTRIBUTING.md), [issues](https://github.com/c8m6/empeira/issues)
+and [pull requests](https://github.com/c8m6/empeira/pulls) are welcome. Follow the
+[code of conduct](CODE_OF_CONDUCT.md) and report vulnerabilities through the
+[security policy](SECURITY.md).
+
+Project-owned code and documentation are licensed under
+[AGPL-3.0-only](LICENSE). Third-party packages and images retain their own licenses
+and notices and are obtained from upstream; empeira does not bundle them or
+redistribute proprietary Puppet Enterprise software.

data/bin/empeira

@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/empeira'
+require_relative '../lib/empeira/cli/main'
+
+begin
+  Empeira::CLI::Main.start(ARGV)
+rescue Empeira::Addons::Error => e
+  $stderr.write "#{e.message}\n"
+  exit e.exit_status
+rescue Empeira::Error => e
+  # CLI errors must remain visible even when Ruby warnings are disabled.
+  $stderr.write "Error: #{e.message}\n"
+  exit 1
+rescue Interrupt
+  exit 130
+end

data/config/defaults.yaml

@@ -0,0 +1,229 @@
+version: 1
+
+# Standalone Git addons; no addon code runs during synchronization or completion.
+addons: {}
+mocks:
+  commands: {}
+requirements:
+  empeira: null
+runtime:
+  container_engine: podman
+modules:
+  path: modules
+server:
+  mounts: []
+  runtime:
+    startup:
+      entrypoint: /container-entrypoint.sh
+      arguments: [foreground]
+      eyaml_keys: direct
+    paths:
+      puppetdb_config: /etc/puppetlabs/puppet/puppetdb.conf
+    environment_keys:
+      certname: CERTNAME
+      dns_alt_names: DNS_ALT_NAMES
+      ca_hostname: CA_HOSTNAME
+      autosign: AUTOSIGN
+      server_hostname: OPENVOXSERVER_HOSTNAME
+      environment_timeout: OPENVOXSERVER_ENVIRONMENT_TIMEOUT
+      java_args: OPENVOXSERVER_JAVA_ARGS
+      max_active_instances: OPENVOXSERVER_MAX_ACTIVE_INSTANCES
+      puppetdb_enabled: USE_OPENVOXDB
+      storeconfigs: OPENVOX_STORECONFIGS
+      reports: OPENVOX_REPORTS
+      puppetdb_server_urls: OPENVOXDB_SERVER_URLS
+  environment: production
+  memory: 1536
+  cpus: 2
+  timeout: 240
+puppetdb:
+  enabled: true
+  memory: 768
+  runtime:
+    entrypoint: /usr/bin/java
+    user: '0'
+    java_arguments: [-Xms128m, -Xmx256m, -Dlogappender=STDOUT]
+    main_arguments: [clojure.main, -m, puppetlabs.puppetdb.cli.services]
+    paths:
+      jar: /opt/puppetlabs/server/apps/puppetdb/puppetdb.jar
+      config: /etc/puppetlabs/puppetdb/conf.d
+      bootstrap_config: /etc/puppetlabs/puppetdb/bootstrap.cfg
+      data: /opt/puppetlabs/server/data/puppetdb
+network:
+  egress: []
+  redirects: []
+proxy:
+  enabled: false
+  global: []
+  rules: []
+vm:
+  disk: 30
+  interfaces: []
+  console:
+    root_password: empeira
+dns:
+  upstream:
+    mode: host
+    servers: []
+  additional_resolver: null
+  rewrites: []
+node_defaults:
+  os: ubuntu
+  version: "24.04"
+  init: process
+  memory: 1024
+  cpus: 2
+hiera:
+  mounts: []
+eyaml:
+  enabled: false
+  private_key: null
+  public_key: null
+images:
+  registry: null
+  network_adapter_builder:
+    repository: library/golang
+    tag: 1.27.1-alpine3.24
+  server:
+    repository: ghcr.io/openvoxproject/openvoxserver
+    tag: "8.16.0"
+    digest: "sha256:17902772813778ed8dabb08b83eec2ddce09e799a993e2ec01a46b5cb7994bd8"
+  puppetdb:
+    repository: ghcr.io/openvoxproject/openvoxdb
+    tag: "8.15.0"
+    digest: "sha256:a5e1c400a23392ac772abf27f0312032052c0a296628a7785eb3c3904ef44b5d"
+  postgres:
+    repository: library/postgres
+    tag: "16.13-alpine"
+    digest: "sha256:4e6e670bb069649261c9c18031f0aded7bb249a5b6664ddec29c013a89310d50"
+  dns:
+    repository: coredns/coredns
+    tag: "1.14.7"
+  r10k:
+    build: modules/Containerfile
+  relay:
+    build: relay/Containerfile
+  proxy:
+    build: proxy/Containerfile
+  direct_egress:
+    build: gateway/Containerfile
+  nodes:
+    ubuntu:
+      "22.04":
+        repository: library/ubuntu
+        tag: "22.04"
+        build: nodes/debian/Containerfile
+        architectures: [amd64, arm64]
+      "24.04":
+        repository: library/ubuntu
+        tag: "24.04"
+        build: nodes/debian/Containerfile
+        architectures: [amd64, arm64]
+    rocky:
+      "8":
+        repository: rockylinux/rockylinux
+        tag: "8"
+        build: nodes/rpm/Containerfile
+        architectures: [amd64, arm64]
+      "9":
+        repository: rockylinux/rockylinux
+        tag: "9"
+        build: nodes/rpm/Containerfile
+        architectures: [amd64, arm64]
+    almalinux:
+      "8":
+        repository: library/almalinux
+        tag: "8"
+        build: nodes/rpm/Containerfile
+        architectures: [amd64, arm64]
+      "9":
+        repository: library/almalinux
+        tag: "9"
+        build: nodes/rpm/Containerfile
+        architectures: [amd64, arm64]
+    oraclelinux:
+      "8":
+        repository: library/oraclelinux
+        tag: "8"
+        build: nodes/rpm/Containerfile
+        architectures: [amd64, arm64]
+agent:
+  cache:
+    enabled: true
+  package: openvox-agent
+  version: "8.29.0"
+  install:
+    method: repository
+    repositories:
+      ubuntu22.04:
+        url: "https://apt.voxpupuli.org/openvox8-release-ubuntu22.04.deb"
+        destinations: [apt.voxpupuli.org]
+        sha256: "fb23fa5bcbea3608384ae40cf9a7f705485353c3d81c5dc69f6a4d6e2c94b389"
+        suffix: "-1+ubuntu22.04"
+      ubuntu24.04:
+        url: "https://apt.voxpupuli.org/openvox8-release-ubuntu24.04.deb"
+        destinations: [apt.voxpupuli.org]
+        sha256: "40b8052bcece23ed707e609504dd14b178dc662652455f2d30e9c8e614955a94"
+        suffix: "-1+ubuntu24.04"
+      el8:
+        url: "https://yum.voxpupuli.org/openvox8-release-el-8.noarch.rpm"
+        destinations: [yum.voxpupuli.org]
+        sha256: "21ae739f60bdf9f3710ee3f894bf750140b85b3804110641a88561d2d2fdeff3"
+        suffix: "-1.el8"
+      el9:
+        url: "https://yum.voxpupuli.org/openvox8-release-el-9.noarch.rpm"
+        destinations: [yum.voxpupuli.org]
+        sha256: "ad1a18ce2634cb3a7a5bf3bc5cc3b0d0dbb8cb4411872f2f326d948004a1772b"
+        suffix: "-1.el9"
+    apt: {}
+    dnf: {}
+    packages: {}
+bootstrap:
+  enabled: false
+  scripts: []
+  packages:
+    install:
+      default: []
+      debian: []
+      redhat: []
+    remove:
+      default: []
+      debian: []
+      redhat: []
+  guests:
+    ubuntu:
+      "22.04":
+        agent_preinstalled: false
+        destinations: [archive.ubuntu.com, security.ubuntu.com, ports.ubuntu.com]
+      "24.04":
+        agent_preinstalled: false
+        destinations: [archive.ubuntu.com, security.ubuntu.com, ports.ubuntu.com]
+    rocky:
+      "8":
+        agent_preinstalled: false
+        destinations: [dl.rockylinux.org]
+        baseurl: "https://dl.rockylinux.org/pub/rocky/8"
+      "9":
+        agent_preinstalled: false
+        destinations: [dl.rockylinux.org]
+        baseurl: "https://dl.rockylinux.org/pub/rocky/9"
+    almalinux:
+      "8":
+        agent_preinstalled: false
+        destinations: [repo.almalinux.org]
+        baseurl: "https://repo.almalinux.org/almalinux/8"
+      "9":
+        agent_preinstalled: false
+        destinations: [repo.almalinux.org]
+        baseurl: "https://repo.almalinux.org/almalinux/9"
+    oraclelinux:
+      "8":
+        agent_preinstalled: false
+        destinations: [yum.oracle.com]
+browser:
+  start_url: "about:blank"
+  image:
+    repository: linuxserver/chromium
+    tag: "latest"
+containers:
+  additional: []