docs: revise docs

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

README.md

@@ -1,117 +1,25 @@
 # Dalec
 
 Dalec is a project aimed at providing a declarative format for building system packages and containers from those packages.
-Dalec is still under heavy development and the spec format is not currently considered stable.
 
-Currently only support for Azure Linux (CBL-Mariner 2.0) is available but support
-for other Linux distributions and operating systems is planned and is already [pluggable]().
+Our goal is to provide a secure and reproducible way to build packages and containers, with a focus on supply chain security.
 
-## Usage
+> [!NOTE]
+> Dalec is still under heavy development and the spec format is not currently considered stable. Feedback is welcome! ❤️
 
-Dalec is currently provided as a buildkit frontend which enables you to use dalec with tools like `docker build`.
-You can find the JSON schema for the dalec spec [in docs/spec.schema.json](./docs/spec.schema.json).
+## Features
 
-You will need to add a `syntax` directive at the top of your spec file to enable the dalec frontend:
-
-```yaml
-# syntax=ghcr.io/azure/dalec/frontend:latest
-```
-
-### Examples:
-
-You can look at the [test/fixtures](./test/fixtures) directory for examples of dalec specs.
-
-Build an rpm for mariner2:
-
-```console
-$ docker build -f test/fixtures/moby-runc.yml --target mariner2/rpm --output=_output .
-<output truncated>
-```
-
-With this command you should have a _output/RPMS/\<arch>, _output/RPMS/noarch, and _output/SRPMS directories with the built RPM and SRPM files.
-
-Build a container for mariner2:
-
-```console
-$ docker build -f test/fixtures/moby-runc.yml --target mariner2/container -t test-runc-container:example .
-```
-
-This container will have the rpm along with all its dependencies installed.
-The base image used for the container is determined by the target.
-For mariner2 this is `mcr.microsoft.com/cbl-mariner/distroless/base:2.0`.
-This can be customized in your yaml spec for the target.
-Example:
-
-```yaml
-targets:
-    mariner2:
-        image:
-            base: mcr.microsoft.com/cbl-mariner/base/core:2.0
-```
-
-Dalec will try to detect if the image is a "distroless" image by checking if the `rpm` binary is present.
-If it is present then dalec assumes the image is *not* distroless and installs the rpm like normal.
-When the image is distroless the rpm is installed and then the rpm database is cleaned up and
-rpm manifests are created at `/var/lib/rpmmanifest`.
-
-To print a list of available build targets:
-
-```console
-$ BUILDX_EXPERIMENTAL=1 docker build --print=targets -f test/fixtures/moby-runc.yml .
-debug/gomods                 Outputs all the gomodule dependencies for the spec
-debug/resolve                Outputs the resolved dalec spec file with build args applied.
-debug/sources                Outputs all sources from a dalec spec file.
-mariner2/container (default) Builds a container image for mariner2.
-mariner2/container/depsonly  Builds a container image with only the runtime dependencies installed.
-mariner2/rpm                 Builds an rpm and src.rpm for mariner2.
-mariner2/rpm/debug/buildroot Outputs an rpm buildroot suitable for passing to rpmbuild.
-mariner2/rpm/debug/sources   Outputs all the sources specified in the spec file in the format given to rpmbuild.
-mariner2/rpm/debug/spec      Outputs the generated RPM spec file
-```
-
-
-## Support for other OSes and Linux distributions
-
-Dalec can never hope to bake in support for every OS and Linux distribution.
-Dalec is designed to be pluggable.
-Even if the base dalec frontend does not support your distro/OS of choice, the spec format is designed to allow referencing a custom frontend.
-This way you can support other distros/OSes without having to fork dalec, wait for a new release, or even change the `syntax` directive in your spec file.
-
-Additionally, the structure of dalec is such that you can use dalec as a library to build your frontend.
-In the `frontend` package you can register your build targets with `frontend.RegisterTarget` and then use `frontend.Build` as the buildkit `BuildFunc`
-See `./cmd/frontend/main.go` for how this is used.
-
-### Example
-
-```yaml
-# ...
-targets:
-  custom_distro:
-    frontend:
-        image: <frontend image>
-# ...
-```
-
-## Docs
-
-Docs are available at [https://azure.github.io/dalec/](https://azure.github.io/dalec/).
-
-
-### Building the docs
-
-You can view the docs locally by running:
-
-```console
-$ go -C website run .
-```
-
-This will, by default, make the docs available on `http://localhost:3000/dalec/`.
-You can customize the port with `--port <port>`.
-
-```console
-$ go -C website run . --port 3001
-```
+- 🐳 No additional tools are needed except for [Docker](https://docs.docker.com/engine/install/)!
+- 🚀 Easy to use declarative configuration that provides reproducible builds
+- 📦 Build packages and/or containers for [Azure Linux](https://github.com/microsoft/azurelinux) 2 and 3 (formerly known as CBL-Mariner)
+- 🔌 Pluggable support for other operating systems
+- 🤏 Minimal image size, resulting in less vulnerabilities and smaller attack surface
+- 🪟 Support Windows containers for Go
+- 🚉 Support for multi-platform images
+- ✍️ Support for signed packages
+- 🔐 Ensure supply chain security with build time SBOMs, and Provenance attestations
 
+👉 To get started, please see [Dalec documentation](https://azure.github.io/dalec/)!
 
 ## Contributing
 

website/README.md

@@ -2,6 +2,21 @@
 
 This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
+### Building the docs
+
+You can view the docs locally by running:
+
+```console
+$ go -C website run .
+```
+
+This will, by default, make the docs available on `http://localhost:3000/dalec/`.
+You can customize the port with `--port <port>`.
+
+```console
+$ go -C website run . --port 3001
+```
+
 ### Installation
 
 ```

website/docs/build-source.md

@@ -0,0 +1,172 @@
+---
+title: Building from source
+---
+
+In this section, we'll go over how to build packages from source with Dalec.
+
+To do this, we'll need a few things:
+
+1. A list of sources to pull from
+2. A build script to build the sources
+3. A list of artifacts to include in the package
+
+In this example, we'll build the `go-md2man` package and container from [`go-md2man`](https://github.com/cpuguy83/go-md2man) repo using `v2.0.3` tag in the repo.
+
+First, let's start with the contructing a [Dalec spec](spec.md) file.
+
+We define the metadata of the package in the spec. This includes the name, packager, vendor, license, website, and description of the package.
+
+```yaml
+# syntax=ghcr.io/azure/dalec/frontend:latest
+name: go-md2man
+version: 2.0.3
+revision: "1"
+packager: Dalec Example
+vendor: Dalec Example
+license: MIT
+description: A tool to convert markdown into man pages (roff).
+website: https://github.com/cpuguy83/go-md2man
+```
+
+In the next section, we define the sources that we will be pulling from. In this case, we are pulling from a git repository.
+
+One thing to note, in many build systems you will not have access to the Internet while building the package, and indeed that is the case with the `mariner2` target. As such, this build will fail because `go build` will try to download the go modules. For this reason, we added a `generate` section to the source to run `go mod download` in a docker image with the `src` source mounted and then extract the go modules from the resulting filesystem.
+
+```yaml
+sources:
+  src:
+    git:
+      url: https://github.com/cpuguy83/go-md2man.git
+      commit: "v2.0.3"
+    generate:
+      - gomod: {}
+```
+
+In the next section, we define the dependencies that are needed to build the package. In this case, we need the `golang` dependency at the build time, and `openssl-libs` at runtime. Build dependencies are dependencies that are needed to build the package, while runtime dependencies are dependencies that are needed to run the package.
+
+```yaml
+dependencies:
+  build:
+    golang:
+  runtime:
+    openssl-libs:
+```
+
+Now, let's define the build steps. In this case, we are building the `go-md2man` binary.
+
+```yaml
+build:
+  env:
+    CGO_ENABLED: "0"
+  steps:
+    - command: |
+        cd src
+        go build -o go-md2man .
+```
+
+Next, we define the artifacts that we want to include in the package. In this case, we are including the `go-md2man` binary.
+
+```yaml
+artifacts:
+  binaries:
+    src/go-md2man:
+```
+
+Image section defines the entrypoint and command for the image. In this case, we are setting the entrypoint to `go-md2man` and the command to `--help`.
+
+```yaml
+image:
+  entrypoint: go-md2man
+  cmd: --help
+```
+
+Finally, we can add a test case to the spec file which helps ensure the package is assembled as expected. The following test will make sure `/usr/bin/go-md2man` is installed and has the expected permissions. These tests are automatically executed when building the container image.
+
+```yaml
+tests:
+  - name: Check bin
+    files:
+      /usr/bin/go-md2man:
+        permissions: 0755
+```
+
+Now, let's put it all together in a single file.
+
+```yaml
+# syntax=ghcr.io/azure/dalec/frontend:latest
+# syntax=ghcr.io/azure/dalec/frontend:latest
+name: go-md2man
+version: 2.0.3
+revision: "1"
+packager: Dalec Example
+vendor: Dalec Example
+license: MIT
+description: A tool to convert markdown into man pages (roff).
+website: https://github.com/cpuguy83/go-md2man
+
+sources:
+  src:
+    generate:
+      - gomod: {}
+    git:
+      url: https://github.com/cpuguy83/go-md2man.git
+      commit: "v2.0.3"
+
+dependencies:
+  build:
+    golang:
+
+build:
+  env:
+    CGO_ENABLED: "0"
+  steps:
+    - command: |
+        cd src
+        go build -o go-md2man .
+
+artifacts:
+  binaries:
+    src/go-md2man:
+
+image:
+  entrypoint: go-md2man
+  cmd: --help
+
+tests:
+  - name: Check bin
+    files:
+      /usr/bin/go-md2man:
+        permissions: 0755
+```
+
+:::note
+Full example can be found at [examples/go-md2man.yml](https://github.com/Azure/dalec/blob/main/docs/examples/go-md2man.yml)
+:::
+
+Now that we have the spec file, we can build the package and container using `docker`.
+
+## Building using Docker
+
+In this section, we'll go over how to build packages and containers with Dalec. Other applicable Docker parameters will also apply to Dalec.
+
+Targets here are example. You can find more information about applicable targets in the [targets](targets.md) section.
+
+### Building an RPM package
+
+To build an RPM package only, we can use the following command:
+
+```shell
+docker build -t go-md2man:2.0.3 -f examples/go-md2man.yml --target=mariner2/rpm --output=_output .
+```
+
+This will create `RPM` and `SRPM` directories in the `_output` directory with the built RPM and SRPM packages respectively.
+
+### Building a container
+
+To build a container, we can use the following command:
+
+```shell
+docker build -t go-md2man:2.0.3 -f examples/go-md2man.yml --target=mariner2,
+```
+
+This will produce a container image named `go-md2man:2.0.3`.

website/docs/build.md

@@ -0,0 +1,25 @@
+---
+title: Building with DALEC
+---
+
+In this section, we'll go over how to build packages and containers with Dalec.
+
+To get started, you'll need to have [Docker](https://docs.docker.com/engine/install/) installed.
+
+## Creating a Dalec Spec
+
+The Dalec spec is a YAML file that describes the package to be built and any customizations to the output image. It includes package metadata like name, version, packager, and other things typically found in a system package. It also includes a list of build and runtime dependencies, how to build the project to be packaged, and what files are included in the package.
+
+For more information on the Dalec spec, see the [DALEC Specification](spec.md).
+
+## Building from source(s)
+
+Dalec can build packages and containers from source code repositories. This is done by specifying the source code repository and the build steps in the Dalec spec. The source code is checked out, built, and the resulting artifacts are included in the package.
+
+For more information on building from source, see [Building from source](build-source.md).
+
+## Virtual Packages
+
+In addition to building a traditional package that installs binaries and other files you can also create a "virtual" package, which is a package that references other packages but doesn't install any files itself. This is useful for creating a package that is just a collection of dependencies.
+
+For more information on virtual packages, see [Virtual Packages](virtual-packages.md).

website/docs/editor-support.md

@@ -2,7 +2,7 @@
 title: Editor Support
 ---
 
-There is a [json schema file](https://github.com/Azure/dalec/blob/main/docs/spec.schema.json) which can be used to integrate with your editor.
+We provide a [JSON schema file](https://github.com/Azure/dalec/blob/main/docs/spec.schema.json) to integrate with your editor.
 This will help validate your yaml files and provide intellisense for the spec.
 
 ## VSCode