holos

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="./docs/holos-lockup-dark.svg">
  <img alt="holos" src="https://raw.githubusercontent.com/zeroecco/holos/HEAD/docs/holos-lockup-light.svg" width="340">
</picture>

Docker compose لـ KVM. عرّف حزم متعددة الأجهزة الافتراضية في ملف YAML واحد. بدون libvirt، بدون
XML، بدون لوحة تحكم موزعة.

الموقع والتوثيق: <https://zeroecco.github.io/holos/>

الوحدة الأساسية هي الجهاز الافتراضي (VM)، وليس الحاوية. كل نسخة من عبء العمل تحصل على
حدود نواة خاصة بها، وطبقة qcow2 علوية، وبذرة cloud-init، ووصول SSH مُولَّد.

## البدء السريع

> يتطلب Linux + `/dev/kvm`. إصدارات macOS تشغّل الأوامر غير المتصلة مثل
> `validate` و`import` و`images` و`pull`، لكن `up` و`run` يحتاجان إلى مضيف
> KVM.

جهاز افتراضي واحد قابل للتخلص منه، بدون ملف compose:

```bash
holos run alpine
holos exec <printed-project-name>
holos down <printed-project-name>
```

حزمة ذات خدمة واحدة يمكنك `curl` عليها. احفظها باسم `holos.yaml`:

```yaml
name: hello

services:
  web:
    image: ubuntu:noble
    ports:
      - "8080:80"
    cloud_init:
      packages:
        - nginx
      write_files:
        - path: /var/www/html/index.html
          content: "hello from holos\n"
      runcmd:
        - systemctl restart nginx
```

```bash
holos up
curl localhost:8080
holos down hello
```

هذا جهاز افتراضي حقيقي يُقلع من صورة سحابية، ويثبّت حزمة، ويكتب إعدادات،
ويُمرّر منفذ المضيف.

## التثبيت

