Merge pull request #3 from project-ocre/updating_container_format

updated the ocre container format

Author: Knox Lively

docs/architecture/containers/components/binary_objects/index.md

@@ -0,0 +1,58 @@
+---
+layout: default
+title: Image Components 
+parent: Ocre Containers 
+nav_order: 1 
+---
+
+# Image Components
+
+An Ocre container consists of the following **three** components: 
+
+| **Component** | **Description** |
+|-----------|-------------|
+| [`oci-layout`](#oci-layout) | OCI Layout file in JSON format. Specifies the version of the `imageLayoutVersion` in use. Ocre containers must set this value to `1.0.0` |
+| [`index.json`](#indexjson) | Image index file in JSON format. Serves as the entry point for the container image. Ocre containers will have one manifest entry with the mediaType of `application/vnd.oci.image.manifest.v1+json` which points to the Ocre artifact. |
+| [`blobs/`](#blobs) | Directory containing content-addressable blobs. Blobs are stored as files with the naming convention of `<alg>/<encoded>` which much match the digest format `<alg>:<encoded>`. Ocre containers support the SHA-256 algorithm *only*. |
+
+### oci-layout
+
+The `oci-layout` file identifies this as an Open Container Image Layout. Written in [UTF-8](https://www.w3schools.com/charsets/ref_html_utf8.asp) encoded JSON, it contains a single field `imageLayoutVersion` which must be set to `1.0.0` for Ocre containers. This file follows the `application/vnd.oci.layout.header.v1+json` media type specification as defined [here](https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/media-types.md).
+
+An **example** of this file is as follows:
+```json
+{
+    "imageLayoutVersion": "1.0.0"
+}
+```
+
+### index.json
+
+The `index.json` file serves as the entry point for the container image. Written in [UTF-8](https://www.w3schools.com/charsets/ref_html_utf8.asp) encoded JSON, it contains a single manifest entry pointing to the Ocre artifact, using the `mediaType` of `application/vnd.oci.image.manifest.v1+json`. This file follows the [OCI Image Index Specification](https://github.com/opencontainers/image-spec/blob/v1.1.0-rc2/image-layout.md#indexjson-file).
+
+An **example** of this file is as follows:
+
+```json
+{
+  "schemaVersion": 2,
+  "mediaType": "application/vnd.oci.image.index.v1+json",
+  "manifests": [
+    {
+      "mediaType": "application/vnd.oci.image.manifest.v1+json",
+      "digest": "sha256:b11ba766595f3bf6b1db36019cb09decc88aca35ff44dc5ae70bd88d4f188be4",
+      "size": 445
+    }
+  ]
+}
+```
+
+This illustrates an index that provides a single reference the Ocre container image manifest.
+
+### blobs/
+
+The `blobs` directory contains all content-addressable components of the Ocre container. Files are stored using the format `<alg>/<encoded>`, matching their digest format `<alg>:<encoded>`. Currently, Ocre containers only support the SHA-256 algorithm for these digests.
+
+---
+
+## Learn More
+Learn how these components are organized by reading about the [Image Manifest](../image_manifest), which defines the complete structure of an Ocre container.

docs/architecture/containers/components/container_configuration/index.md

@@ -0,0 +1,67 @@
+---
+layout: default
+title: Image Configuration 
+parent: Ocre Containers
+nav_order: 3
+---
+
+# Image Configuration
+
+The container configuration (`application/vnd.wasm.config.v0+json`) defines how the container should be run. It is a collection of metadata that controls the container's runtime behavior, including environment variables, execution parameters, hardware permissions, and entry points.
+
+For Ocre containers, this configuration is specifically tailored to WebAssembly modules running in embedded environments, ensuring proper initialization and execution within resource constraints.
+
+---
+
+## Configuration Structure
+
+The configuration file follows the [OCI Image Manifest](https://github.com/opencontainers/image-spec/blob/main/manifest.md)  specification with modifications for Wasm and embedded environments. See the example and a detailed description of its elements below. 
+
+### Example
+
+```json
+{
+  "architecture": "wasm",
+  "os": "wasip1",
+  "layerDigests": [
+    "sha256:71cb138990af165c4baf0c43361e5c055ed60a5d2632ee547597be56dcfa07e2"
+  ],
+  "module": {
+    "entryPoint": "on_init"
+  }
+}
+```
+
+## Configuration Elements
+
+Elements within the **configuration** are defined as follows:
+
+| Element | Type | Required | Description |
+|---------|------|----------|-------------|
+| `architecture` | string | Yes | CPU architecture of the binaries in this image; this value MUST be set to `wasm` |
+| `os` | string | Yes | Operating system which this image is built to run on; this MUST be `wasip1` or `wasip2` according to the Wasm target type |
+| `layerDigests` | array | Yes | Digests of all of the layers this configuration targets; digests must be in the same order as in the image manifest file |
+| `module` | module object | Yes | Specifies the parameters used for execution; `entryPoint` defines the WASM function to call on container start |
+
+---
+
+## Future Enhancements
+
+Ocre will extend its configuration format to better align with OCI standards and support critical runtime elements through the `config` entry. This enhancement will enable control over environment variables, permissions, and additional runtime parameters that are essential for container operation. 
+
+Here's an **example** of how these configurations will be structured:
+
+```json
+{
+  "config": {
+    "Env": [
+      "name1=val1",
+      "name2=val2"
+    ],
+    "Permissions": [
+      "perm1",
+      "perm2"
+    ]
+  }
+}
+```

docs/architecture/containers/components/index.md

@@ -0,0 +1,23 @@
+---
+layout: default
+title: Image Format 
+parent: Ocre Containers 
+nav_order: 0 
+---
+
+# Image Format
+
+Ocre container images follow the [Open Container Initiative (OCI)](https://opencontainers.org/) format where possible, with some modifications to support the needs of constrained, embedded devices. The manifest format is modeled after the [OCI Image Manifest](https://github.com/opencontainers/image-spec/blob/main/manifest.md) format and conforms to the [Wasm OCI Artifact](https://tag-runtime.cncf.io/wgs/wasm/deliverables/wasm-oci-artifact/) layout specifications.
+
+Ocre containers can be stored either as a single zip file or as a set of files in a directory, providing flexibility in how they are distributed and managed. The container format uses the Wasm OCI Artifact layout as its `config.mediaType`, ensuring compatibility with standard OCI tooling while maintaining the specific requirements for WebAssembly modules in embedded environments.
+
+
+---
+
+## Learn More
+
+To fully understand the Ocre container format, explore these detailed specifications. 
+
+- [Image Components](../image_components): Learn about the core elements that make up an Ocre container. 
+- [Image Manifest](../image_manifest): Understand how the manifest file organizes and references container components.
+- [Image Configuration](../image_configuration): Discover how to configure container execution, permissions, and runtime behavior.