doc: added developement guide

Author: simonwalz

README.md

@@ -67,7 +67,9 @@ CuOS is designed for **mass deployment**:
 
 ## 📦 Getting Started
 
-Coming soon: Installation instructions, example Dockerfiles, and deployment guides.
+For system administrators looking to deploy services using CuOS, please visit [cuos-iac](https://github.com/cuos-dev/cuos-iac/), our Infrastructure as Code repository. It provides tools and templates for deploying and managing services on CuOS.
+
+For developers looking to create custom CuOS-based systems, check out our [CuOS Development Guide](docs/development-guide.md).
 
 ---
 

docs/common/btrfs-usage.md

@@ -0,0 +1,75 @@
+# Advanced BTRFS Usage in CuOS
+
+This document explains how CuOS uses BTRFS subvolumes for system management and updates.
+
+## Overview
+
+CuOS uses BTRFS subvolumes instead of traditional partitions for its A/B update system. This approach provides:
+- Efficient storage usage through copy-on-write (CoW)
+- Atomic system updates
+- Fast rollbacks
+- Data persistence across updates
+
+## System Layout
+
+### Disk Structure
+
+```
+/dev/sdX               # Physical disk
+├── partition1         # BIOS boot partition
+├── partition2: boot   # EFI System Partition (ESP)
+└── partition3: system # BTRFS root partition
+    ├── @os            # OS subvolume
+    │   └── docker     # Docker dir only used while updating
+    │       ├── btrfs  # 
+    │       │   ├──    # image layers as btrfs subvolumes
+    │       │   └──    # use use for the OS.
+    │       └── ...
+    ├── @data          # Persistent data
+    │   ├── docker     # System docker dir
+    │   ├── log        # System logs: /var/log
+    │   └── ...
+    └── @swap          # For the swap file
+```
+
+GRUB is setup as boot loader for both UEFI and non-UEFI setups.
+
+For partition switch we write two grub files and configure the default.
+
+### Raspberry Pi
+
+```
+/dev/sdX               # Physical disk
+├── partition1: boot   # /boot/firmware partition  (vfat)
+└── partition2: system # BTRFS root partition (as above)
+```
+
+Boot partition has the raspbian default structure. [RaspberryPi Documentation](https://www.raspberrypi.com/documentation/computers/config_txt.html#what-is-config-txt)
+
+For partition switch we write the subvol in cmdline.txt.
+
+### Mount Points
+```
+/          → /dev/sdX3/@os/docker/btrfs/...  # Current system root
+/data      → /dev/sdX3/@data           # Persistent data
+/swap      → /dev/sdX3/@swap           # For the swap file
+```
+
+## Update Process
+
+1. **Preparation**
+   ```
+   system_A (active)
+   system_B (ready for update)
+   ```
+
+2. **During Update**
+   - Docker pulls new image
+   - Creates new root filesystem in inactive subvolume
+   - Updates boot configuration
+
+3. **After Update**
+   ```
+   system_A (old, fallback)
+   system_B (new, active)
+   ```

docs/common/building-images.md

@@ -0,0 +1,100 @@
+# Building CuOS Image Files
+
+This guide explains how to build CuOS system images for different platforms (from Docker images).
+
+"Image" means, that it copies the OS directly on the target. To install it using a secondary media (e.g., USB stich or virtual cdrom device) see [Installer](./installation.md).
+
+## Prerequisites
+
+   * A `system.json` configuration file (see [under the variants](../development-guide.md))
+   * A Docker environment to build the installation media ON the same machine architecture as the target system. Note: Building ARM64 images on x86_64 hosts (or vice versa) is not supported
+  * Access to a container registry
+ 
+## Image Factory
+
+The image-factory creates bootable images with the CuOS partition scheme.
+
+### Configuration
+
+Create a `system.json` file with your image configuration:
+
+```json
+{
+  "os_image": "your-registry/your-os-image",
+  "os_image_version": "1.0.0",
+  "os_image_digest": "",
+  "updater_image": "ghcr.io/cuos-dev/cuos-updater",
+  "updater_image_version": "latest",
+  "updater_image_digest": ""
+}
+```
+
+### Creating Images
+
+```bash
+./image-factory/start.sh path/to/system.json
+```
+
+The created image will be available at `./output/image.img`.
+
+### Image Structure
+
+The created image includes:
+1. BIOS boot partition
+2. EFI System Partition (ESP)
+3. Root filesystem partition
+   - BTRFS filesystem
+   - Automatic snapshot management
+
+For more details, see [BTRFS Usage Guide](./btrfs-usage.md).
+
+
+## Platform-Specific Images
+
+### x86_64 Systems
+Standard image creation process as described above.
+
+### Raspberry Pi (ARM64)
+Use the Raspberry Pi specific image configuration:
+```json
+{
+  "rpi-arm64_image": "your-registry/your-rpi-image",
+  "rpi-arm64_image_version": "1.0.0",
+  "rpi-arm64_image_digest": ""
+}
+```
+
+## Image Formats and Conversion
+
+Convert between formats using qemu-img:
+```bash
+# Convert to QCOW2
+qemu-img convert -f raw -O qcow2 image.img image.qcow2
+
+# Convert to VHD
+qemu-img convert -f raw -O vpc image.img image.vhd
+```
+
+## Using the Image on Physical disks:
+
+1. Write the image to a physical device (e.g., USB drive):
+   ```bash
+   dd if=image.img of=/dev/sdX bs=1M status=progress
+   ```
+2. Boot from the device and follow on-screen instructions.
+
+Note: The first boot may take longer as the system resizes partitions and sets up the filesystem.
+
+## Using the image on Proxmox VE
+
+1. Upload the `image.img` to your Proxmox server.
+2. Convert the raw image to a Proxmox-compatible format (e.g., QCOW2):
+   ```bash
+   qemu-img convert -f raw -O qcow2 image.img image.qcow2
+   ```
+3. Create a new VM in Proxmox without a disk.
+4. Upload the converted image to the VM's disk storage:
+   ```bash
+   qm importdisk <VMID> image.qcow2 <STORAGE>
+   ```
+5. Attach the disk to the VM and configure boot options.