~~tag>oowow develop online-installation images xze ~~

====== OOWOW Online-installation images ======

===== Basic Requirements =====

WIP:

  * System must workable for any board revision
  * Image writing size small as possible, no need to rewrite the whole eMMC content, same as writing unused empty spaces
  * Image writing size not be bigger what's possible smallest storage board configurations
  * Any private data not allowed
  * Any malware spyware etc ... will be banned
  * Clean trash, logs, cache, etc ... before packing installation image
  * Use optimal compression via [[#xze]]
  * Use meta descriptions for images via [[#xze]]
  * Use [[#basic-khadas-file-name-format|Basic Khadas file-name format]] for installation images
  * WIP: ... 

==== Image Size ====

Try to make the installation image size small as possible

<WRAP important >
The simple dump from EMMC is the wrong way. Yes we can do it but, this image will have negative parts like:
  * some garbage in unused space
  * same fill EMMC size which will be written as is
  * ...

It's possible to improve by [[#dump-optimization]], but don't have any warranty to get quality results 

</WRAP>

==== Partitions ====

=== Fenix Builds ===
<WRAP important >
for Fenix builds need to use normal partitions (like GPT or DOS ) please don’t use Amlogic partitions variant (just if its really necessary)
</WRAP>

```
...
Choose install type:
2. SD-USB - Image For Writing to SD/USB Storage
...
Compress image:
Yes
```
<WRAP tip >
Compress image option, automatically build image suitable for OOWOW 
</WRAP>


WIP:


===== Dump optimization =====

  * Prepare all content on eMMC (clean cached, temp, logs, files manually by hand)
  * Boot into OOWOW
  * Before make dump from eMMC need make some optimization via __ OOWOW => shell __ ''RESIZE=1 mmc_optimize''
  * Make an eMMC dump to SD/USB it will be automatically decreased as possible
  * Repack it by [[#xze]], if need to use it for online installation 

<WRAP important >
Be sure your system must resize root-fs back to maximal size automatically at 1st boot, for example ''resize2fs /dev/rootfs'' 
</WRAP>


===== Basic Khadas file-name format =====

WIP: ...
```
SYNTAX:  boardname-system[-info]+.img[.xz|gz|zst]
```

All in lowercase only, use '-' as splitter, no spaces, no Unicode only basic Latin ... chars, file-name size less 80 symbols.  

Examples: https://dl.khadas.com/.images/vim4/

===== XZE =====

We recommend using [[https://github.com/khadas/krescue/blob/master/tools/xze|xze]] features for image developers, to provide better service for users like as:

  * Provide additional meta information about images
  * Its fully compatible with the common xz format, and same possible to use anywhere 
  * Fast-checking image integrity before writing it
  * Make a warranty it will be suitable for the current board installation
  * Fast optimal compression for fastest decompression on SBC
  * Image signup
  * etc...

==== XZE usage examples ====

The packing process is very simple just need to add some additional meta information ...

```sh pack raw image 
xze "vim1s-ha-supervised-debian-11-minimal-linux-5.4-fenix-1.5.1-230623.img" \
 --meta \
 label="Home Assistant" \
 builder="Repack" \
 date="$(LANG=C TZ= date)" \
 match=BOARD=VIM1S \
 link=https://www.home-assistant.io/ \
 duration=180 \
 desc="Home Assistant / debian 11 / linux 5.4 / fenix 1.5.1 / 230623"
```

Also, we can get full information about xze-packed image

```sh check image meta info

./xze YOUR-IMAGE.img.xz 

```

Just one more example 

```shell 
~$ ./xze edge2-openfyde-r114.img.xz 
Strms  Blocks   Compressed Uncompressed  Ratio  Check   Filename
    2     110  1,456.4 MiB  9,786.1 MiB  0.149  CRC64   edge2-openfyde-r114.img.xz
[i] blocks: 110 // 1,456.4*MiB // 9,786.1*MiB
##META_FILE##
FILE: edge2-openfyde-r114.img.xz
UNPACKED_SIZE: 10261445120
PACKED_SIZE: 1527136256
FILE_SIZE: 1527140352
##META-FILE##

##KRESCUE_META##
type:xz
label: openFyde
date: Sat Jul 15 04:18:38 UTC 2023
match: BOARD=Edge2
builder: openFyde
link: https://openfyde.io/
desc: openFyde for Khadas Edge2
duration: 60
image: edge2-openfyde-r114.img
##KRESCUE-META##
##KRESCUE##END
```

Last one is web usage

```shell get meta info 
~$ IMAGE_LINK=https://github.com/openFyde/overlay-edge2-openfyde/releases/download/r114/edge2-openfyde-r114.img.xz

~$ curl -s -jkLf -r-4096 "$IMAGE_LINK" | xz -dc 

##META_FILE##
FILE: edge2-openfyde-r114.img.xz
UNPACKED_SIZE: 10261445120
PACKED_SIZE: 1527136256
FILE_SIZE: 1527140352
##META-FILE##

##KRESCUE_META##
type:xz
label: openFyde
date: Sat Jul 15 04:18:38 UTC 2023
match: BOARD=Edge2
builder: openFyde
link: https://dl.khadas.com/
desc: openFyde for Khadas Edge2
duration: 60
image: edge2-openfyde-r114.img
##KRESCUE-META##
##KRESCUE##END

```



===== Armbian external mirrors usage =====

[[armbian-images]]


```shell link setup
@web:/storage/.images/edge2$ grep "" edge2-armbian*
edge2-armbian-jammy-legacy-cli.img.xz:https://redirect.armbian.com/khadas-edge2/Jammy_legacy.oowow
edge2-armbian-jammy-legacy-desktop-xfce.img.xz:https://redirect.armbian.com/khadas-edge2/Jammy_legacy_xfce.oowow
edge2-armbian-jammy-legacy-minimal.img.xz:https://redirect.armbian.com/khadas-edge2/Jammy_legacy_minimal.oowow

@web:/storage/.images/edge2$ chmod 0667 edge2-armbian*


```

===== See also =====

  * [[software/oowow/dev/online-external-images-usage/]]