الملفات التنفيذية الجاهزة مرفقة بكل
[إصدار على GitHub](https://github.com/zeroecco/holos/releases):

```bash
TAG=v0.6.3
ASSET=holos_${TAG#v}_Linux_x86_64.tar.gz
BASE=https://github.com/zeroecco/holos/releases/download/$TAG
curl -LO $BASE/$ASSET
curl -LO $BASE/checksums.txt
grep " $ASSET$" checksums.txt | sha256sum -c -
gh attestation verify $ASSET --repo zeroecco/holos
sudo tar -xz -C /usr/local/bin -f $ASSET holos
holos version
holos doctor
```

تتضمن صفحات الإصدارات مجاميع تحقق SHA-256 وشهادات GitHub للمصنوعات (artifact attestations) لإثبات
المصدر الموقّع. تحقق من كليهما قبل تثبيت الملفات التنفيذية على مضيفات الإنتاج.

أو ابنِ من المصدر:

```bash
go build -o bin/holos ./cmd/holos
go test ./...
bin/holos doctor
```

## واجهة سطر الأوامر (CLI)

```text
holos up [-f holos.yaml] [--locked] [--lockfile path] [--lock-timeout 5m|--no-wait]
                                     start all services
holos run [flags] <image> [-- cmd...] launch a one-off VM
holos down <project>                 stop and remove a project
holos ps [-f holos.yaml]             list running projects
holos start [-f holos.yaml] [svc]    start a stopped service or all services
holos stop [-f holos.yaml] [svc]     stop a service or all services
holos console <project> [<inst>]     attach serial console
holos exec <project> [<inst>] [-- cmd...]
                                     SSH into an instance
holos logs <project> [<svc|inst>]    show console logs
holos inspect [-f holos.yaml] [project|instance]
                                     inspect state as JSON
holos validate [-f holos.yaml]       validate compose file (--capacity/--network)
holos pull <image>                   pull a cloud image
holos verify <image>|--all           verify cached image checksums
holos images                         list available images
holos images lock -f holos.yaml [-o holos.images.lock]
                                     write project image lockfile
holos snapshots {create|list|rm|restore|export} ... manage root snapshots
holos volumes [-f holos.yaml] [--json]
                                     list named volumes
holos volumes rm <project> <volume>  remove a detached named volume
holos volumes export <project> <volume> <path>
                                     export a detached named volume
holos volumes snapshot <project> <volume> <snapshot>
                                     snapshot a detached named volume
holos volumes snapshots <project> <volume>
                                     list volume snapshots
holos volumes snapshot-rm <project> <volume> <snapshot>
                                     remove a volume snapshot
holos volumes snapshot-restore <project> <volume> <snapshot>
                                     restore a volume snapshot
holos volumes snapshot-export <project> <volume> <snapshot> <path>
                                     export a volume snapshot
holos volumes resize [--shrink] <project> <volume> <size>
                                     resize a detached named volume
holos devices [--gpu]                list PCI devices and IOMMU groups
holos completion <bash|zsh|fish>      print shell completion script
holos doctor [--json]                check host dependencies
holos install [-f holos.yaml] [--system] [--enable]
                                     install a systemd unit
holos uninstall [-f holos.yaml] [--system]
                                     remove the systemd unit
holos import [vm...] [--all] [--xml file] [--connect uri] [-o file]
                                     convert virsh VMs into holos.yaml
```

## التوثيق

- [الموقع](https://zeroecco.github.io/holos/): صفحة الهبوط والتوثيق المعروض.
- [دليل CLI](https://github.com/zeroecco/holos/blob/main/docs/cli.md): الأجهزة الافتراضية المؤقتة، و`exec`، وتثبيت systemd، واستيراد virsh،
  و`doctor`.
- [ملف Compose](https://github.com/zeroecco/holos/blob/main/docs/compose.md): الخدمات، والأحجام، وفحوصات الصحة،
  والشبكات، وتمرير PCI، وتزويد Dockerfile، والإعدادات الافتراضية.
- [مخطط JSON](https://github.com/zeroecco/holos/blob/main/docs/holos.schema.json): الإكمال والتحقق في المحرر لـ
  `holos.yaml`.
- [الأمثلة](https://github.com/zeroecco/holos/blob/main/examples/README.md): حزم قابلة للتشغيل وقوالب مع
  شروحات بأسلوب README.
- [الميزات المفقودة](https://github.com/zeroecco/holos/blob/main/docs/missing-features.md): الفجوات ذات الأولوية التي تناسب
  هدف holos في compose KVM أحادي المضيف.
- [التطوير](https://github.com/zeroecco/holos/blob/main/docs/development.md): البناء، والاختبار، ومتطلبات المضيف، وعملية
  الإصدار.
- [سياسة الأمان](https://github.com/zeroecco/holos/blob/main/SECURITY.md): الإصدارات المدعومة والإبلاغ الخاص.
- [نموذج التهديد / التقوية](https://github.com/zeroecco/holos/blob/main/docs/threat-model.md):
  التحقق من الصور، وأذونات الحالة، والأقفال، والإرشادات التشغيلية.
- [المساهمة](https://github.com/zeroecco/holos/blob/main/CONTRIBUTING.md): البناء، والاختبار، والأسلوب، واتفاقيات طلبات السحب (PR).

## الأمثلة

ابدأ بمثال nginx الصغير:

```bash
holos up -f examples/alpine-nginx/holos.yaml
curl localhost:8080
holos down alpine-nginx
```

يتضمن دليل الأمثلة أيضًا تزويد Dockerfile، وتمرير GPU،
وحزمة متعددة الخدمات تُظهر `depends_on`، والإعدادات المُولَّدة،
والنسخ المتماثلة (replicas).

## متطلبات المضيف

- Linux مع `/dev/kvm`
- `qemu-system-x86_64`
- `qemu-img`
- أحد الأدوات `cloud-localds` أو `genisoimage` أو `mkisofs` أو `xorriso`
- برنامج OVMF / edk2-ovmf الثابت لـ UEFI أو تمرير PCI
- `ssh` لـ `holos exec` وفحوصات الصحة

شغّل `holos doctor` للتحقق من المضيف.

## استكشاف الأخطاء وإصلاحها

### إعادة تعيين SSH عند الإقلاع الأول

`kex_exchange_identification: read: Connection reset by peer` عادةً يعني
أن cloud-init لا يزال يعيد توليد مفاتيح المضيف ويعيد تشغيل sshd. ينتظر `holos exec`
حتى 60 ثانية افتراضيًا، لكن عمليات الإقلاع الأولى البطيئة جدًا قد تحتاج إلى محاولة أخرى أو
`holos exec -w 5m <project>`.

### وحدة التحكم تُظهر `Login incorrect`

قد تحاول وحدة التحكم التسلسلية تسجيل الدخول التلقائي قبل أن ينشئ cloud-init المستخدم.
انتظر ظهور `cloud-init ... finished` في سجل وحدة التحكم، ثم استخدم `holos exec`.
الصور السحابية عمومًا لا تأتي بكلمة مرور لوحدة التحكم، وholos لا
يضيف واحدة.

### فشل `up` على macOS

KVM ميزة في نواة Linux. ملفات macOS التنفيذية مفيدة للتأليف والأوامر
غير المتصلة، لكن `holos up` و`holos run` يجب أن يُنفَّذا على مضيف
Linux KVM.

## أهداف غير مقصودة

holos ليس Kubernetes. إنه لا يحاول حل التجميع متعدد المضيفين، أو الترحيل الحي،
أو شبكات الخدمات (service meshes)، أو الشبكات العلوية (overlay networks)، أو المجدولات، أو CRDs، أو نصاب
لوحة التحكم.

الهدف هو جعل KVM عمليًا لحزم أحادية المضيف دون استيراد
الشكل التشغيلي لـ Kubernetes.

## الترخيص

مرخّص بموجب [رخصة Apache، الإصدار 2.0](https://github.com/zeroecco/holos/blob/main/LICENSE). راجع
[`NOTICE`](https://github.com/zeroecco/holos/blob/main/NOTICE) لحقوق النسب.