Skip to content

Commit

Permalink
doc: Update
Browse files Browse the repository at this point in the history
  • Loading branch information
mcmah309 committed Oct 27, 2024
1 parent a907959 commit 6099bf2
Showing 1 changed file with 61 additions and 31 deletions.
92 changes: 61 additions & 31 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,12 @@
[<img alt="crates.io" src="https://img.shields.io/crates/v/containeryard.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](https://crates.io/crates/containeryard)
[<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-containeryard-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs" height="20">](https://docs.rs/containeryard)

ContainerYard is a declarative, reproducible, and reusable decentralized approach for defining containers. Think Nix flakes meets Containerfiles (aka Dockerfiles).
ContainerYard is a declarative, reproducible, and reusable decentralized approach for defining containers.

ContainerYard breaks Containerfiles into modules. Modules represent some specific functionality of a container. e.g. The [rust module](https://github.com/mcmah309/yard_module_repository/tree/3c81a4a383f4446437df364ef0a6ba17bc88c479/dependent/apt/rust) defines rust's installation. Modules also support [Tera](https://keats.github.io/tera/docs/#templates) templating.
ContainerYard breaks Containerfiles into [modules](#declaring-a-simple-module). Modules represent specific functionality of a container. e.g. The [rust module](https://github.com/mcmah309/yard_module_repository/tree/3c81a4a383f4446437df364ef0a6ba17bc88c479/dependent/apt/rust) defines rust's installation. While a `yard.yaml` file composes modules into Containerfiles.

## yard.yaml

A `yard.yaml` file is used to compose modules into Containerfiles.
```yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/mcmah309/containeryard/master/src/schemas/yard-schema.json

Expand Down Expand Up @@ -47,24 +48,16 @@ hooks:
post: echo Done
```
To compose the modules defined in `yard.yaml` into Containerfiles, simply run `yard build .`.
To compose the modules defined in `yard.yaml` into Containerfiles, simply run `yard build`.
Which in the above case, will output a single Containerfile to your current directory.

## Declaring A Simple Module

A module consists of a [Tera](https://keats.github.io/tera/docs/#templates) template named `Containerfile` and a `yard-module.yaml` file
that defines configuration options and dependencies of the template.

**Containerfile**
```Containerfile
FROM alpine:{{ version | default (value="latest") }}
Modules represent some specific functionality of a container.
A module consists of a `yard-module.yaml` file and a `Containerfile`.

RUN apk update \
&& apk upgrade \
&& apk add --no-cache ca-certificates \
&& update-ca-certificates
```
**yard-module.yaml**
### yard-module.yaml
`yard-module.yaml` defines the configuration options of the `Containerfile`.
```yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/mcmah309/containeryard/master/src/schemas/yard-module-schema.json
Expand All @@ -76,28 +69,43 @@ args:
# Files to be pulled in with this module
required_files:
```
`yard.yaml` provides the values for `args:` declared in a `yard-module.yaml`.
e.g.
```yaml
inputs:
modules:
module: path/to/module
For more module examples click [here](https://github.com/mcmah309/yard_module_repository/tree/master).

## Installation

Note: `yard` is the cli tool for ContainerYard.
outputs:
Containerfile:
- module:
version: "3.20.0"
```

### Debian - Ubuntu, Linux Mint, Pop!_OS, etc.
### Containerfile
`Containerfile` is the feature/functionality of the module.
```Containerfile
FROM alpine:{{ version | default (value="latest") }}
```bash
release_ver=<INSERT_CURRENT_VERSION> # e.g. release_ver='v0.2.7'
deb_file="containeryard_$(echo $release_ver | sed 's/^v//')-1_amd64.deb"
curl -LO https://github.com/mcmah309/containeryard/releases/download/$release_ver/$deb_file
dpkg -i "$deb_file"
RUN apk update \
&& apk upgrade \
&& apk add --no-cache ca-certificates \
&& update-ca-certificates
```
`Containerfile` (aka [Dockerfile](https://docs.docker.com/reference/dockerfile/))
is treated first as a [Tera](https://keats.github.io/tera/docs/#templates) template, then compiled.

### Cargo
Thus combining the examples from this section, the output for the final component would be
```Containerfile
FROM alpine:3.20.0
```bash
cargo install containeryard
RUN apk update \
&& apk upgrade \
&& apk add --no-cache ca-certificates \
&& update-ca-certificates
```
Consider adding `--profile dist` for a longer compile time but a more optimal build.

For more module examples click [here](https://github.com/mcmah309/yard_module_repository/tree/master).

## Why Use ContainerYard?

Expand All @@ -113,10 +121,32 @@ and Tera templates are powerful enough. Just let ContainerYard be the glue.

## Why Use Container Yard Over Nix Flakes

Think Nix flakes meets Containerfiles (aka Dockerfiles).

Nix flakes guarantees reproducibility at the cost of developer flexibility. Container Yard is decentralized, allowing users to easily use different package managers and upstreams. As such, Container Yard sacrifices some reproducibility guarantees and gains complete developer flexibility.

Container Yard is also extremely simple and built on familiar developer tools - Containerfiles and Tera templates.

## Installation

Note: `yard` is the cli tool for ContainerYard.

### Debian - Ubuntu, Linux Mint, Pop!_OS, etc.

```bash
release_ver=<INSERT_CURRENT_VERSION> # e.g. release_ver='v0.2.7'
deb_file="containeryard_$(echo $release_ver | sed 's/^v//')-1_amd64.deb"
curl -LO https://github.com/mcmah309/containeryard/releases/download/$release_ver/$deb_file
dpkg -i "$deb_file"
```

### Cargo

```bash
cargo install containeryard
```
Consider adding `--profile dist` for a longer compile time but a more optimal build.

## Contributing

Feel free to open an issue with any suggestions/ideas/bugs you may have and/or create PR's.
Expand Down

0 comments on commit 6099bf2

Please sign in to comment.