kairos/luet
1
0
Fork 0
mirror of https://github.com/mudler/luet.git synced 2025-04-27 19:25:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

📓 Add docs alongside

Browse Source
This commit is contained in:
Ettore Di Giacinto 2022-01-30 19:44:45 +01:00
parent 6f77fa2b3a
commit a591a1e44f
55 changed files with 3194 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
.github/workflows/pages.yml vendored Normal file
View File

@ -0,0 +1,23 @@
name: Github Pages
on:
push:
branches: [ master, docs ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
submodules: 'recursive'
- name: Build 🔧
run: |
cd docs && make build
mv public ../
- name: Deploy 🚀
if: github.ref == 'refs/heads/master' && github.event_name == 'push'
uses: JamesIves/github-pages-deploy-action@releases/v3
with:
ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
BRANCH: gh-pages
FOLDER: public

6
.gitignore vendored
View File

@ -3,3 +3,9 @@ luet
tests/integration/shunit2
tests/integration/bin
release/
/docs/bin/
/docs/public/
/docs/resources/
/docs/node_modules/
/docs/package-lock.json
/docs/package.json

3
.gitmodules vendored Normal file
View File

@ -0,0 +1,3 @@
[submodule "docs/themes/docsy"]
path = docs/themes/docsy
url = https://github.com/google/docsy.git

14
README.md
View File

@ -12,7 +12,7 @@
Luet is a multi-platform Package Manager based off from containers - it uses Docker (and others) to build packages. It has zero dependencies and it is well suitable for "from scratch" environments. It can also version entire rootfs and enables delivery of OTA-alike updates, making it a perfect fit for the Edge computing era and IoT embedded devices.
It offers a simple [specfile format](https://luet-lab.github.io/docs/docs/concepts/packages/specfile/) in YAML notation to define both [packages](https://luet-lab.github.io/docs/docs/concepts/packages/) and [rootfs](https://luet-lab.github.io/docs/docs/concepts/packages/#package-layers). As it is based on containers, it can be also used to build stages for Linux From Scratch installations and it can build and track updates for those systems.
It offers a simple [specfile format](https://luet.io/docs/concepts/packages/specfile/) in YAML notation to define both [packages](https://luet.io/docs/concepts/packages/) and [rootfs](https://luet.io/docs/concepts/packages/#package-layers). As it is based on containers, it can be also used to build stages for Linux From Scratch installations and it can build and track updates for those systems.
It is written entirely in Golang and where used as package manager, it can run in from scratch environment, with zero dependencies.
@ -25,10 +25,10 @@ It is written entirely in Golang and where used as package manager, it can run i
- It builds from containers, but installs, uninstalls and perform upgrades on machines
- Installer doesn't depend on anything ( 0 dep installer !), statically built
- You can install it aside also with your current distro package manager, and start building and distributing your packages
- [Support for packages as "layers"](https://luet-lab.github.io/docs/docs/concepts/packages/specfile/#building-strategies)
- [It uses SAT solving techniques to solve the deptree](https://luet-lab.github.io/docs/docs/concepts/overview/constraints/) ( Inspired by [OPIUM](https://ranjitjhala.github.io/static/opium.pdf) )
- Support for [collections](https://luet-lab.github.io/docs/docs/concepts/packages/collections/) and [templated package definitions](https://luet-lab.github.io/docs/docs/concepts/packages/templates/)
- [Can be extended with Plugins and Extensions](https://luet-lab.github.io/docs/docs/concepts/plugins-and-extensions/)
- [Support for packages as "layers"](https://luet.io/docs/concepts/packages/specfile/#building-strategies)
- [It uses SAT solving techniques to solve the deptree](https://luet.io/docs/concepts/overview/constraints/) ( Inspired by [OPIUM](https://ranjitjhala.github.io/static/opium.pdf) )
- Support for [collections](https://luet.io/docs/concepts/packages/collections/) and [templated package definitions](https://luet.io/docs/concepts/packages/templates/)
- [Can be extended with Plugins and Extensions](https://luet.io/docs/concepts/plugins-and-extensions/)
- [Can build packages in Kubernetes (experimental)](https://github.com/mudler/luet-k8s)
- Uses containerd/go-containerregistry to manipulate images - works also daemonless with the img backend
@ -37,7 +37,7 @@ It is written entirely in Golang and where used as package manager, it can run i
To install luet, you can grab a release on the [Release page](https://github.com/mudler/luet/releases) or to install it in your system:
```bash
$ curl https://get.mocaccino.org/luet/get_luet_root.sh | sudo sh
$ curl https://luet.io/install.sh | sudo sh
$ luet search ...
$ luet install ..
$ luet --help
@ -53,7 +53,7 @@ $ make build
## Documentation
[Documentation](https://luet-lab.github.io/docs) is available, or
[Documentation](https://luet.io/) is available, or
run `luet --help`, any subcommand is documented as well, try e.g.: `luet build --help`.
# Dependency solving

22
docs/.github/workflows/pages.yml vendored Normal file
View File

@ -0,0 +1,22 @@
name: Github Pages
on:
push:
branches: [ master ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
with:
submodules: 'recursive'
- name: Build 🔧
run: |
make build
- name: Deploy 🚀
if: github.ref == 'refs/heads/master' && github.event_name == 'push'
uses: JamesIves/github-pages-deploy-action@releases/v3
with:
ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
BRANCH: gh-pages
FOLDER: public

6
docs/.gitignore vendored Normal file
View File

@ -0,0 +1,6 @@
bin/
public/
resources/
node_modules/
tech-doc-hugo

4
docs/.gitmodules vendored Normal file
View File

@ -0,0 +1,4 @@
[submodule "themes/docsy"]
path = themes/docsy
url = https://github.com/google/docsy

0
docs/.hugo_build.lock Normal file
View File

1
docs/CNAME Normal file
View File

@ -0,0 +1 @@
luet.io

18
docs/Makefile Normal file
View File

@ -0,0 +1,18 @@
export HUGO_VERSION?=0.91.2
export HUGO_PLATFORM?=Linux-64bit
export ROOT_DIR:=$(shell dirname $(realpath $(lastword $(MAKEFILE_LIST))))
.DEFAULT_GOAL := build
.PHONY: build
build:
scripts/build.sh
.PHONY: serve
serve:
scripts/serve.sh
.PHONY: publish
publish:
scripts/publish.sh

62
docs/assets/scss/_variables_project.scss Normal file
View File

@ -0,0 +1,62 @@
/*
Add styles or override variables from the theme here.
*/
$enable-gradients: true;
$enable-rounded: false;
$enable-shadows: true;
$google_font_name: "Alata";
$google_font_family: "Alata:300,300i,400,400i,700,700i";
.td-box--primary .td-arrow-down::before, .td-box--1 .td-arrow-down::before{
border-color: #2F3061 transparent transparent transparent !important;
}
.td-box--primary {
background-color: #2F3061 !important;
}
.td-box--1 { background-color: #2F3061 !important; }
.td-box--2 { background-color: #201A23 !important; }
.td-box--dark {
background-color: #343434 !important;
}
.td-box--3 {
color: #fff !important;
background-color: #5F5980 !important;
}
.td-navbar {
background: #5F5980 !important;
}
.navbar-bg-onscroll {
background: #5F5980 !important;
}
.td-box--4 {
background-color: #DFDFDF !important;
}
.btn-primary {
background: #5F5980 !important;
border-color: #5F5980 !important;
}
.btn-secondary {
background: #657DC2 !important;
border-color: #657DC2 !important;
}

165
docs/config.toml Normal file
View File

@ -0,0 +1,165 @@
baseURL = "https://www.luet.io"
title = "Luet"
enableRobotsTXT = true
# Hugo allows theme composition (and inheritance). The precedence is from left to right.
theme = ["docsy"]
# Will give values to .Lastmod etc.
enableGitInfo = true
# Language settings
contentDir = "content/en"
defaultContentLanguage = "en"
defaultContentLanguageInSubdir = false
# Useful when translating.
enableMissingTranslationPlaceholders = true
disableKinds = ["taxonomy", "taxonomyTerm"]
# Highlighting config
pygmentsCodeFences = true
pygmentsUseClasses = false
# Use the new Chroma Go highlighter in Hugo.
pygmentsUseClassic = false
#pygmentsOptions = "linenos=table"
# See https://help.farbox.com/pygments.html
pygmentsStyle = "tango"
# Configure how URLs look like per section.
[permalinks]
blog = "/:section/:year/:month/:day/:slug/"
## Configuration for BlackFriday markdown parser: https://github.com/russross/blackfriday
[blackfriday]
plainIDAnchors = true
hrefTargetBlank = true
angledQuotes = false
latexDashes = true
# Image processing configuration.
[imaging]
resampleFilter = "CatmullRom"
quality = 75
anchor = "smart"
[services]
[services.googleAnalytics]
# Comment out the next line to disable GA tracking. Also disables the feature described in [params.ui.feedback].
id = "UA-00000000-0"
# Language configuration
[languages]
[languages.en]
title = "Luet"
description = "Package manager built from containers"
languageName ="English"
# Weight used for sorting.
weight = 1
#[languages.it]
#title = "Luet"
#description = "Gestore di pacchetti basato su containers"
#languageName ="Italian"
#contentDir = "content/it"
#time_format_default = "02.01.2006"
#time_format_blog = "02.01.2006"
[[menu.main]]
name = "Contribution guidelines"
weight = 50
url = "https://github.com/mudler/luet/contribute"
pre = "<i class='fab fa-github'></i>"
post = ""
[markup]
[markup.goldmark]
[markup.goldmark.renderer]
unsafe = true
# Everything below this are Site Params
[params]
copyright = "Ettore Di Giacinto"
privacy_policy = "https://policies.google.com/privacy"
# First one is picked as the Twitter card image if not set on page.
# images = ["images/project-illustration.png"]
# Menu title if your navbar has a versions selector to access old versions of your site.
# This menu appears only if you have at least one [params.versions] set.
version_menu = "Releases"
# Repository configuration (URLs for in-page links to opening issues and suggesting changes)
github_repo = "https://github.com/mudler/luet"
# An optional link to a related project repo. For example, the sibling repository where your product code lives.
github_project_repo = "https://github.com/mudler/luet"
# Specify a value here if your content directory is not in your repo's root directory
github_subdir = "docs"
# Google Custom Search Engine ID. Remove or comment out to disable search.
#gcs_engine_id = "011737558837375720776:fsdu1nryfng"
# Enable Algolia DocSearch
algolia_docsearch = false
# Enable Lunr.js offline search
offlineSearch = true
# User interface configuration
[params.ui]
# Enable to show the side bar menu in its compact state.
sidebar_menu_compact = false
# Set to true to disable breadcrumb navigation.
breadcrumb_disable = true
# Set to true to hide the sidebar search box (the top nav search box will still be displayed if search is enabled)
sidebar_search_disable = false
# Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top nav bar
navbar_logo = true
# Set to true to disable the About link in the site footer
footer_about_disable = false
# Adds a H2 section titled "Feedback" to the bottom of each doc. The responses are sent to Google Analytics as events.
# This feature depends on [services.googleAnalytics] and will be disabled if "services.googleAnalytics.id" is not set.
# If you want this feature, but occasionally need to remove the "Feedback" section from a single page,
# add "hide_feedback: true" to the page's front matter.
[params.ui.feedback]
enable = true
# The responses that the user sees after clicking "yes" (the page was helpful) or "no" (the page was not helpful).
yes = 'Glad to hear it! Please <a href="https://github.com/Luet-lab/docs/issues/new">tell us how we can improve</a>.'
no = 'Sorry to hear that. Please <a href="https://github.com/Luet-lab/docs/issues/new">tell us how we can improve</a>.'
[params.links]
# End user relevant links. These will show up on left side of footer and in the community page if you have one.
# [[params.links.user]]
# name = "User mailing list"
# url = "https://example.org/mail"
# icon = "fa fa-envelope"
# desc = "Discussion and help from your fellow users"
# [[params.links.user]]
# name ="Twitter"
# url = "https://example.org/twitter"
# icon = "fab fa-twitter"
# desc = "Follow us on Twitter to get the latest news!"
# [[params.links.user]]
# name = "Stack Overflow"
# url = "https://example.org/stack"
# icon = "fab fa-stack-overflow"
# desc = "Practical questions and curated answers"
# Developer relevant links. These will show up on right side of footer and in the community page if you have one.
[[params.links.developer]]
name = "GitHub"
url = "https://github.com/mudler/luet"
icon = "fab fa-github"
desc = "Development takes place here!"
[[params.links.developer]]
name = "Slack"
url = "https://join.slack.com/t/luet/shared_invite/enQtOTQxMjcyNDQ0MDUxLWQ5ODVlNTI1MTYzNDRkYzkyYmM1YWE5YjM0NTliNDEzNmQwMTkxNDRhNDIzM2Y5NDBlOTZjZTYxYWQyNDE4YzY"
icon = "fab fa-slack"
desc = "Join us on Slack!"
# [[params.links.developer]]
# name = "Developer mailing list"
# url = "https://example.org/mail"
# icon = "fa fa-envelope"
# desc = "Discuss development issues around the project"

81
docs/content/en/_index.html Normal file
View File

@ -0,0 +1,81 @@
+++
title = "Luet docs"
linkTitle = "luetdocs"
+++
{{< blocks/cover title="Luet" image_anchor="top" height="full" color="orange" >}}
<div class="mx-auto">
<a class="btn btn-lg btn-primary mr-3 mb-4" href="{{< relref "/docs" >}}">
Documentation <i class="fas fa-arrow-alt-circle-right ml-2"></i>
</a>
<a class="btn btn-lg btn-secondary mr-3 mb-4" href="https://github.com/mudler/luet/releases">
Download <i class="fab fa-github ml-2 "></i>
</a>
<p class="lead mt-5">Container Package Manager</p>
<div class="mx-auto mt-5">
{{< blocks/link-down color="info" >}}
</div>
</div>
{{< /blocks/cover >}}
{{% blocks/lead color="primary" %}}
Luet uses Container technologies ( Docker, img ) to build packages.
It provides an abstraction over the Dockerfile format introducing relation and versioning of images.
{{% /blocks/lead %}}
{{< blocks/section color="dark" >}}
{{% blocks/feature icon="fa-tree" title="SAT Solver" %}}
Luet uses SAT Solving techniques to compute the dependencies graph.
This allows to refer to docker images by using semver constraints.
No Relational db is involved.
{{% /blocks/feature %}}
{{% blocks/feature icon="fab fa-github" title="Contributions welcome!" url="https://github.com/mudler/luet" %}}
If you like to play with code, check out our issues that are marked as ["good first issue"](https://github.com/mudler/luet/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) and open a [Pull Request](https://github.com/mudler/luet/pulls) on **GitHub**.
New users are always welcome, and have fun!
{{% /blocks/feature %}}
{{% blocks/feature icon="fa-terminal" title="Container-based" %}}
Use container abstraction to define your package repositories
{{% /blocks/feature %}}
{{< /blocks/section >}}
{{< blocks/section >}}
<div class="col">
<h1 class="text-center">Releasing is not anymore a nightmare</h1>
<center>You can carefully pick now dependencies to make your release - release composed of container images or either of a set of packages
</center>
</div>
{{< /blocks/section >}}
{{< blocks/section >}}
{{% blocks/feature icon="fa-truck" title="Package Management" %}}
Build, ship and delivery your software. Faster
{{% /blocks/feature %}}
{{% blocks/feature icon="fa-heartbeat" title="0 dep installer" %}}
When Luet is used as installer, it has zero dependencies.
Your system can't break anymore
{{% /blocks/feature %}}
{{% blocks/feature icon="fa-magic" title="Reconstruct images" %}}
Thanks to its SAT core, Luet can reconstruct images defined by dependencies and version constraints.
Building a de-facto tree of container images
{{% /blocks/feature %}}
{{< /blocks/section >}}

41
docs/content/en/about/_index.html Normal file
View File

@ -0,0 +1,41 @@
---
title: About Luet
linkTitle: About
menu:
main:
weight: 10
---
{{< blocks/cover title="About Luet" image_anchor="bottom" height="min" >}}
<p class="lead mt-5">Luet is a Package Manager which uses Containers technologies.
</p>
{{< /blocks/cover >}}
{{% blocks/lead %}}
Luet uses Container technologies ( Docker, img ) to build packages.
It provides an abstraction over the Dockerfile format introducing relation and versioning of images.
{{% /blocks/lead %}}
{{< blocks/section >}}
<div class="col-12">
<h1 class="text-center">Zero-deps installer</h1>
<center>The installer can run in "from scratch" environment - your system will be always recoverable - everything which was built from containers can be installed locally.
</center>
</div>
{{< /blocks/section >}}
{{< blocks/section >}}
<div class="col-12">
<h1 class="text-center">In few commands it allows you to switch between multiple Linux Distributions, in runtime!</h1>
</div>
{{< /blocks/section >}}

BIN
docs/content/en/about/featured-background.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 788 KiB

13
docs/content/en/blog/_index.md Normal file
View File

@ -0,0 +1,13 @@
---
title: "Luet Blog"
linkTitle: "Blog"
menu:
main:
weight: 30
---
This is the **blog** section. It has two categories: News and Releases.
Files in these directories will be listed in reverse chronological order.

8
docs/content/en/blog/news/_index.md Normal file
View File

@ -0,0 +1,8 @@
---
title: "News About Luet"
linkTitle: "News"
weight: 20
---

10
docs/content/en/blog/news/website.md Normal file
View File

@ -0,0 +1,10 @@
---
title: "Website is up"
linkTitle: "Website is up"
date: 2019-12-23
description: >
Website is up
---
Finally the website is up! Docs are a work in progress. Stay tuned for more upcoming updates

14
docs/content/en/blog/releases/0.3.md Executable file
View File

@ -0,0 +1,14 @@
---
title: "0.3 Release"
linkTitle: "0.3"
date: 2019-12-23
description: >
X-Mas release!
---
This release comes with a lot of bugfixes and enhancement to the SAT solver core:
- Add support for `provides`. They allow to have `virtual` packages which can be replaced during solving by other drop-in packages.
- Tons of fixes
- Preparation for upcoming compression support

8
docs/content/en/blog/releases/_index.md Normal file
View File

@ -0,0 +1,8 @@
---
title: "New Releases"
linkTitle: "Releases"
weight: 20
---

8
docs/content/en/community/_index.md Normal file
View File

@ -0,0 +1,8 @@
---
title: Community
menu:
main:
weight: 40
---
<!--add blocks of content here to add more sections to the community page -->

33
docs/content/en/docs/Concepts/Overview/_index.md Normal file
View File

@ -0,0 +1,33 @@
---
title: "Overview"
linkTitle: "Overview"
weight: 1
description: >
See Luet in action.
---
Luet provides an abstraction layer on top of the container image layer to make the package a first class construct. A package definition and all its dependencies are translated by Luet to Dockerfiles which can then be built anywhere that docker runs.
Luet is written entirely in Go and comes as a single static binary. This has a few advantages:
- Easy to recover. You can use luet to bootstrap the system entirely from the ground-up.
- Package manager has no dependencies on the packages that it installs. There is no chance of breaking the package manager by installing a conflicting package, or uninstalling one.
- Portable - it can run on any architecture
Luet brings the containers ecosystem to standard software package management and delivery. It is fully built around the container concept, and leverages the huge catalog already present in the wild. It lets you use Docker images from [Docker Hub](https://hub.docker.com/), or from private registries to build packages, and helps you to redistribute them.
Systems that are using luet as a package manager can consume Luet repositories with only luet itself. No dependency is required by the Package manager, giving you the full control on what you install or not in the system. It can be used to generate *Linux from Scratch* distributions, also to build Docker images, or to simply build standalone packages that you might want to redistribute.
The syntax proposed aims to be [KISS](https://en.wikipedia.org/wiki/KISS_principle) - you define a set of steps that need to be run to build your image, and a set of constraints denoting the requirements or conflicts of your package.
## Why another Package manager?
There is no known package manager with 0-dependency that fully leverages the container ecosystem. This gap forces current package managers to depend on a specific system layout as base of the building process and the corresponding depencies. This can cause situations leading to a broken system. We want to fix that by empowering the user, by building their own packages, and redistribute them.
Luet allows also to create packages entirely from Docker images content. In this way the user can actually bundle all the files of an image into a package and deliver part of it, or entirely as a layer. All of that, without the package manager depending on a single bit from it.
## Package definitions
Luet uses [YAML](https://en.wikipedia.org/wiki/YAML) for the package specification format, Luet parses the [requirements](/docs/docs/concepts/overview/constraints) to build [packages](/docs/docs/concepts/packages), so Luet can consume them.
Below you can find links to tutorials on how to build packages, images and repositories.

188
docs/content/en/docs/Concepts/Overview/build_packages.md Normal file
View File

@ -0,0 +1,188 @@
---
title: "Building packages"
linkTitle: "Building packages"
weight: 1
date: 2017-01-05
description: >
How to build packages with Luet
---
## Prerequisistes
Luet currently supports [Docker](https://www.docker.com/) and [Img](https://github.com/genuinetools/img) as backends to build packages. Both of them can be used and switched in runtime with the ```--backend``` option, so either one of them must be present in the host system.
### Docker
Docker is the (less) experimental Luet engine supported. Be sure to have Docker installed and the daemon running. The user running `luet` commands needs the corresponding permissions to run the `docker` executable, and to connect to a `docker` daemon. The only feature needed by the daemon is the ability to build images, so it fully supports remote daemon as well (this can be specified with the `DOCKER_HOST` environment variable, that is respected by `luet`)
### Img
Luet supports [Img](https://github.com/genuinetools/img). To use it, simply install it in your system, and while running `luet build`, you can switch the backend by providing it as a parameter: `luet build --backend img`. For small packages it is particularly powerful, as it doesn't require any docker daemon running in the host.
### Building packages on Kubernetes
Luet and img can be used together to orchestrate package builds also on kubernetes. There is available an experimental [Kubernetes CRD for Luet](https://github.com/mudler/luet-k8s) which allows to build packages seamelessly in Kubernetes and push package artifacts to an S3 Compatible object storage (e.g. Minio).
## Building packages
![Build packages](/docs/tree.jpg)
Luet provides an abstraction layer on top of the container image layer to make the package a first class construct. A package definition and all its dependencies are translated by Luet to Dockerfiles which can then be built anywhere that docker runs.
To resolve the dependency tree Luet uses a SAT solver and no database. It is responsible for calculating the dependencies of a package and to prevent conflicts. The Luet core is still young, but it has a comprehensive test suite that we use to validate any future changes.
Building a package with Luet requires only a [definition](/docs/docs/concepts/packages/specfile). This definition can be self-contained and be only composed of one [specfile](/docs/docs/concepts/packages/specfile), or a group of them, forming a Luet tree. For more complex use-cases, see [collections](/docs/docs/concepts/packages/collections).
Run `luet build --help` to get more help for each parameter.
Build accepts a list of packages to build, which syntax is in the `category/name-version` notation. See also [specfile documentation page](/docs/docs/concepts/packages/specfile/#refering-to-packages-from-the-cli) to see how to express packages from the CLI.
## Environmental variables
Luet builds passes its environment variable at the engine which is called during build, so for example the environment variable `DOCKER_HOST` or `DOCKER_BUILDKIT` can be setted.
Every argument from the CLI can be setted via environment variable too with a `LUET_` prefix, for instance the flag `--clean`, can be setted via environment with `LUET_CLEAN`, `--privileged` can be enabled with `LUET_PRIVILEGED` and so on.
## Supported compression format
At the moment, `luet` can compress packages and tree with `zstd` and `gzip`. For example:
```bash
luet build --compression zstd ...
```
Will output package compressed in the zstd format.
See the `--help` of `create-repo` and `build` to learn all the available options.
## Example
A [package definition](/docs/docs/concepts/packages/specfile) is composed of a `build.yaml` and a sibiling `definition.yaml`.
In the following example, we are creating a dummy package (`bar/foo`). Which ships one file only, `/foo`
```bash
$> # put yourself in some workdir
$~/workdir> mkdir package
$~/workdir> cat <<EOF > package/build.yaml
image: busybox
steps:
- echo "foo=bar" > /foo
EOF
$~/workdir> cat <<EOF > package/definition.yaml
name: "foo"
version: "0.1"
category: "bar"
EOF
```
To build it, simply run `luet build bar/foo` or `luet build --all` to build all the packages in the current directory:
```bash
$> luet build --all
📦 Selecting foo 0.1
📦 Compiling foo version 0.1 .... ☕
🐋 Downloading image luet/cache-foo-bar-0.1-builder
🐋 Downloading image luet/cache-foo-bar-0.1
📦 foo Generating 🐋 definition for builder image from busybox
🐋 Building image luet/cache-foo-bar-0.1-builder
🐋 Building image luet/cache-foo-bar-0.1-builder done
Sending build context to Docker daemon 4.096kB
...
```
Luet "trees" are just a group of specfiles, in the above example, our tree was the current directory. You can also specify a directory with the `--tree` option. Luet doesn't enforce any tree layout, so they can be nested at any level. The only rule of thumb is that a `build.yaml` file needs to have either a `definition.yaml` or a `collection.yaml` file next to it.
## Nesting dependencies
In the example above we have created a package from a `delta`. Luet by default creates packages by analyzing the differences between the generated containers, and extracts the differences as archive, the resulting files then are compressed and can be consumed later on by `luet install`.
Luet can create packages from different [building strategies](/docs/docs/concepts/packages/specfile/#building-strategies): by delta, by taking a whole container content, or by considering a single directory in the build container.
Besides that, [a package can reference a strict dependency on others](/docs/docs/concepts/packages/specfile/#build-time-dependencies).
### Example
Let's extend the above example with two packages which depends on it during the build phase.
```bash
$~/workdir> mkdir package2
$~/workdir> cat <<EOF > package2/build.yaml
requires:
- name: "foo"
category: "bar"
version: ">=0"
steps:
- source /foo && echo "$foo" > /bar
EOF
$~/workdir> cat <<EOF > package2/definition.yaml
name: "ineedfoo"
version: "0.1"
category: "bar"
EOF
$~/workdir> mkdir package3
$~/workdir> cat <<EOF > package3/build.yaml
requires:
- name: "foo"
category: "bar"
version: ">=0"
- name: "ineedfoo"
category: "bar"
version: ">=0"
steps:
- source /foo && echo "$foo" > /ineedboth
- cat /bar > /bar
EOF
$~/workdir> cat <<EOF > package3/definition.yaml
name: "ineedfooandbar"
version: "0.1"
category: "bar"
EOF
```
To build, run again:
```bash
$> luet build --all
```
As we can see, now Luet generated 3 packages, `bar/foo`, `bar/ineedfoo` and `bar/ineedfooandbar`. They aren't doing anything special than just shipping text files, this is an illustrative example on how build requirements can be combined to form new packages:
`bar/ineedfooandbar` depends on both `bar/ineedfoo` and `bar/foo` during build-time, while `bar/foo` uses a docker image as a build base.
See the [package definition documentation page](/docs/docs/concepts/packages/specfile/#building-strategies) for more details on how to instruct the Luet compiler to build packages with different strategies.
## Caching docker images
Luet can push and pull the docker images that are being generated during the build process. A tree is represented by a single docker image, and each package can have one or more tags attached to it.
To push automatically docker images that are built, use the `--push` option, to pull, use the `--pull` option. An image repository can be specified with `--image-repository` flag, and can include also the remote registries where the images are pushed to.
Luet doesn't handle login to registries, so that has to be handled separately with `docker login` or `img login` before the build process starts.
### Build faster
When packages are cached, for iterating locally it's particularly useful to jump straight to the image that you want to build. You can use ```--only-target-package``` to jump directly to the image you are interested in. Luet will take care of checking if the images are present in the remote registry, and would build them if any of those are missing.
## Notes
- All the files which are next to a `build.yaml` are copied in the container which is running your build, so they are always accessible during build time.
- If you notice errors about disk space, mind to set the `TMPDIR` env variable to a different folder. By default luet respects the O.S. default (which in the majority of system is `/tmp`).

34
docs/content/en/docs/Concepts/Overview/constraints.md Normal file
View File

@ -0,0 +1,34 @@
---
title: "CSP, SAT && RL"
linkTitle: "CSP, SAT && RL"
weight: 4
description: >
How Luet turns Image resolution into CSP
---
Under the hood, Luet uses boolean satisfiability problem ([SAT](https://en.wikipedia.org/wiki/Boolean_satisfiability_problem)) [reinforcement learning](https://en.wikipedia.org/wiki/Reinforcement_learning) techniques to solve package constraints.
Luet allows you to specify 3 types of set of contraints on a [package](/docs/docs/concepts/packages/) definition:
- Requires
- Conflicts
- Provides
The package definition in your tree definition, along with its Requires and Conflicts, are turned into Boolean formulas that are consumed by the solver to compute a solution. The solution represent the state of your system after a particular query is asked to the solver (Install, Uninstall, Upgrade).
## Requires and Conflicts
A list of requires and conflicts, composed of one or more [packages](/docs/docs/concepts/packages/), becomes a SAT formula. The formula is then given to the SAT solver to compute a finite state set of packages which must be installed in the system in order to met the requirements.
As Luet allows to express constraints with selectors ( e.g. `A depends on >=B-1.0`) it generates additional constraints to guarantee that at least one package and at most one is picked as dependency (*ALO* and *AMO*).
## Provides
Provides constraints are not encoded in a SAT formula. Instead, they are `expanded` into an in-place substitution of the packages that they have to be replaced with.
They share the same SAT logic of expansion, allowing to swap entire version ranges (e.g. `>=1.0`), allowing to handle package rename, removals, and virtuals.
## References
- OPIUM (Luet is inspired by it): https://ranjitjhala.github.io/static/opium.pdf
- FROM TRACTABLE CSP TO TRACTABLE SAT: https://www.cs.ox.ac.uk/files/4014/maxclosed_orderencoding_v16_TR.pdf
- Solver concepts applied to packages (`zypper`): https://en.opensuse.org/openSUSE:Libzypp_satsolver_basics

96
docs/content/en/docs/Concepts/Overview/repositories.md Normal file
View File

@ -0,0 +1,96 @@
---
title: "Creating Luet repositories"
linkTitle: "Creating Luet repositories"
weight: 2
date: 2017-01-05
description: >
How to create Luet repositories
---
After a set of packages has been built, a repository must be created in order to make them accessible by Luet clients. A Repository can be served either local files or via http(s) (at the moment of writing). Luet, by default, supports multiple-repositories with priorities.
## Create a repository
After issuing a `luet build`, the built packages are present in the output build directory. The `create-repo` step is needed to generate a portable tree, which is read by the clients, and a `repository.yaml` which contains the repository metadata.
Note that the output of `create-repo` is *additive* so it integrates with the current build content. The repository is composed by the packages generated by the `build` command (or `pack`) and the `create-repo` generated metadata.
### Flags
Some of the relevant flags for `create-repo` are:
- **--descr**: Repository description
- **--name**: Repository name
- **--output**: Metadata output folder (while a different path can be specified, it's prefered to output the metadata files directly to the package directory).This most of the time matches the packages path for convenience.
- **--packages**: Directory where built packages are stored. This most of the time is also the output path.
- **--reset-revision**: Reset the repository revision number
- **--tree-path**: Specify a custom name for the tree path. (Defaults to tree.tar)
- **--tree-compression**: Specify a compression algorithm for the tree. (Available: gzip, Defaults: none)
- **--tree**: Path of the tree which was used to generate the packages and holds package metadatas
- **--type**: Repository type (http/local). It is just descriptive, the clients will be able to consume the repo in whatsoever way it is served.
- **--urls**: List of URIS where the repository is available
See `luet create-repo --help` for a full description.
## Example
Build a package and generate the repository metadata:
```
$> mkdir package
$> cat <<EOF > package/build.yaml
image: busybox
steps:
- echo "foo" > /foo
EOF
$> cat <<EOF > package/definition.yaml
name: "foo"
version: "0.1"
category: "bar" # optional!
EOF
$> luet build --all --destination $PWD/out/ --tree $PWD/package
📦 Selecting foo 0.1
📦 Compiling foo version 0.1 .... ☕
🐋 Downloading image luet/cache-foo-bar-0.1-builder
🐋 Downloading image luet/cache-foo-bar-0.1
📦 foo Generating 🐋 definition for builder image from busybox
🐋 Building image luet/cache-foo-bar-0.1-builder
🐋 Building image luet/cache-foo-bar-0.1-builder done
Sending build context to Docker daemon 4.096kB
...
$> luet create-repo --name "test" --output $PWD/out --packages $PWD/out --tree $PWD/package
For repository test creating revision 1 and last update 1580641614...
$> ls out
foo-bar-0.1-builder.image.tar foo-bar-0.1.image.tar foo-bar-0.1.metadata.yaml foo-bar-0.1.package.tar repository.yaml tree.tar
```
### Repositories type
There are 3 types of repositories supported by luet: `disk`, `http`, `docker`.
#### `disk`
It is a repository which is merely a local folder in your system. When creating a repository and specifying ```--output```, `luet` expects a local path to the system where to store the generated metadata.
#### `http`
It is a repository type which is hosted behind a webserver. When creating a repository and specifying ```--output```, `luet` expects a local path to the system where to store the generated metadata, similarly to the `disk` repository type. Luet is not handling any file upload. The `http` repository type gains meaning when being used from the client, where the repository source must be specified
#### `docker`
When specifying the `docker` repository type, `luet` will generate final images from the build results and upload them to the docker reference specified with ```--output```. The images contains the artifact output from the build result, and they are tagged accordingly to their package name. A single image reference needs to be passed, all the packages will be pushed in a single image but with different tags.
The login to the container registry is not handled, the daemon needs to have already proper permissions to push the image to the destination.
## Notes
- The tree of definition being used to build the repository, and the package directories must **not** be symlinks.
- To build a repository is not required to hold the packages artifacts, only the respective `metadata.yaml` file is required.

138
docs/content/en/docs/Concepts/Overview/usage.md Normal file
View File

@ -0,0 +1,138 @@
---
title: "CLI usage"
linkTitle: "CLI usage"
weight: 3
date: 2019-12-14
description: >
How to install packages, manage repositories, ...
---
## Installing a package
To install a package with `luet`, simply run:
```bash
$ luet install <package_name>
```
To relax dependency constraints and avoid auto-upgrades, add the `--relax` flag:
```bash
$ luet install --relax <package name>
```
To install only the package without considering the deps, add the `--nodeps` flag:
```bash
$ luet install --nodeps <package name>
```
To install only package dependencies, add the `--onlydeps` flag:
```bash
$ luet install --onlydeps <package name>
```
To only download packages, without installing them use the `--download-only` flag:
```bash
$ luet install --download-only <package name>
```
## Uninstalling a package
To uninstall a package with `luet`, simply run:
```bash
$ luet uninstall <package_name>
```
## Upgrading the system
To upgrade your system, simply run:
```bash
$ luet upgrade
```
## Refreshing repositories
Luet automatically syncs repositories definition on the machine when necessary, but it avoids to sync up in a 24h range. In order to refresh the repositories manually, run:
```bash
$ luet repo update
```
## Searching a package
To search a package:
```bash
$ luet search <regex>
```
To search a package and display results in a table:
```bash
$ luet search --table <regex>
```
To look into the installed packages:
```bash
$ luet search --installed <regex>
```
Note: the regex argument is optional
## Search file belonging to packages
```bash
$ luet search --file <file_pattern>
```
### Search output
Search can return results in the terminal in different ways: as terminal output, as json or as yaml.
#### JSON
```bash
$ luet search --json <regex>
```
#### YAML
```bash
$ luet search --yaml <regex>
```
#### Tabular
```bash
$ luet search --table <regex>
```
## Quiet luet output
Luet output is verbose by default and colourful, however will try to adapt to the terminal, based on which environment is executed (as a service, in the terminal, etc.)
You can quiet `luet` output with the `--quiet` flag or `-q` to have a more compact output in all the commands.

271
docs/content/en/docs/Concepts/Packages/_index.md Normal file
View File

@ -0,0 +1,271 @@
---
title: "Packages"
linkTitle: "Packages"
weight: 2
description: >
Package definition syntax
---
A Package in Luet is denoted by a triple (`name`, `category` and `version`), here called *package form* in a `definition.yaml` file in YAML:
```yaml
name: "awesome"
version: "0.1"
category: "foo"
```
While `category` and `version` can be omitted, the name is required. Note that when refering to a package, the triplet is always present:
```yaml
requires:
- name: "awesome"
version: "0.1"
category: "foo"
- name: "bar"
version: "0.1"
category: "foo"
```
## Building process
When a package is required to be built, Luet resolves the dependency trees and orders the spec files to satisfy the given contraints.
Each package build context is where the spec files are found (`definition.yaml` and `build.yaml`). This means that in the container, which is running the build process, the resources inside the package folder are accessible, as normally in Docker.
```
❯ tree distro/raspbian/buster
distro/raspbian/buster
├── build.sh
├── build.yaml
├── definition.yaml
└── finalize.yaml
```
In the example above, `build.sh` is accessible in build time and can be invoked easily in build time in `build.yaml`:
```yaml
steps:
- sh build.sh
```
## Package provides
Packages can specify a list of `provides`. This is a list of packages in *package form*, which indicates that the current definition *replaces* every occurrence of the packages in the list (both at *build* and *runtime*). This mechanism is particularly helpful for handling package moves or for enabling virtual packages (e.g., [gentoo virtual packages](https://packages.gentoo.org/categories/virtual)).
*Note: packages in the `provides` list don't need to exist or have a valid build definition either.*
## Package types
By a combination of keywords in `build.yaml`, you end up with categories of packages that can be built:
- Seed packages
- Packages deltas
- Package layers
- Package with includes
Check the [Specfile concept](/docs/docs/concepts/packages/specfile) page for a full overview of the available keywords in the Luet specfile format.
### Seed packages
Seed packages denote a parent package (or root) that can be used by other packages as a dependency. Normally, seed packages include just an image (preferably tagged) used as a base for other packages to depend on.
It is useful to pin to specific image versions, and to write down in a tree where packages are coming from. There can be as many seed packages as you like in a tree.
A seed package `build.yaml` example is the following:
```yaml
image: "alpine:3.1"
```
Every other package that depends on it will inherit the layers from it.
If you want to extract the content of the seed package in a separate packages (splitting), you can just create as many package as you wish depending on that one, and extract its content, for example:
**alpine/build.yaml**
```yaml
image: "alpine:3.1"
```
**alpine/definition.yaml**
```yaml
name: "alpine"
version: "3.1"
category: "seed"
```
**sh/build.yaml**
```yaml
# List of build-time dependencies
requires:
- name: "alpine"
version: "3.1"
category: "seed"
unpack: true # Tells luet to use the image content by unpacking it
includes:
- /bin/sh
```
**sh/definition.yaml**
```yaml
name: "sh"
category: "utils"
version: "1.0"
```
In this example, there are two packages being specified:
- One is the `seed` package, which is the base image employed to later extract packages. It has no installable content, and it is just virtually used during build phase.
- `sh` is the package which contains `/bin/sh`, extracted from the seed image and packaged. This can be consumed by Luet clients in order to install `sh` in their system.
### Packages delta
Luet, by default, will try to calculate the delta of the package that is meant to be built. This means that it tracks **incrementally** the changes in the packages, to ease the build definition. Let's see an example.
Given the root package:
**alpine/build.yaml**
```yaml
image: "alpine:3.1"
```
**alpine/definition.yaml**
```yaml
name: "alpine"
version: "3.1"
category: "seed"
```
We can generate any file, and include it in our package by defining this simple package:
**foo/build.yaml**
```yaml
# List of build-time dependencies
requires:
- name: "alpine"
version: "3.1"
category: "seed"
steps:
- echo "Awesome" > /foo
```
**foo/definition.yaml**
```yaml
name: "foo"
category: "utils"
version: "1.0"
```
By analyzing the difference between the two packages, Luet will automatically track and package `/foo` as part of the `foo` package.
To allow operations that must not be accounted in to the final package, you can use the `prelude` keyword:
**foo/build.yaml**
```yaml
# List of build-time dependencies
requires:
- name: "alpine"
version: "3.1"
category: "seed"
prelude:
- echo "Not packaged" > /invisible
steps:
- echo "Awesome" > /foo
```
**foo/definition.yaml**
```yaml
name: "foo"
category: "utils"
version: "1.0"
```
The list of commands inside `prelude` that would produce artifacts, are not accounted to the final package. In this example, only `/foo` would be packaged (which output is equivalent to the example above).
This can be used, for instance, to fetch sources that must not be part of the package.
You can apply restrictions anytime and use the `includes` keyword to specifically pin to the files you wish in your package.
### Package layers
Luet can be used to track entire layers and make them installable by Luet clients.
Given the examples above:
**alpine/build.yaml**
```yaml
image: "alpine:3.1"
```
**alpine/definition.yaml**
```yaml
name: "alpine"
version: "3.1"
category: "seed"
```
An installable package derived by the seed, with the actual full content of the layer can be composed as follows:
**foo/build.yaml**
```yaml
# List of build-time dependencies
requires:
- name: "alpine"
version: "3.1"
category: "seed"
unpack: true # It advertize Luet to consume the package as is
```
**foo/definition.yaml**
```yaml
name: "foo"
category: "utils"
version: "1.0"
```
This can be combined with other keywords to manipulate the resulting package (layer), for example:
**foo/build.yaml**
```yaml
# List of build-time dependencies
requires:
- name: "alpine"
version: "3.1"
category: "seed"
unpack: true # It advertize Luet to consume the package as is
steps:
- apk update
- apk add git
- apk add ..
```
**foo/definition.yaml**
```yaml
name: "foo"
category: "utils"
version: "1.0"
```
### Package includes
In addition, the `includes` keyword can be set in order to extract portions from the package image.
**git/build.yaml**
```yaml
# List of build-time dependencies
requires:
- name: "alpine"
version: "3.1"
category: "seed"
unpack: true # It advertize Luet to consume the package as is
steps:
- apk update
- apk add git
includes:
- /usr/bin/git
```
**foo/definition.yaml**
```yaml
name: "git"
category: "utils"
version: "1.0"
```
As a reminder, the `includes` keywords accepts regular expressions in the Golang format. Any criteria expressed by means of Golang regular expressions, and matching the file name (absolute path), will be part of the final package.

33
docs/content/en/docs/Concepts/Packages/collections.md Normal file
View File

@ -0,0 +1,33 @@
---
title: "Collections"
linkTitle: "Collections"
weight: 4
description: >
Group a set of package build spec with templating
---
`Collections` are a special superset of packages. To define a collection, instead of using a `definition.yaml` file, create a `collection.yaml` file with a list of packages:
{{<githubembed repo="mudler/luet" file="tests/fixtures/shared_templates/test/collection.yaml" lang="yaml">}}
Packages under a collection shares the same `build.yaml` and `finalize.yaml`, so a typical package layout can be:
```
collection/
collection.yaml
build.yaml
finalize.yaml
... additional files in the build context
```
Luet during the build phase, will treat packages of a collection individually. A collection is a way to share the same build process across different packages.
## Templating
[The templating mechanism](/docs/docs/concepts/packages/templates) can be used in collections as well, and each stanza in `packages` is used to interpolate each single package.
## Examples
- https://github.com/mocaccinoOS/mocaccino-musl-universe/tree/master/multi-arch/packages/entities
- https://github.com/mocaccinoOS/portage-tree/tree/master/multi-arch/packages/groups
- https://github.com/mocaccinoOS/mocaccino-musl-universe/tree/master/multi-arch/packages/X

630
docs/content/en/docs/Concepts/Packages/specfile.md Normal file
View File

@ -0,0 +1,630 @@
---
title: "Specfile"
linkTitle: "Specfile"
weight: 2
description: >
Luet specfile syntax
---
# Specfiles
Luet [packages](/docs/docs/concepts/packages/) are defined by specfiles. Specfiles define the runtime and builtime requirements of a package. There is an hard distinction between runtime and buildtime. A spec is composed at least by the runtime (`definition.yaml` or a `collection.yaml`) and the buildtime specification (`build.yaml`).
Luet identifies the package definition by looking at directories that contains a `build.yaml` and a `definition.yaml` (or `collection.yaml`) files. A Luet tree is merely a composition of directories that follows this convention. There is no constriction on either folder naming or hierarchy.
*Example of a [tree folder hierarchy](https://github.com/Luet-lab/luet-embedded/tree/master/distro)*
```bash
tree distro
distro
├── funtoo
│   ├── 1.4
│   │   ├── build.sh
│   │   ├── build.yaml
│   │   ├── definition.yaml
│   │   └── finalize.yaml
│   ├── docker
│   │   ├── build.yaml
│   │   ├── definition.yaml
│   │   └── finalize.yaml
│   └── meta
│   └── rpi
│   └── 0.1
│   ├── build.yaml
│   └── definition.yaml
├── packages
│   ├── container-diff
│   │   └── 0.15.0
│   │   ├── build.yaml
│   │   └── definition.yaml
│   └── luet
│   ├── build.yaml
│   └── definition.yaml
├── raspbian
│   ├── buster
│   │   ├── build.sh
│   │   ├── build.yaml
│   │   ├── definition.yaml
│   │   └── finalize.yaml
│   ├── buster-boot
│   │   ├── build.sh
│   │   ├── build.yaml
│   │   ├── definition.yaml
│   │   └── finalize.yaml
```
## Build specs
Build specs are defined in `build.yaml` files. They denote the build-time `dependencies` and `conflicts`, together with a definition of the content of the package.
*Example of a `build.yaml` file*:
```yaml
steps:
- echo "Luet is awesome" > /awesome
prelude:
- echo "nooops!"
requires:
- name: "echo"
version: ">=1.0"
conflicts:
- name: "foo"
version: ">=1.0"
provides:
- name: "bar"
version: ">=1.0"
env:
- FOO=bar
includes:
- /awesome
unpack: true
```
### Building strategies
Luet can create packages with different strategies:
- by delta. Luet will analyze the containers differencies to find out which files got **added**.
You can use the `prelude` section to exclude certains file during analysis.
- by taking a whole container content
- by considering a single directory in the build container.
#### Package by delta
By default Luet will analyze the container content and extract any file that gets **added** to it. The difference is calculated by using the container which is depending on, or either by the container which is created by running the steps in the `prelude` section of the package build spec:
```yaml
prelude:
- # do something...
steps:
- # real work that should be calculated delta over
```
By omitting the `prelude` keyword, the delta will be calculated from the parent container where the build will start from.
#### Package by container content
Luet can also generate a package content from a container. This is really useful when creating packages that are entire versioned `rootfs`. To enable this behavior, simply add `unpack: true` to the `build.yaml`. This enables the Luet unpacking features, which will extract all the files contained in the container which is built from the `prelude` and `steps` fields.
To include/exclude single files from it, use the `includes` and `excludes` directives.
#### Package by a folder in the final container
Similarly, you can tell Luet to create a package from a folder in the build container. To enable this behavior, simply add `package_dir: "/path/to/final/dir"`.
The directory must represent exactly how the files will be ultimately installed from clients, and they will show up in the same layout in the final archive.
So for example, to create a package which ships `/usr/bin/mybin`, we could write:
```yaml
package_dir: "/output"
steps:
- mkdir -p /output/usr/bin/
- echo "fancy stuff" > /output/usr/bin/mybin && chmod +x /output/usr/bin/mybin
```
### Build time dependencies
A package build spec defines how a package is built. In order to do this, Luet needs to know where to start. Hence a package must declare at least either one of the following:
- an `image` keyword which tells which Docker image to use as base, or
- a list of `requires`, which are references to other packages available in the tree.
They can't be both present in the same specfile.
To note, it's not possible to mix package build definitions from different `image` sources. They must form a unique sub-graph in the build dependency tree.
On the other hand it's possible to have multiple packages depending on a combination of different `requires`, given they are coming from the same `image` parent.
### Excluding/including files explictly
Luet can also *exclude* and *include* single files or folders from a package by using the `excludes` and `includes` keyword respecitvely.
Both of them are parsed as a list of Golang regex expressions, and they can be combined together to fine-grainly decide which files should be inside the final artifact. You can refer to the files as they were in the resulting package. So if a package produces a `/foo` file, and you want to exclude it, you can add it to `excludes` as `/foo`.
### Package source image
Luet needs an image to kick-off the build process for each package. This image is being used to run the commands in the `steps` and `prelude`, and then the image is processed by the **building strategies** explained above.
The image can be resolved either by:
1) providing a specific image name with `image`
2) providing a set of package requirements with `requires` which will be constructed a new image from. The resulting image is an image linked between each other with the `FROM` field in the Dockerfile following the SAT solver ordering.
3) providing a set of packages to squash their result from `requires` and by specifying `requires_final_images: true`.
{{< alert color="info" title="Note" >}}
The above keywords cannot be present in the same spec **at the same time**, or they cannot be combined. But you are free to create further intermediate specs to achieve the desired image.
{{< /alert >}}
#### Difference between `requires` and `requires` with `requires_final_images: true`
`requires` generates a graph from all the `images` of the specfile referenced inside the list. This means it builds a chain of images that are used to build the packages, e.g.: `packageA(image: busybox) -> packageB (requires: A) -> packageC (requires: C)`. The container which is running your build then **inherits** it's parents from a chain of order resolution, provided by the SAT solver.
When specifying `requires_final_images: true` luet builds an artifact for each of the packages listed from their compilation specs and it will later *squash* them together in a new container image which is then used in the build process to create an artifact.
The key difference is about *where* your build is going to run from. By specifying `requires_final_images` it will be constructed a new image with the content of each package - while if setting it to false, it will order the images appropriately and link them together with the Dockerfile `FROM` field. That allows to reuse the same images used to build the packages in the require section - or - create a new one from the result of each package compilation.
## Keywords
Here is a list of the full keyword refereces for the `build.yaml` file.
### `conflicts`
(optional) List of packages which it conflicts with in *build time*. In the same form of `requires` it is a list of packages that the current one is conflicting with.
```yaml
conflicts:
- name: "foo"
category: "bar"
version: "1.0"
...
- name: "baz"
category: "bar"
version: "1.0"
```
See [Package concepts](/docs/docs/concepts/packages) for more information on how to represent a package in a Luet tree.
### `copy`
_since luet>=0.15.0_
(optional) A list of packages/images where to copy files from. It is the [Docker multi-stage build](https://docs.docker.com/develop/develop-images/multistage-build/) equivalent but enhanced with tree hashing resolution.
To copy a specific file from a package *build* container:
```yaml
steps:
- ...
prelude:
- ...
copy:
- package:
category: "foo"
name: "bar"
version: ">=0"
source: "/foo"
destination: "/bar"
```
Any package that is listed in the section will be compiled beforeahead the package, and the file is available both in `prelude` and `steps`.
Internally, it's rendered as `COPY --from=package/image:sha /foo /bar`
To copy a specific file from an external image:
```yaml
steps:
- ...
prelude:
- ...
copy:
- image: "buxybox:latest"
source: "/foo"
destination: "/bar"
```
### `env`
(optional) A list of environment variables ( in `NAME=value` format ) that are expanded in `step` and in `prelude`. ( e.g. `${NAME}` ).
```yaml
env:
- PATH=$PATH:/usr/local/go/bin
- GOPATH=/luetbuild/go
- GO111MODULE=on
- CGO_ENABLED=0
- LDFLAGS="-s -w"
```
### `excludes`
(optional) List of golang regexes. They are in full path form (e.g. `^/usr/bin/foo` ) and indicates that the files listed shouldn't be part of the final artifact
Wildcards and golang regular expressions are supported. If specified, files which are not matching any of the regular expressions in the list will be excluded in the final package.
```yaml
excludes:
- ^/etc/shadow
- ^/etc/os-release
- ^/etc/gshadow
```
By combining `excludes` with `includes`, it's possible to include certain files while excluding explicitly some others (`excludes` takes precedence over `includes`).
### `image`
(optional/required) Docker image to be used to build the package.
```yaml
image: "busybox"
```
It might be omitted in place of `requires`, and indicates the image used to build the package. The image will be pulled and used to build the package.
### `includes`
(optional) List of regular expressions to match files in the resulting package. The path is absolute as it would refer directly to the artifact content.
Wildcards and golang regular expressions are supported. If specified, files which are not matching any of the regular expressions in the list will be excluded in the final package.
```yaml
includes:
- /etc$
- /etc/lvm$
- /etc/lvm/.*
- /usr$
- /usr/bin$
- /usr/bin/cc.*
- /usr/bin/c\+\+.*
- /usr/bin/cpp.*
- /usr/bin/g\+\+.*
```
__Note__: Directories are treated as standard entries, so to include a single file, you need also to explictly include also it's directory. Consider this example to include `/etc/lvm/lvm.conf`:
```yaml
includes:
- /etc$
- /etc/lvm$
- /etc/lvm/lvm.conf
```
### `join`
_since luet>=0.16.0_
_to be deprecated in luet>=0.18.0 in favor of `requires_final_images`_
(optional/required) List of packages which are used to generate a parent image from.
It might be omitted in place of `image` or `requires`, and will generate an image which will be used as source of the package from the final packages in the above list. The new image is used to run eventually the package building process and a new artifact can be generated out of it.
```yaml
join:
- name: "foo"
category: "bar"
version: "1.0"
...
- name: "baz"
category: "bar"
version: "1.0"
```
See [Package concepts](/docs/docs/concepts/packages) for more information on how to represent a package in a Luet tree.
#### Examples
- https://github.com/mocaccinoOS/mocaccino-stage3/blob/278e3637cf65761bf01a22c891135e237e4717ad/packages/system/stage3/build.yaml
### `package_dir`
(optional) A path relative to the build container where to create the package from.
Similarly to `unpack`, changes the building strategy.
```yaml
steps:
- mkdir -p /foo/bar/etc/myapp
- touch /foo/bar/etc/myapp/config
package_dir: /foo/bar
```
### `prelude`
(optional) A list of commands to perform in the build container before building.
```yaml
prelude:
- |
PACKAGE_VERSION=${PACKAGE_VERSION%\+*} && \
git clone https://github.com/mudler/yip && cd yip && git checkout "${PACKAGE_VERSION}" -b build
```
### `requires`
(optional/required) List of packages which it depends on.
A list of packages that the current package depends on in *build time*. It might be omitted in place of `image`, and determines the resolution tree of the package itself. A new image is composed from the packages listed in this section in order to build the package
```yaml
requires:
- name: "foo"
category: "bar"
version: "1.0"
...
- name: "baz"
category: "bar"
version: "1.0"
```
See [Package concepts](/docs/docs/concepts/packages) for more information on how to represent a package in a Luet tree.
### `requires_final_images`
_since luet>=0.17.0_
(optional) A boolean flag which instruct luet to use the final images in the `requires` field.
By setting `requires_final_images: true` in the compilation spec, packages in the `requires` section will be first compiled, and afterwards the final packages are squashed together in a new image that will be used during build.
```yaml
requires:
- name: "foo"
category: "bar"
version: "1.0"
...
- name: "baz"
category: "bar"
version: "1.0"
requires_final_images: true
```
`requires_final_images` replaces the use of `join`, which will be deprecated in luet `>=0.18.0`.
### `step`
(optional) List of commands to perform in the build container.
```yaml
steps:
- |
cd yip && make build-small && mv yip /usr/bin/yip
```
### `unpack`
(optional) Boolean flag. It indicates to use the unpacking strategy while building a package
```yaml
unpack: true
```
It indicates that the package content **is** the whole container content.
## Rutime specs
Runtime specification are denoted in a `definition.yaml` or a `collection.yaml` sibiling file. It identifies the package and the runtime contraints attached to it.
*definition.yaml*:
```yaml
name: "awesome"
version: "0.1"
category: "foo"
requires:
- name: "echo"
version: ">=1.0"
category: "bar"
conflicts:
- name: "foo"
version: "1.0"
provides:
- name: "bar"
version: "<1.0"
```
A `collection.yaml` can be used in place of a `definition.yaml` to identify a **set** of packages that instead shares a common `build.yaml`:
*collection.yaml*:
```yaml
packages:
- name: "awesome"
version: "0.1"
category: "foo"
requires:
- name: "echo"
version: ">=1.0"
category: "bar"
conflicts:
- name: "foo"
version: "1.0"
provides:
- name: "bar"
version: "<1.0"
- name: "awesome"
version: "0.2"
category: "foo"
requires:
- name: "echo"
version: ">=1.0"
category: "bar"
conflicts:
- name: "foo"
version: "1.0"
provides:
- name: "bar"
version: "<1.0"
...
```
All the fields (also the ones which are not part of the spec) in the `definition.yaml` file are available as templating values when rendering the `build.yaml` file. When running [finalizers](/docs/docs/concepts/packages/specfile/#finalizers) instead only the fields belonging to the specs are available.
### Keywords
Here is a list of the full keyword refereces
### `annotations`
(optional) A map of freeform package annotations:
```yaml
annotations:
foo: "bar"
baz: "test"
```
#### `category`
(optional) A string containing the category of the package
```yaml
category: "system"
```
### `conflicts`
(optional) List of packages which it conflicts with in *runtime*. In the same form of `requires` it is a list of packages that the current one is conflicting with.
```yaml
conflicts:
- name: "foo"
category: "bar"
version: "1.0"
...
- name: "baz"
category: "bar"
version: "1.0"
```
See [Package concepts](/docs/docs/concepts/packages) for more information on how to represent a package in a Luet tree.
### `description`
(optional) A string indicating the package description
```yaml
name: "foo"
description: "foo is capable of..."
```
### `hidden`
(optional) A boolean indicating whether the package has to be shown or not in the search results (`luet search...`)
```yaml
hidden: true
```
### `labels`
(optional) A map of freeform package labels:
```yaml
labels:
foo: "bar"
baz: "test"
```
Labels can be used in `luet search` to find packages by labels, e.g.:
```bash
$> luet search --by-label foo
```
### `license`
(optional) A string indicating the package license type.
```yaml
license: "GPL-3"
```
#### `name`
(required) A string containing the name of the package
```yaml
name: "foo"
```
### `provides`
(optional) List of packages which the current package is providing.
```yaml
conflicts:
- name: "foo"
category: "bar"
version: "1.0"
...
- name: "baz"
category: "bar"
version: "1.0"
```
See [Package concepts](/docs/docs/concepts/packages) for more information on how to represent a package in a Luet tree.
### `requires`
(optional) List of packages which it depends on in runtime.
A list of packages that the current package depends on in *runtime*. The determines the resolution tree of the package itself.
```yaml
requires:
- name: "foo"
category: "bar"
version: "1.0"
...
- name: "baz"
category: "bar"
version: "1.0"
```
See [Package concepts](/docs/docs/concepts/packages) for more information on how to represent a package in a Luet tree.
### `uri`
(optional) A list of URI relative to the package ( e.g. the official project pages, wikis, README, etc )
```yaml
uri:
- "http://www.mocaccino.org"
- ...
```
#### `version`
(required) A string containing the version of the package
```yaml
version: "1.0"
```
## Refering to packages from the CLI
All the `luet` commands which takes a package as argument, respect the following syntax notation:
- `cat/name`: will default to selecting any available package
- `=cat/name`: will default to gentoo parsing with regexp so also `=cat/name-1.1` works
- `cat/name@version`: will select the specific version wanted ( e.g. `cat/name@1.1` ) but can also include ranges as well `cat/name@>=1.1`
- `name`: just name, category is omitted and considered empty
## Finalizers
Finalizers are denoted in a `finalize.yaml` file, which is a sibiling of `definition.yaml` and `build.yaml` file. It contains a list of commands that finalize the package when it is installed in the machine.
*finalize.yaml*:
```yaml
install:
- rc-update add docker default
```
### Keywords
- `install`: List of commands to run in the host machine. Failures are eventually ignored, but will be reported and luet will exit non-zero in such case.

95
docs/content/en/docs/Concepts/Packages/templates.md Normal file
View File

@ -0,0 +1,95 @@
---
title: "Templated packages"
linkTitle: "Templated packages"
weight: 3
description: >
Use templates to fine tune build specs
---
Luet supports the [`sprig` rendering engine template, like helm](http://masterminds.github.io/sprig/). It's being used to interpolate `build.yaml` and `finalize.yaml` files before their execution. The following document assumes you are familiar with the `helm` templating.
The `build.yaml` and `finalize.yaml` files are rendered during build time, and it's possible to use the `helm` templating syntax inside such files. The `definition.yaml` file will be used to interpolate templating values available in `build.yaml`
Given the following `definition.yaml`:
```yaml
name: "test"
category: "foo"
version: "1.1"
additional_field: "baz"
```
A `build.yaml` can look like the following, and interpolates it's values during build time:
```yaml
image: ...
steps:
- echo {{.Values.name}} > /package_name
- echo {{.Values.additional_field}} > /extra
```
Which would be for example automatically rendered by luet like the following:
```yaml
image: ...
steps:
- echo test > /package_name
- echo baz > /extra
```
This mechanism can be used in collections as well, and each stanza in `packages` is used to interpolate each single package.
## Interpolating globally
It's possible to interpolate during build phase all the package specs targeted for build with the ```--values``` flag, which takes a yaml file of an arbitrary format, if variables are clashing, the yaml supplied in `--values` takes precedence and overwrite the values of each single `definition.yaml` file.
## Shared templates
Since luet `0.17.5` it is possible to share templates across different packages. All templates blocks found inside the `templates` folder inside the root `luet tree` of a repository gets templated and shared across all the packages while rendering each compilation spec of the given tree.
Consider the following:
```
shared_templates
├── templates
│   └── writefile.yaml
└── test
├── build.yaml
└── collection.yaml
```
#### `collection.yaml`
We define here two packages with a collection. They will share the same compilation spec to generate two different packages
{{<githubembed repo="mudler/luet" file="tests/fixtures/shared_templates/test/collection.yaml" lang="yaml">}}
#### `writefile.yaml`
All the files in the `templates` folder will get rendered by the template for each package in the tree. We define here a simple block to write out a file from the context which is passed by:
{{<githubembed repo="mudler/luet" file="tests/fixtures/shared_templates/templates/writefile.yaml" lang="yaml">}}
#### `build.yaml`
Finally the build spec consumes the template block we declared above, passing by the name of the package:
{{<githubembed repo="mudler/luet" file="tests/fixtures/shared_templates/test/build.yaml" lang="yaml">}}
## Limitations
The `finalize.yaml` file has access only to the package fields during templating. Extra fields that are present in the `definition.yaml` file are *not* accessible during rendering in the `finalize.yaml` file, but only the package fields (`name`, `version`, `labels`, `annotations`, ...)
## References
- [Sprig docs](http://masterminds.github.io/sprig/)
- [Helm Templating functions](https://helm.sh/docs/chart_template_guide/function_list/)
- [Helm Templating variable](https://helm.sh/docs/chart_template_guide/variables/)
## Examples
- https://github.com/mocaccinoOS/mocaccino-musl-universe/tree/master/multi-arch/packages/tar

153
docs/content/en/docs/Concepts/Plugins and Extensions/_index.md Normal file
View File

@ -0,0 +1,153 @@
---
title: "Plugins and Extensions"
linkTitle: "Plugins and Extensions"
weight: 3
description: >
Extend luet with plugins and extensions
---
Luet can be extended in 2 ways by extensions and plugins.
# Before you begin
You need to have a working `luet` binary installed.
## Extensions
Extensions expand Luet featureset horizontally, so for example, “luet geniso” will allow you to build an iso using luet, without this needing to be part of the luet core.
An Extension is nothing more than a standalone executable file, whose name begins with `luet-`. To install an extension, simply move its executable file to anywhere on your system `PATH`.
All the plugins will be accessible to luet as `luet pluginname`
### Writing an Extension
You can write an extension in any programming language or script that allows you to write command-line commands.
Executables receive the inherited environment from luet. An extension determines which command path it wishes to implement based on its name. For example, a plugin wanting to provide a new command luet foo, would simply be named luet-foo, and live somewhere in your PATH.
#### Example Extension
```bash
#!/bin/bash
if [[ "$1" == "help" ]]
then
echo "Extension help"
exit 0
fi
if [[ "$1" == "run" ]]
then
# do something interesting
fi
echo "I am an Extension named luet-foo"
```
### Using an Extension
To use the above extension, simply make it executable:
```bash
$ sudo chmod +x ./luet-foo
```
and place it anywhere in your PATH:
```bash
$ sudo mv ./luet-foo /usr/local/bin
```
You may now invoke your extension as a luet command:
```bash
$ luet foo
I am an Extension named luet-foo
```
All args and flags are passed as-is to the executable:
```bash
$ luet foo help
Extension help
```
## Plugins
Plugins instead are expanding Luet vertically by hooking into internal events. Plugins and Extensions can be written in any language, bash included! Luet uses [go-pluggable](https://github.com/mudler/go-pluggable) so it can dispatch events to external binaries.
Similarly to **Extensions**, a **Plugin** is nothing more than a standalone executable file, but without any special prefix. To install a plugin, simply move its executable file to anywhere on your system `PATH`.
Differently from **Extensions**, they are not available from the **CLI** and cannot be invoked directly by the user, instead they are called by Luet during its lifecycle.
### Writing a Plugin
You can write a plugin in any programming language or script.
The first argument that is passed to a plugin will always be the event that was emitted by Luet in its lifecycle. You can see all the [events available here](https://github.com/mudler/luet/blob/master/pkg/bus/events.go). The second argument, is a `JSON` encoded payload of the object that Luet is emitting with the event. The object(s) may vary depending on the emitted event.
The output of the plugin (`stdout`) will be parsed as JSON. Every plugin must return a valid JSON at the end of its execution, or it will be marked as failed and stops `luet` further execution. [See also the go-pluggable README](https://github.com/mudler/go-pluggable#plugin-processed-data).
The returning payload should be in the following form:
```json
{ "state": "", "data": "data", "error": ""}
```
By returning a json with the error field not empty, it will make fail the overall execution.
#### Example Plugin
```bash
#!/bin/bash
echo "$1" >> /tmp/event.txt
echo "$2" >> /tmp/payload.txt
echo "{}"
```
### Using a plugin
To use the above plugin, simply make it executable:
```bash
$ sudo chmod +x ./test-foo
```
and place it anywhere in your PATH:
```bash
$ sudo mv ./test-foo /usr/local/bin
```
Now, when running luet, add ```--plugin test-foo```:
```bash
$ luet --plugin test-foo install -y foopackage
```
And check `/tmp/event.txt` to see the event fired and `/tmp/payload.txt` to check the payloads that were emitted by Luet.
### Concrete example
A plugin that prints the images that are being built in `/tmp/exec.log`:
```bash
#!/bin/bash
exec >> /tmp/exec.log
exec 2>&1
event="$1"
payload="$2"
if [ "$event" == "image.post.build" ]; then
image=$(echo "$payload" | jq -r .data | jq -r .ImageName )
echo "{ \"data\": \"$image built\" }"
else
echo "{}"
fi
```

7
docs/content/en/docs/Concepts/_index.md Normal file
View File

@ -0,0 +1,7 @@
---
title: "Concepts"
linkTitle: "Concepts"
weight: 2
description: >
Documentation references
---

145
docs/content/en/docs/Getting started/_index.md Normal file
View File

@ -0,0 +1,145 @@
---
title: "Getting Started"
linkTitle: "Getting Started"
weight: 1
description: >
First steps with Luet
---
## Prerequisites
No dependencies. For building packages [see the Build Packages section](/docs/docs/concepts/overview/build_packages/)
## Get Luet
### From release
Just grab a release from [the release page on GitHub](https://github.com/mudler/luet/releases). The binaries are statically compiled.
Or you can install Luet also with a single command:
```bash
curl https://luet.io/install.sh | sudo sh
```
### Building Luet from source
Requirements:
- [Golang](https://golang.org/) installed in your system.
- make
```bash
$> git clone https://github.com/mudler/luet
$> cd luet
$> make build # or just go build
```
## Install it as a system package
In the following section we will see how to install luet with luet itself. We will use a transient luet version that we are going to throw away right after we install it in the system.
```bash
# Get a luet release. It will be used to install luet in your system
wget https://github.com/mudler/luet/releases/download/0.8.3/luet-0.8.3-linux-amd64 -O luet
chmod +x luet
# Creates the luet configuration file and add the luet-index repository.
# The luet-index repository contains a collection of repositories which are
# installable and tracked in your system as standard packages.
cat > .luet.yaml <<EOF
repositories:
- name: "mocaccino-repository-index"
description: "MocaccinoOS Repository index"
type: "http"
enable: true
cached: true
priority: 1
urls:
- "https://raw.githubusercontent.com/mocaccinoOS/repository-index/gh-pages"
EOF
# Install the official luet repository to get always the latest luet version
./luet install repository/luet
# Install luet (with luet) in your system
./luet install system/luet
# Remove the temporary luet used for bootstrapping
rm -rf luet
# Copy over the config file to your system
mkdir -p /etc/luet
mv .luet.yaml /etc/luet/luet.yaml
```
## Configuration
Luet stores its configuration files in `/etc/luet`. If you wish to override its default settings, create a file `/etc/luet/luet.yaml`.
A example of a `luet.yaml` file can be found [here](https://github.com/mudler/luet/blob/master/contrib/config/luet.yaml).
There are a bunch of configuration settings available, but the most relevant are:
```yaml
logging:
color: true # Enable/Disable colored output
enable_emoji: true # Enable/Disable emoji from output
general:
debug: false # Enable/Disable debug
system:
rootfs: "/" # What's our rootfs. Luet can install packages outside of "/"
database_path: "/var/db/luet" # Where to store DB files
database_engine: "boltdb"
tmpdir_base: "/var/tmp/luet" # The temporary directory to be used
```
### Adding repositories
To add repositories, you can either add a `repositories` stanza in your `/etc/luet/luet.yaml` or either add one or more yaml files in `/etc/luet/repos.conf.d/`.
#### Configuration in `/etc/luet/luet.yaml`
```yaml
logging:
color: true # Enable/Disable colored output
enable_emoji: true # Enable/Disable emoji from output
general:
debug: false # Enable/Disable debug
system:
rootfs: "/" # What's our rootfs. Luet can install packages outside of "/"
database_path: "/var/db/luet" # Where to store DB files
database_engine: "boltdb"
tmpdir_base: "/var/tmp/luet" # The temporary directory to be used
repositories:
- name: "some-repository-name" # Repository name
description: "A beautiful description"
type: "http" # Repository type, disk or http are supported (disk for local path)
enable: true # Enable/Disable repo
cached: true # Enable cache for repository
priority: 3 # Cache priority
urls: # Repository URLs
- "...."
```
#### Configuration in `/etc/luet/repos.conf.d/`
A repository file can be for example:
```yaml
name: "..." # Repository name
description: "..."
type: "http" # Repository type, disk or http are supported (disk for local path)
enable: true # Enable/Disable repo
cached: true # Enable cache for repository
priority: 3 # Cache priority
urls: # Repository URLs
- "..."
```
There is available a [collection of repositories](https://packages.mocaccino.org/repository-index), which is containing a list of repositories that can be installed in the system with `luet install`.
If you installed Luet from the curl command, you just need to run `luet search repository` to see a list of all the available repository, and you can install them singularly by running `luet install repository/<name>`. Otherwise, add the repository stanzas you need to `/etc/luet/luet.yaml`.

10
docs/content/en/docs/Resources/_index.md Executable file
View File

@ -0,0 +1,10 @@
---
title: "Resources"
linkTitle: "Resources"
weight: 20
date: 2017-01-05
description: >
Luet examples, resources, API reference
---

66
docs/content/en/docs/Resources/arm.md Normal file
View File

@ -0,0 +1,66 @@
---
title: "ARM images"
linkTitle: "ARM images"
weight: 4
description: >
Use Luet to build, track, and release OTA update for your embedded devices.
---
{{< alert color="warning" title="Warning" >}}
This article is outdated.
Please refer to the ["Hello World"](../../tutorials/hello_world/) tutorial instead.
{{< /alert >}}
Here we show an example on how to build "burnable" SD images for Raspberry Pi with Luet. This approach lets you describe and version OTA upgrades for your embedded devices, delivering upgrades as layer upgrades on the Pi.
The other good side of the medal is that you can build a Luet package repository with multiple distributions (e.g. `Raspbian`, `OpenSUSE`, `Gentoo`, ... ) and switch among them in runtime. In the above example `Raspbian` and `Funtoo` (at the time of writing) are available.
## Prerequisites
You have to run the following steps inside an ARM board to produce arm-compatible binaries. Any distribution with Docker will work. Note that the same steps could be done in a cross-compilation approach, or with qemu-binfmt in a amd64 host.
You will also need in your host:
- Docker
- Luet installed (+container-diff) in `/usr/bin/luet` (arm build)
- make
## Build the packages
Clone the repository https://github.com/Luet-lab/luet-embedded
$> git clone https://github.com/Luet-lab/luet-embedded
$> cd luet-embedded
$> sudo make build-all
...
If a rebuild is needed, just do `sudo make rebuild-all` after applying the changes.
## Create the repository
$> sudo make create-repo
...
## Serve the repo locally
$> make serve-repo
...
## Create the flashable image
### Funtoo based system
$> sudo LUET_PACKAGES='distro/funtoo-1.4 distro/raspbian-boot-0.20191208 system/luet-develop-0.5' make image
...
### Raspbian based system
$> sudo LUET_PACKAGES='distro/raspbian-0.20191208 distro/raspbian-boot-0.20191208 system/luet-develop-0.5' make image
...
At the end of the process, a file `luet_os.img`, ready to be flashed to an SD card, should be present in the current directory.
## Add packages
In order to build and add [packages](/docs/docs/concepts/packages/) to the exiting repository, simply add or edit the [specfiles](/docs/docs/concepts/specfile) under the `distro` folder. When doing ```make rebuild-all``` the packages will be automatically compiled and made available to the local repository.

74
docs/content/en/docs/Resources/building.md Normal file
View File

@ -0,0 +1,74 @@
---
title: "Building"
linkTitle: "Building"
weight: 4
description: >
Examples to build with Luet
---
## Simple package build
Creating and building a simple [package](/docs/docs/concepts/packages/):
```
$> mkdir package
$> cat <<EOF > package/build.yaml
image: busybox
steps:
- echo "foo" > /foo
EOF
$> cat <<EOF > package/definition.yaml
name: "foo"
version: "0.1"
EOF
$> luet build --all
📦 Selecting foo 0.1
📦 Compiling foo version 0.1 .... ☕
🐋 Downloading image luet/cache-foo-bar-0.1-builder
🐋 Downloading image luet/cache-foo-bar-0.1
📦 foo Generating 🐋 definition for builder image from busybox
🐋 Building image luet/cache-foo-bar-0.1-builder
🐋 Building image luet/cache-foo-bar-0.1-builder done
Sending build context to Docker daemon 4.096kB
...
```
### Build packages
In order to build a specific version, a full [package](/docs/docs/concepts/packages/) definition (triple of `category`, `name` and `version`) has to be specified.
In this example we will also enable package compression (gzip).
```
$> mkdir package
$> cat <<EOF > package/build.yaml
image: busybox
steps:
- echo "foo" > /foo
EOF
$> cat <<EOF > package/definition.yaml
name: "foo"
version: "0.1"
category: "bar"
EOF
$> luet build bar/foo-0.1 --compression gzip
📦 Selecting foo 0.1
📦 Compiling foo version 0.1 .... ☕
🐋 Downloading image luet/cache-foo-bar-0.1-builder
🐋 Downloading image luet/cache-foo-bar-0.1
📦 foo Generating 🐋 definition for builder image from busybox
🐋 Building image luet/cache-foo-bar-0.1-builder
🐋 Building image luet/cache-foo-bar-0.1-builder done
Sending build context to Docker daemon 4.096kB
...
```

30
docs/content/en/docs/Resources/faq.md Normal file
View File

@ -0,0 +1,30 @@
---
title: "Frequently Asked Questions"
linkTitle: "FAQ"
weight: 4
description: >
FAQ
---
## Can't build packages
There might be several reasons why packages fails to build, for example, if your build fails like this:
```
$ luet build ...
INFO Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
ERROR Error: Failed compiling development/toolchain-go-0.6: failed building package image: Could not push image: quay.io/mocaccino/micro-toolchain:latest toolchain-go-development-0.6-builder.dockerfile: Could not build image: quay.io/mocaccino/micro-toolchain:latest toolchain-go-development-0.6-builder.dockerfile: Failed running command: : exit status 1
ERROR Bailing out
```
means the user you are running the build command can't either connect to docker or `docker` is not started.
Check if the user you are running the build is in the `docker` group, or if the `docker` daemon is started.
Luet by default if run with multiple packages summarize errors and can be difficult to navigate to logs, but if you think you might have found a bug, run the build with `--debug` before opening an issue.
## Why the name `luet`?
Well, I have the idea that programs should be small, so they are not difficult to type and easy to remember, and easy to stick in. `luet` is really a combination of the first letters of my fiancee name (Lucia) and my name (Ettore) `lu+et = luet`! and besides, happen to be also a [small bridge](http://www.comuniterrae.it/punto/ponte-luet/) in Italy ;)

21
docs/content/en/docs/Resources/references.md Normal file
View File

@ -0,0 +1,21 @@
---
title: "References"
linkTitle: "References"
weight: 100
description: >-
References to various resources related to luet
---
## References
Here is a list of references to projects that are related to Luet (open up a PR to add yours to the list!):
| Description | URL |
|----------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------|
| Official Luet repository | https://github.com/Luet-lab/luet-repo |
| Example repository to host package browser websites on gh-pages. It uses the package-browser extension to generate HTML pages from a list of luet repositories | https://github.com/Luet-lab/package-browser-sample |
| LineageOS builds with luet | https://github.com/mudler/android-builds |
| Example repository template to build packages on github actions and push packages on a container registry | https://github.com/Luet-lab/github-repository |
| Immutable container OS toolkit | https://github.com/rancher-sandbox/cOS-toolkit |
| mocaccinoOS desktop | https://github.com/mocaccinoOS/desktop |
| mocaccinoOS extra | https://github.com/mocaccinoOS/mocaccino-extra |

38
docs/content/en/docs/Resources/scratch.md Normal file
View File

@ -0,0 +1,38 @@
---
title: "Images from scratch"
linkTitle: "ScratchImages"
weight: 4
description: >
Using Luet to compose images from scratch
---
The Docker image `quay.io/luet/base` is a `scratch` Docker image always kept up-to-date with the latest luet version. That image can be used to bootstrap new images with Luet repositories with the packages you want, from the repositories you prefer.
For example we can mount a config file, and later on install a package:
```bash
cat <<EOF > $PWD/luet.yaml
repositories:
- name: "micro-stable"
enable: true
cached: true
priority: 1
type: "http"
urls:
- "https://get.mocaccino.org/mocaccino-micro-stable"
EOF
docker rm luet-runtime-test || true
docker run --name luet-runtime-test \
-ti -v /tmp:/tmp \
-v $PWD/luet.yaml:/etc/luet/luet.yaml:ro \
quay.io/luet/base install shells/bash
docker commit luet-runtime-test luet-runtime-test-image
# Try your new image!
docker run -ti --entrypoint /bin/bash --rm luet-runtime-test-image
```
In this way we will create a new image, with only `luet` and `bash`, and nothing else from a scratch image.

9
docs/content/en/docs/Tutorials/_index.md Executable file
View File

@ -0,0 +1,9 @@
---
title: "Tutorials"
linkTitle: "Tutorials"
weight: 8
date: 2017-01-04
description: >
Howtos, Cookbooks
---

246
docs/content/en/docs/Tutorials/build_package.md Normal file
View File

@ -0,0 +1,246 @@
---
title: "Build a package"
linkTitle: "Build a package"
weight: 3
date: 2017-01-04
description: >
Example on how to build a package and run it locally with luet box
---
{{< alert color="warning" title="Warning" >}}
This article contains references to Luet repositories that were deprecated, and needs to be updated.
Please refer to the ["Hello World"](../../tutorials/hello_world/) tutorial instead.
{{< /alert >}}
![catclock](https://github.com/BarkyTheDog/catclock/raw/master/catclock.gif)
# Catclock example
In this example, we will build the awesome [CatClock](https://github.com/BarkyTheDog/catclock) on containers we will run it locally in a Luet box.
We will do this experiment to prove two things:
1) how we can build a package with Luet and
2) two packages from different distributions can (sometime) work together.
## Prerequisites
To build packages with Luet, you must have installed Docker and container-diff, follow our [setup guide](../../getting-started).
## 1) Create the package
To prove our point, we will build our package from an OpenSUSE image, and later on we will consume
entropy repositories for runtime dependencies. To note, this is not the main focus of Luet, and this is a restricted example on its features on build-time resolution. For more syntax examples, see also [Build specs](../../concepts/specfile/#build-specs) and [Package types](../../concepts/packages/#package-types).
Run this commands in any directory you choose to be your workspace:
```bash
# Let's create a directory to store our package spec:
mkdir -p tree/misc/catclock/
```
### 1.1) Build spec
Now, let's generate our **build** spec:
```bash
# Create a build file. We use here opensuse/leap to build the package, as an example
cat <<EOF > tree/misc/catclock/build.yaml
image: opensuse/leap
# Preparation phase
prelude:
- zypper in -y git make libXt-devel xmh gcc motif-devel libXext-devel libpulse-devel libaubio-devel
- git clone https://github.com/BarkyTheDog/catclock
# Here we define the steps that Luet will follow
steps:
- cd catclock && make DEFINES="-Wno-incompatible-pointer-types"
- mv catclock/xclock /usr/bin/xclock
# (optional) File list that will be included in the final package
# Luet will filter out files that won't match any entry in the list (regex syntax IS supported)
includes:
- /usr/bin/xclock
EOF
```
`build.yaml` is what an ebuild is for Gentoo and for e.g. what PKGBUILD is for Arch.
- *image: opensuse/leap* tells luet to use opensuse/leap as a build image. We collect the build time dependencies with `zypper` (the openSUSE package manager), and the [CatClock](https://github.com/BarkyTheDog/catclock) with `git`. When we declare an `image` keyword in a spec, it becomes a *seed* package ( [Package types](../../concepts/packages/#package-types) ) as doesn't depend on any package in build time, we will cover more use cases in other examples.
- *prelude* is a list of commands that will happen during the build phase.
They might generate binaries, or download sources, but those are not took into consideration when generating the final package.
- *steps* is a list of commands that will happen during the build phase.
Luet will execute those commands and all the binaries generated from them become part of the final package
- *includes* is a (optional) list of regex that tells to Luet what files to filter out from the final artifact.
### 1.2) Runtime spec
Now we generate the runtime spec, it's the part about the binary end which will be installed in the system. It also holds the metadata relative to the package definition (`name`, `category`, `version`).
```bash
# Create a runtime definition.
# We will leverage packages already present on Sabayon Entropy repositories
# the end-system needs to have the Luet Sabayon Entropy repositories enabled.
cat <<EOF > tree/misc/catclock/definition.yaml
category: "misc"
name: "catclock"
version: "0.20200318"
requires:
- category: meta
name: users
version: ">=0"
- category: x11-libs
name: motif
version: ">=0.1"
- category: media-libs
name: libjpeg-turbo
version: ">=0.1"
EOF
```
- *category*, *name*, and *version*: identifies the package in a Luet tree. This is the unique identifier for a package.
- *requires* it's a list of packages which our **catclock** depends on during runtime (when we will execute catclock inside a small-container!). To find out what's required by your binaries it can be a try-learn-fail effort. If the package you wish to build is specifying the deps it requires, and those are available in a Luet repository, you are all set, just point them there. Otherwise you have to figure out after you build the binary the first time (for example, with `ldd`) to which libraries it depends on.
In this example we consume the dependencies from the [Luet Entropy Repo](https://github.com/Luet-lab/luet-entropy-repo), that we will enable on the following steps.
## 2) Build it!
```bash
sudo /usr/bin/luet build \
--tree=$PWD/tree misc/catclock \
--destination $PWD/build \
--compression gzip
sudo chown -R $USER $PWD/build # So later on, we can access to the repository with our user
```
We are building the specs in this step.
- *tree*: is the path where our specs are, in our case it's `tree`.
- *destination*: is the path where our packages will be stored, in our case this is `build`.
- *compression*: is the compression algorithm used to compress the final artifacts
Note, we need *sudo* to keep the permissions properly mapped in the artifact which is produced
this is not always the case. Depends on the package content.
## 3) Create a local repository
We will generate now our repository metadata:
```bash
/usr/bin/luet create-repo --tree "tree" \
--output $PWD/build \
--packages $PWD/build \
--name "test repo" \
--descr "Test Repo" \
--tree-compression gzip \
--meta-compression gzip
```
Creating a repository in Luet is about adding metadata and make our spec tree available to other systems running Luet to intall the package.
- **output**: a path which is where Luet will store the repository metadata.
- **packages**: a path containing the packages that were built during the build step
- **name**: Repository name
- **descr**: Repository description
- **tree-compression**: optional, algorithm to use when compression the tree metadata
- **meta-compression**: optional, algorithm to use when compression the repository metadata
## 4) Let's test it!
Now we are all set. We have the packages compiled, and we are ready to consume them. We don't want to break our host system, and we want to test this from our user.
Let's create a directory, we will try to setup a full running system, and install everything there.
```bash
# Let's create a directory for our "fake" rootfilesystem
# it will be populated with a minimal set of packages needed to run
# our amazing catclock
mkdir -p $PWD/rootfs
```
```bash
# Let's also create a directory to store our config files
mkdir -p $PWD/conf
```
We will generate now a Luet config. The Luet config is used to read where install things from, and in which directory.
It also lists the repositories that are used by the client to retrieve packages remotely.
```bash
# We create here a config file which references the rootfs.
# In this way, luet instead installing packages to your host system, will populate the rootfs
# (note, all the steps are run by a user here, no root required!)
cat <<EOF > conf/luet-dso-local.yaml
system:
rootfs: $PWD/rootfs # our "fake" rootfs that we created before
database_path: "/" # this is where our Luet DB will live
database_engine: "boltdb" # this is the Luet DB engine
repositories:
- name: "main"
type: "disk"
priority: 3
enable: true
urls:
- "$PWD/build" # This is the repository we have created before!
- name: "sabayonlinux.org"
description: "Sabayon Linux Repository"
type: "http"
enable: true
cached: true
priority: 2
urls:
- "https://dispatcher.sabayon.org/sbi/namespace/luet-entropy-repo"
- name: "luet-repo"
description: "Luet Official Repository"
type: "http"
enable: true
cached: true
priority: 1
urls:
- "https://raw.githubusercontent.com/Luet-lab/luet-repo/gh-pages"
EOF
# we have specified an additional repository, one that is luet-entropy-repo (which contains
# the runtime dependencies we specified in our package)
```
```bash
# Let's populate our rootfs with some minimal things: base-gcc, and bash
# meta/users is a meta package providing minimal base to run things with a full
# user-level support.
export LUET_NOLOCK=true
luet install \
--config $PWD/conf/luet-dso-local.yaml \
meta/users
```
```bash
# catclock is a X11 app! we want to be able to play with it locally from our host :)
# Let's copy the .Xauthority file to allow the X app to communicate with our X server
# Note: This can be achieved in other ways (set up a tcp X server, and so on)
cp -rfv $HOME/.Xauthority $PWD/rootfs/
```
```bash
luet install \
--config $PWD/conf/luet-dso-local.yaml \
misc/catclock
```
```bash
# Let's run our beautiful catclock :)
luet box exec --rootfs $PWD/rootfs \
--stdin --stdout --stderr --env DISPLAY=$DISPLAY \
--env XAUTHORITY=/.Xauthority --mount /tmp --entrypoint /usr/bin/xclock
```
Spawn a bash shell inside our box (with permission to access to our running X):
```bash
luet box exec --rootfs $PWD/rootfs \
--stdin --stdout --stderr --env DISPLAY=$DISPLAY \
--env XAUTHORITY=/.Xauthority --mount /tmp --entrypoint /bin/bash
```

147
docs/content/en/docs/Tutorials/hello_world.md Normal file
View File

@ -0,0 +1,147 @@
---
title: "Hello world!"
linkTitle: "Hello world!"
weight: 1
date: 2017-01-04
description: >
Everything starts from an "Hello!"
---
This article will guide you to build your first package with Luet!
For this purpose, we have picked a real-world example: [gogs](https://github.com/gogs/gogs) which is a "painless self-hosted Git service", an open-source alternative to Github.
Gogs is written in Golang, and we need a working Golang version in order to build it.
Here you can see a live recorded session of this tutorial:
<script id="asciicast-388348" src="https://asciinema.org/a/388348.js" data-autoplay="true" data-size="small" data-cols="120" data-rows="40" async></script>
# Define a Luet tree
Everything starts from a Luet tree. A Luet tree is just a directory containing one (or more) Luet specfile, here on we assume that you are working in a dedicated folder (e.g. `~/demo`) in your system.
Let's create then a package that will be our base to build other packages from now on, we have picked `busybox` here - it is really small and enough for our purpose.
## busybox
```bash
mkdir busybox
```
Let's now write the build specification, which is just containing the image tag that we are referencing to
```bash
cat <<EOF > busybox/build.yaml
image: "busybox:{{.Values.version}}-glibc"
EOF
```
Now, lets write the `definition.yaml`, which contains the metadata information about our package ( e.g. how we refer to it with luet, the version, and so on )
```bash
cat <<EOF > busybox/definition.yaml
category: "distro"
name: "busybox"
version: "1.33.0"
EOF
```
## golang
We need now golang in order to build `gogs`. Let's declare then a golang package:
```bash
mkdir golang
```
And a build specfile, which is simply fetch golang from https://golang.org and installing it in the busybox container:
```bash
cat <<EOF > golang/build.yaml
requires:
- category: "distro"
name: "busybox"
version: ">=0"
prelude:
- wget https://golang.org/dl/go{{.Values.version}}.linux-{{.Values.arch}}.tar.gz -O golang.tar.gz
- mkdir /usr/local
steps:
- tar -C /usr/local -xzf golang.tar.gz
EOF
```
Note how we `require` busybox. The Golang container will now be based from busybox, and the `prelude` and `steps` fields will be executed in that context.
And finally let's write the golang metadata files, so we can refer to it from other packages
```bash
cat <<EOF > golang/definition.yaml
name: "go"
category: "dev-lang"
version: "1.15.6"
arch: "amd64"
EOF
```
## gogs
Finally we can write the gogs package definition!
```bash
mkdir gogs
```
The build specfile, will just fetch the `gogs` sources at a given version (specified in the `definition.yaml`) and build the sources with go:
```bash
cat <<'EOF' > gogs/build.yaml
requires:
- category: "dev-lang"
name: "go"
version: ">=0"
env:
- GOPATH="/go"
- GOGSPATH="$GOPATH/src/github.com/gogs/gogs"
- PATH=$PATH:/usr/local/go/bin
- CGO_ENABLED=0
prelude:
- mkdir -p $GOPATH/src/github.com/gogs
- wget https://github.com/gogs/gogs/archive/v{{.Values.version}}.tar.gz -O - | tar -xzf - -C ./ && mv gogs-{{.Values.version}} $GOGSPATH
steps:
- mkdir /usr/bin
- cd $GOGSPATH && go build && mv gogs /usr/bin/gogs
excludes:
# Cache generated by Golang
- ^/root
EOF
```
And the metadata, in this way we can refer to gogs in a Luet tree:
```bash
cat <<EOF > gogs/definition.yaml
category: "dev-vcs"
name: "gogs"
version: "0.11.91"
EOF
```
# Build packages
The simplest and mostly immediate way to build packages, is running `luet build <packagename>` in the same folder you have your Luet tree.
In this case, to build gogs and its deps, we can do:
```bash
luet build dev-vcs/gogs
```
And that's it! you will find the package archives in `build/` in the same folder where you started the command.
You will see that Luet generates not only archives with the file resulting to your builds, but it will also generate metadata files (ending with `.metadata.yaml`) that contains additional metadata information about your build and the package itself (e.g. checksums).
You can use tools like [yq](https://github.com/mikefarah/yq) to inspect those:
```bash
yq r build/gogs-dev-vcs-0.11.91.metadata.yaml checksums
```
Now if you want to consume the artifacts just built with `luet install`, you can create a repository with `luet create-repo`.

18
docs/content/en/docs/_index.md Executable file
View File

@ -0,0 +1,18 @@
---
title: "Documentation"
linkTitle: "Documentation"
weight: 20
menu:
main:
weight: 20
---
Luet is a Package Manager based on containers. It provides an abstraction layer over container specfile format, enhancing the image resolution process of open container inititative ([OCI](https://en.wikipedia.org/wiki/Open_Container_Initiative)) runtimes with boolean satisfiability problem ([SAT](https://en.wikipedia.org/wiki/Boolean_satisfiability_problem)) solving techniques.
Luet can be used to build [packages](/docs/docs/concepts/packages/), container images, as well as to manage and distribute installations of derived [packages](/docs/docs/concepts/packages/) locally.
Allows to apply semver [constraints](/docs/docs/concepts/overview/constraints/) to Image dependencies, treating it as a classical [CSP](https://en.wikipedia.org/wiki/Constraint_satisfaction_problem).
<script id="asciicast-388348" src="https://asciinema.org/a/388348.js" data-autoplay="true" data-size="small" data-cols="90" data-rows="30" async></script>

57
docs/content/en/docs/contribution-guidelines.md Normal file
View File

@ -0,0 +1,57 @@
---
title: "Contributing"
linkTitle: "Contribution guidelines"
weight: 159
---
## Contributing to Luet
Contribution guidelines for the Luet project are on the [Github repository](https://github.com/mudler/luet/blob/master/CONTRIBUTING.md). Here you can find some heads up for contributing to the documentation website.
## Contributing to the Docs website
### We Develop with Github
We use [github to host code](https://github.com/Luet-lab/docs), to track issues and feature requests, as well as accept pull requests.
We use [Hugo](https://gohugo.io/) to format and generate our website, the
[Docsy](https://github.com/google/docsy) theme for styling and site structure,
and Github Actions to manage the deployment of the site.
Hugo is an open-source static site generator that provides us with templates,
content organisation in a standard directory structure, and a website generation
engine. You write the pages in Markdown (or HTML if you want), and Hugo wraps them up into a website.
All submissions, including submissions by project members, require review. We
use GitHub pull requests for this purpose. Consult
[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
information on using pull requests.
### Any contributions you make will be under the Software License of the repository
In short, when you submit code changes, your submissions are understood to be under the same License that covers the project. Feel free to contact the maintainers if that's a concern.
### Updating a single page
If you've just spotted something you'd like to change while using the docs, Docsy has a shortcut for you:
1. Click **Edit this page** in the top right hand corner of the page you want to modify.
2. If you don't already have an up to date fork of the project repo, you are prompted to get one - click **Fork this repository and propose changes** or **Update your Fork** to get an up to date version of the project to edit. The appropriate page in your fork is displayed in edit mode.
### Quick start with a local checkout
Here's a quick guide to updating the docs with a git local checkout. It assumes you're familiar with the
GitHub workflow and you're happy to use the automated preview of your doc
updates:
1. Fork the [the Docs repo](https://github.com/Luet-lab/docs) on GitHub.
2. Make your changes, to see the preview run `make serve` and browse to `localhost:1313`
3. If you're not yet ready for a review, add "WIP" to the PR name to indicate
it's a work in progress.
4. Continue updating your doc and pushing your changes until you're happy with
the content.
5. When you're ready for a review, add a comment to the PR, and remove any
"WIP" markers.
6. When you are satisfied send a pull request (PR).
### License
By contributing, you agree that your contributions will be licensed under the project Licenses.

BIN
docs/content/en/featured-background.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 284 KiB

4
docs/content/en/search-index.md Normal file
View File

@ -0,0 +1,4 @@
---
type: "search-index"
url: "index.json"
---

6
docs/content/en/search.md Normal file
View File

@ -0,0 +1,6 @@
---
title: Search Results
layout: search
---

10
docs/layouts/404.html Normal file
View File

@ -0,0 +1,10 @@
{{ define "main"}}
<main id="main">
<div>
<h1 id="title">Not found</h1>
<p>Oops! This page doesn't exist. Try going back to our <a href="{{ "/" | relURL }}">home page</a>.</p>
<p>You can learn how to make a 404 page like this in <a href="https://gohugo.io/templates/404/">Custom 404 Pages</a>.</p>
</div>
</main>
{{ end }}

9
docs/layouts/shortcodes/githubembed.html Normal file
View File

@ -0,0 +1,9 @@
{{/* https://github.com/haideralipunjabi/hugo-shortcodes/tree/master/github */}}
{{ $dataJ := getJSON "https://api.github.com/repos/" (.Get "repo") "/contents/" (.Get "file") }}
{{ $con := base64Decode $dataJ.content }}
{{ highlight $con (.Get "lang") (.Get "options") }}
<small> <i class='fab fa-github'></i> <i>Complete source code: <a target=_blank href="{{ print "https://github.com/" ( .Get "repo" ) "/blob/master/" (.Get "file" ) }}">{{ print "https://github.com/" ( .Get "repo" ) "/blob/master/" (.Get "file" ) }}</a></i> </small>
<hr>

30
docs/scripts/build.sh Executable file
View File

@ -0,0 +1,30 @@
#!/bin/bash
set -e
BASE_URL="${BASE_URL:-https://luet.io}"
binpath="${ROOT_DIR}/bin"
publicpath="${ROOT_DIR}/public"
if [ ! -e "${binpath}/hugo" ];
then
[[ ! -d "${binpath}" ]] && mkdir -p "${binpath}"
wget https://github.com/gohugoio/hugo/releases/download/v"${HUGO_VERSION}"/hugo_extended_"${HUGO_VERSION}"_"${HUGO_PLATFORM}".tar.gz -O "$binpath"/hugo.tar.gz
tar -xvf "$binpath"/hugo.tar.gz -C "${binpath}"
rm -rf "$binpath"/hugo.tar.gz
chmod +x "$binpath"/hugo
fi
rm -rf "${publicpath}" || true
[[ ! -d "${publicpath}" ]] && mkdir -p "${publicpath}"
# Note: It needs
# sudo npm install -g postcss-cli
#
npm install -D --save autoprefixer
npm install -D --save postcss-cli
HUGO_ENV="production" "${binpath}/hugo" --gc -b "${BASE_URL}" -d "${publicpath}"
cp -rf CNAME $publicpath

14
docs/scripts/publish.sh Executable file
View File

@ -0,0 +1,14 @@
#!/bin/bash
set -e
"${ROOT_DIR}"/scripts/build.sh
git branch -D gh-pages || true
git checkout --orphan gh-pages
git rm -rf .
cp -rfv public/* ./
rm -rf public/

14
docs/scripts/serve.sh Executable file
View File

@ -0,0 +1,14 @@
#!/bin/bash
set -e
binpath="${ROOT_DIR}/bin"
if [ ! -e "${binpath}/hugo" ];
then
[[ ! -d "${binpath}" ]] && mkdir -p "${binpath}"
wget https://github.com/gohugoio/hugo/releases/download/v"${HUGO_VERSION}"/hugo_extended_"${HUGO_VERSION}"_"${HUGO_PLATFORM}".tar.gz -O "$binpath"/hugo.tar.gz
tar -xvf "$binpath"/hugo.tar.gz -C "${binpath}"
rm -rf "$binpath"/hugo.tar.gz
chmod +x "$binpath"/hugo
fi
"${binpath}/hugo" --baseURL="$BASE_URL" -s "$ROOT_DIR" serve

67
docs/static/install.sh vendored Normal file
View File

@ -0,0 +1,67 @@
#!/bin/bash
if [ $(id -u) -ne 0 ]
then echo "Please run the installer with sudo/as root"
exit
fi
set -ex
export LUET_NOLOCK=true
LUET_VERSION=${LUET_VERSION:-0.22.7}
LUET_ROOTFS=${LUET_ROOTFS:-/}
LUET_DATABASE_PATH=${LUET_DATABASE_PATH:-/var/luet/db}
LUET_DATABASE_ENGINE=${LUET_DATABASE_ENGINE:-boltdb}
LUET_CONFIG_PROTECT=${LUET_CONFIG_PROTECT:-1}
if [ -z "$LUET_ARCH" ]; then
LUET_ARCH=$(uname -m)
fi
case $LUET_ARCH in
amd64|x86_64)
LUET_ARCH=amd64
;;
arm64|aarch64|arm*)
LUET_ARCH=armv7
;;
esac
curl -L https://github.com/mudler/luet/releases/download/${LUET_VERSION}/luet-${LUET_VERSION}-linux-${LUET_ARCH} --output luet
chmod +x luet
mkdir -p /etc/luet/repos.conf.d || true
mkdir -p $LUET_DATABASE_PATH || true
mkdir -p /var/tmp/luet || true
if [ "${LUET_CONFIG_PROTECT}" = "1" ] ; then
mkdir -p /etc/luet/config.protect.d || true
curl -L https://raw.githubusercontent.com/mudler/luet/master/contrib/config/config.protect.d/01_etc.yml.example --output /etc/luet/config.protect.d/01_etc.yml
fi
curl -L https://raw.githubusercontent.com/mocaccinoOS/repository-index/master/packages/mocaccino-repository-index.yml --output /etc/luet/repos.conf.d/mocaccino-repository-index.yml
cat > /etc/luet/luet.yaml <<EOF
general:
debug: false
system:
rootfs: ${LUET_ROOTFS}
database_path: "${LUET_DATABASE_PATH}"
database_engine: "${LUET_DATABASE_ENGINE}"
tmpdir_base: "/var/tmp/luet"
EOF
./luet install -y repository/luet repository/mocaccino-repository-index
case $LUET_ARCH in
amd64|x86_64)
./luet install -y system/luet
;;
arm64|aarch64|arm*)
./luet install -y system/luet-arm
;;
esac
if [ ! -e "/usr/bin/luet" ]; then
cp -rf luet /usr/bin/luet
fi
rm -rf luet

BIN
docs/static/tree.jpg vendored Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 31 KiB

1
docs/themes/docsy vendored Submodule

@ -0,0 +1 @@
Subproject commit 033225e5174d50828c565b66d992c7b5d55ba42a