lxc/distrobuilder
1
0
Fork 0
mirror of https://github.com/lxc/distrobuilder.git synced 2026-02-05 06:45:19 +01:00
Code Issues Releases Activity

doc: basic Sphinx setup

Browse Source 
Signed-off-by: Ruth Fuchss <ruth.fuchss@canonical.com>
This commit is contained in:
Ruth Fuchss
2023-02-15 15:54:59 +01:00
parent 8c697272c9
commit 664d32d319
23 changed files with 2167 additions and 234 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
.gitignore vendored Normal file
View File

@@ -0,0 +1,8 @@
# Sphinx
doc/html/
.sphinx/deps/
.sphinx/themes/
.sphinx/venv/
.sphinx/warnings.txt
.sphinx/.wordlist.dic
.sphinx/_static/download

29
.sphinx/.markdownlint/doc-lint.sh Executable file
View File

@@ -0,0 +1,29 @@
#!/bin/sh -eu
if ! command -v mdl >/dev/null; then
echo "Install mdl with 'snap install mdl' first."
exit 1
fi
trap "rm -rf .tmp/" EXIT
## Preprocessing
for fn in $(find doc/ -name '*.md'); do
mkdir -p $(dirname ".tmp/$fn");
sed -E "s/(\(.+\)=)/\1\n/" $fn > .tmp/$fn;
done
mdl .tmp/doc -s.sphinx/.markdownlint/style.rb -u.sphinx/.markdownlint/rules.rb --ignore-front-matter > .tmp/errors.txt || true
## Postprocessing
filtered_errors="$(grep -vxFf .sphinx/.markdownlint/exceptions.txt .tmp/errors.txt)"
if [ "$(echo "$filtered_errors" | wc -l)" = "2" ]; then
echo "Passed!"
exit 0
else
echo "Failed!"
echo "$filtered_errors"
exit 1
fi

0
.sphinx/.markdownlint/exceptions.txt Normal file
View File

44
.sphinx/.markdownlint/rules.rb Normal file
View File

@@ -0,0 +1,44 @@
rule 'Myst-MD031', 'Fenced code blocks should be surrounded by blank lines' do
tags :code, :blank_lines
aliases 'blanks-around-fences'
check do |doc|
errors = []
# Some parsers (including kramdown) have trouble detecting fenced code
# blocks without surrounding whitespace, so examine the lines directly.
in_code = false
fence = nil
lines = [''] + doc.lines + ['']
lines.each_with_index do |line, linenum|
line.strip.match(/^(`{3,}|~{3,})/)
unless Regexp.last_match(1) &&
(
!in_code ||
(Regexp.last_match(1).slice(0, fence.length) == fence)
)
next
end
fence = in_code ? nil : Regexp.last_match(1)
in_code = !in_code
if (in_code && !(lines[linenum - 1].empty? || lines[linenum - 1].match(/^[:\-\*]*\s*\% /))) ||
(!in_code && !(lines[linenum + 1].empty? || lines[linenum + 1].match(/^\s*:/)))
errors << linenum
end
end
errors
end
end
rule 'Myst-IDs', 'MyST IDs should be preceded by a blank line' do
check do |doc|
errors = []
ids = doc.matching_text_element_lines(/^\(.+\)=\s*$/)
ids.each do |linenum|
if (linenum > 1) && !doc.lines[linenum - 2].empty?
errors << linenum
end
end
errors.sort
end
end

12
.sphinx/.markdownlint/style.rb Normal file
View File

@@ -0,0 +1,12 @@
all
exclude_rule 'MD013'
exclude_rule 'MD046'
exclude_rule 'MD041'
exclude_rule 'MD040'
exclude_rule 'MD024'
exclude_rule 'MD033'
exclude_rule 'MD022'
exclude_rule 'MD031'
rule 'MD026', :punctuation => '.,;:!'
rule 'MD003', :style => :atx
rule 'MD007', :indent => 3

24
.sphinx/.spellcheck.yaml Normal file
View File

@@ -0,0 +1,24 @@
matrix:
- name: Markdown files
aspell:
lang: en
d: en_US
dictionary:
wordlists:
- .sphinx/wordlist.txt
output: .sphinx/.wordlist.dic
sources:
- doc/html/**/*.html
pipeline:
- pyspelling.filters.html:
comments: false
attributes:
- title
- alt
ignores:
- code
- pre
- spellexception
- link
- title
- div.relatedlinks

6
.sphinx/_extra/versions.json Normal file
View File

@@ -0,0 +1,6 @@
[
{
"version": "latest",
"id": "latest"
}
]

170
.sphinx/_static/custom.css Normal file
View File

@@ -0,0 +1,170 @@
/** Fix the font weight (300 for normal, 400 for slightly bold) **/
div.page, h1, h2, h3, h4, h5, h6, .sidebar-tree .current-page>.reference, button, input, optgroup, select, textarea, th.head {
font-weight: 300
}
.toc-tree li.scroll-current>.reference, dl.glossary dt, dl.simple dt, dl:not([class]) dt {
font-weight: 400;
}
/** Table styling **/
th.head {
text-transform: uppercase;
font-size: var(--font-size--small);
}
table.docutils {
border: 0;
box-shadow: none;
width:100%;
}
table.docutils td, table.docutils th, table.docutils td:last-child, table.docutils th:last-child, table.docutils td:first-child, table.docutils th:first-child {
border-right: none;
border-left: none;
}
/* center align table cells with ":-:" */
td.text-center {
text-align: center;
}
/** No rounded corners **/
.admonition, code.literal, .sphinx-tabs-tab, .sphinx-tabs-panel, .highlight {
border-radius: 0;
}
/** Admonition styling **/
.admonition {
border-top: 1px solid #d9d9d9;
border-right: 1px solid #d9d9d9;
border-bottom: 1px solid #d9d9d9;
}
/** Color for the "copy link" symbol next to headings **/
a.headerlink {
color: var(--color-brand-primary);
}
/** Line to the left of the current navigation entry **/
.sidebar-tree li.current-page {
border-left: 2px solid var(--color-brand-primary);
}
/** Some tweaks for issue #16 **/
[role="tablist"] {
border-bottom: 1px solid var(--color-sidebar-item-background--hover);
}
.sphinx-tabs-tab[aria-selected="true"] {
border: 0;
border-bottom: 2px solid var(--color-brand-primary);
background-color: var(--color-sidebar-item-background--current);
font-weight:300;
}
.sphinx-tabs-tab{
color: var(--color-brand-primary);
font-weight:300;
}
.sphinx-tabs-panel {
border: 0;
border-bottom: 1px solid var(--color-sidebar-item-background--hover);
background: var(--color-background-primary);
}
button.sphinx-tabs-tab:hover {
background-color: var(--color-sidebar-item-background--hover);
}
/** Custom classes to fix scrolling in tables by decreasing the
font size or breaking certain columns.
Specify the classes in the Markdown file with, for example:
```{rst-class} break-col-4 min-width-4-8
```
**/
table.dec-font-size {
font-size: smaller;
}
table.break-col-1 td.text-left:first-child {
word-break: break-word;
}
table.break-col-4 td.text-left:nth-child(4) {
word-break: break-word;
}
table.min-width-1-15 td.text-left:first-child {
min-width: 15em;
}
table.min-width-4-8 td.text-left:nth-child(4) {
min-width: 8em;
}
/** Underline for abbreviations **/
abbr[title] {
text-decoration: underline solid #cdcdcd;
}
/** Use the same style for right-details as for left-details **/
.bottom-of-page .right-details {
font-size: var(--font-size--small);
display: block;
}
/** Version switcher */
button.version_select {
color: var(--color-foreground-primary);
background-color: var(--color-toc-background);
padding: 5px 10px;
border: none;
}
.version_select:hover, .version_select:focus {
background-color: var(--color-sidebar-item-background--hover);
}
.version_dropdown {
position: relative;
display: inline-block;
text-align: right;
font-size: var(--sidebar-item-font-size);
}
.available_versions {
display: none;
position: absolute;
right: 0px;
background-color: var(--color-toc-background);
box-shadow: 0px 8px 16px 0px rgba(0,0,0,0.2);
z-index: 11;
}
.available_versions a {
color: var(--color-foreground-primary);
padding: 12px 16px;
text-decoration: none;
display: block;
}
.available_versions a:hover {background-color: var(--color-sidebar-item-background--current)}
.show {display:block;}
/** Fix for nested numbered list - the nested list is lettered **/
ol.arabic ol.arabic {
list-style: lower-alpha;
}
/** Make expandable sections look like links **/
details summary {
color: var(--color-link);
}

10
.sphinx/_static/header-nav.js Normal file
View File

@@ -0,0 +1,10 @@
$(document).ready(function() {
$(document).on("click", function () {
$(".more-links-dropdown").hide();
});
$('.nav-more-links').click(function(event) {
$('.more-links-dropdown').toggle();
event.stopPropagation();
});
})

126
.sphinx/_static/version-switcher.js Normal file
View File

@@ -0,0 +1,126 @@
/* JavaScript for the _templates/variant-selector.html file, implementing
* the version switcher for the documentation.
*
* The script gets available versions from the versions.json file on the
* master branch (because the master branch contains the current information
* on which versions we want to display).
* It then links to other versions of the documentation - to the same page
* if the page is available or to the index otherwise.
*/
// Link to the versions.json file on the master branch.
var versionURL = "https://linuxcontainers.org/distrobuilder/docs/master/versions.json";
// URL prefix that is common for the different documentation sets.
var URLprefix = "https://linuxcontainers.org/distrobuilder/docs/"
$(document).ready(function()
{
// Read the versions.json file and call the listVersions function.
var xhr = new XMLHttpRequest();
xhr.onreadystatechange = function () {
if (xhr.readyState === 4) {
if (xhr.status === 200) {
listVersions(JSON.parse(xhr.responseText));
}
else {
console.log("URL "+versionURL+" cannot be loaded.");
}
}
};
xhr.open('GET', versionURL, true);
xhr.send();
});
// Retrieve the name of the current documentation set (for example,
// 'master' or 'stable-5.0') and the path to the page (for example,
// 'howto/pagename/').
function getPaths()
{
var paths = {};
var prefix = new URL(URLprefix);
var url = window.location.pathname;
if (url.startsWith(prefix.pathname)) {
path = url.substr(prefix.pathname.length).split("/");
paths['current'] = path.shift();
if (paths['current'] == "master") {
paths['current'] = "latest";
};
paths['page'] = path.join("/");
}
else {
console.log("Unexpected hosting URL!");
}
return paths;
}
// Populate the version dropdown.
function listVersions(data)
{
paths = getPaths();
var all_versions = document.getElementById("all-versions");
var current = document.getElementById("current");
for( var i = 0; i < data.length; i++ )
{
var one = data[i];
if (one.id === paths['current']) {
// Put the current version at the top without link.
current.innerText = one.version+" ⌄";
}
else {
// Put other versions into the dropdown and link them to the
// suitable URL.
var version = document.createElement("a");
version.appendChild(document.createTextNode(one.version));
version.href = findNewURL(paths,one.id);
all_versions.appendChild(version);
}
}
}
// Check if the same page exists in the other documentation set.
// If yes, return the new link. Otherwise, link to the index page of
// the other documentation set.
function findNewURL(paths,newset) {
var newURL = URLprefix.concat(newset,"/",paths['page']);
var xhr = new XMLHttpRequest();
xhr.open('HEAD', newURL, false);
xhr.send();
if (xhr.status == "404") {
return URLprefix.concat(newset,"/");
} else {
return newURL;
}
}
// Toggle the version dropdown.
function dropdown() {
document.getElementById("all-versions").classList.toggle("show");
}
// Close the dropdown menu if the user clicks outside of it.
window.onclick = function(event) {
if (!event.target.matches('.version_select')) {
var dropdowns = document.getElementsByClassName("available_versions");
var i;
for (i = 0; i < dropdowns.length; i++) {
var openDropdown = dropdowns[i];
if (openDropdown.classList.contains('show')) {
openDropdown.classList.remove('show');
}
}
}
}

75
.sphinx/_templates/footer.html Normal file
View File

@@ -0,0 +1,75 @@
{# ru-fu: copied from Furo, with modifications as stated below #}
<div class="related-pages">
{% if next -%}
<a class="next-page" href="{{ next.link }}">
<div class="page-info">
<div class="context">
<span>{{ _("Next") }}</span>
</div>
<div class="title">{{ next.title }}</div>
</div>
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
</a>
{%- endif %}
{% if prev -%}
<a class="prev-page" href="{{ prev.link }}">
<svg class="furo-related-icon"><use href="#svg-arrow-right"></use></svg>
<div class="page-info">
<div class="context">
<span>{{ _("Previous") }}</span>
</div>
{% if prev.link == pathto(master_doc) %}
<div class="title">{{ _("Home") }}</div>
{% else %}
<div class="title">{{ prev.title }}</div>
{% endif %}
</div>
</a>
{%- endif %}
</div>
<div class="bottom-of-page">
<div class="left-details">
{%- if show_copyright %}
<div class="copyright">
{%- if hasdoc('copyright') %}
{% trans path=pathto('copyright'), copyright=copyright|e -%}
<a href="{{ path }}">Copyright</a> &#169; {{ copyright }}
{%- endtrans %}
{%- else %}
{% trans copyright=copyright|e -%}
Copyright &#169; {{ copyright }}
{%- endtrans %}
{%- endif %}
</div>
{%- endif %}
{# ru-fu: removed "Made with" #}
{%- if last_updated -%}
<div class="last-updated">
{% trans last_updated=last_updated|e -%}
Last updated on {{ last_updated }}
{%- endtrans -%}
</div>
{%- endif %}
</div>
<div class="right-details">
{# ru-fu: replaced RTD icons with our links #}
{%- if show_source and has_source and sourcename %}
<div class="show-source">
<a class="muted-link" href="{{ pathto('_sources/' + sourcename, true)|e }}"
rel="nofollow">Show source</a>
</div>
{%- endif %}
{% if github_url and github_version and github_folder and github_filetype %}
<div class="edit-github">
<a class="muted-link" href="{{ github_url }}/edit/{{ github_version }}{{ github_folder }}{{ pagename }}.{{ github_filetype }}">Edit on GitHub</a>
</div>
{% endif %}
</div>
</div>
</div>

183
.sphinx/_templates/header.html Normal file
View File

@@ -0,0 +1,183 @@
<header id="header" class="p-navigation">
<style>
.p-navigation {
border-bottom: 1px solid var(--color-sidebar-background-border);
}
.p-navigation__nav {
display: flex;
}
ul.p-navigation__links {
display: flex;
list-style: none;
margin-left: 0;
margin-top: auto;
margin-bottom: auto;
max-width: 800px;
width: 100%;
}
ul.p-navigation__links li {
margin: 0 auto;
text-align: center;
width: 100%;
}
ul.p-navigation__links li a {
background-color: rgba(0, 0, 0, 0);
border: none;
border-radius: 0;
color: var(--color-sidebar-link-text);
display: block;
font-weight: 400;
line-height: 1.5rem;
margin: 0;
overflow: hidden;
padding: 1rem 0;
position: relative;
text-align: left;
text-overflow: ellipsis;
transition-duration: .1s;
transition-property: background-color, color, opacity;
transition-timing-function: cubic-bezier(0.215, 0.61, 0.355, 1);
white-space: nowrap;
width: 100%;
}
ul.p-navigation__links .p-navigation__link,
ul.p-navigation__links .p-navigation__logo {
text-align: center;
}
ul.p-navigation__links .p-navigation__link:hover,
ul.p-navigation__links .p-dropdown__link:hover {
background-color: var(--color-sidebar-item-background--hover);
}
ul.p-navigation__links .p-navigation__sub-link {
background: var(--color-background-primary);
padding: .5rem 0 .5rem .5rem;
font-weight: 300;
}
ul.p-navigation__links .more-links-dropdown li a {
border-left: 1px solid var(--color-sidebar-background-border);
border-right: 1px solid var(--color-sidebar-background-border);
}
ul.p-navigation__links .more-links-dropdown li:first-child a {
border-top: 1px solid var(--color-sidebar-background-border);
}
ul.p-navigation__links .more-links-dropdown li:last-child a {
border-bottom: 1px solid var(--color-sidebar-background-border);
}
ul.p-navigation__links .p-navigation__logo {
padding: 0.5rem;
}
ul.p-navigation__links .p-navigation__logo img {
width: 40px;
}
ul.more-links-dropdown {
display: none;
overflow-x: visible;
height: 0;
z-index: 55;
padding: 0;
position: relative;
list-style: none;
margin-bottom: 0;
margin-top: 0;
}
ul.p-navigation__links li:first-child {
width: 130px;
}
@media only screen and (min-width: 800px) {
.nav-more-links::after {
background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16'%3E%3Cpath fill='%23111' d='M8.187 11.748l6.187-6.187-1.06-1.061-5.127 5.127L3.061 4.5 2 5.561z'/%3E%3C/svg%3E");
background-position: center;
background-repeat: no-repeat;
background-size: contain;
content: "";
display: block;
height: 1rem;
pointer-events: none;
position: absolute;
right: 1rem;
text-indent: calc(100% + 10rem);
top: calc(1rem + 0.25rem);
width: 1rem;
}
body[data-theme=dark] .nav-more-links::after {
background-image: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' width='16' height='16'><path stroke='white' fill='white' d='M8.187 11.748l6.187-6.187-1.06-1.061-5.127 5.127L3.061 4.5 2 5.561z'/></svg>");
}
ul.p-navigation__links li:first-child {
width: 100%;
}
}
@media only screen and (min-width: 1310px) {
ul.p-navigation__links {
margin-left: calc(50% - 41em);
}
}
</style>
<div class="p-navigation__nav" role="menubar">
<ul class="p-navigation__links" role="menu">
<li>
<a class="p-navigation__logo" href="/">
<img src="{{ pathto('_static/download/containers.small.png', 1) }}" alt="Linux containers logo" border="0" />
</a>
</li>
<li>
<a href="/" class="p-navigation__link">Home</a>
</li>
<li>
<a href="/distrobuilder/introduction/" class="p-navigation__link">distrobuilder</a>
</li>
<li>
<a href="#" class="p-navigation__link nav-more-links">More resources</a>
<ul class="more-links-dropdown">
<li>
<a href="/distrobuilder/news/" class="p-navigation__sub-link p-dropdown__link">News</a>
</li>
<li>
<a href="/distrobuilder/contribute/" class="p-navigation__sub-link is-selected p-dropdown__link">Contribute</a>
</li>
<li>
<a href="/distrobuilder/downloads/" class="p-navigation__sub-link p-dropdown__link">Downloads</a>
</li>
<li>
<a href="https://discuss.linuxcontainers.org" class="p-navigation__sub-link p-dropdown__link">Forum</a>
</li>
<li>
<a href="https://github.com/lxc/distrobuilder" class="p-navigation__sub-link p-dropdown__link">GitHub</a>
</li>
</ul>
</li>
</ul>
</div>
</header>

49
.sphinx/_templates/page.html Normal file
View File

@@ -0,0 +1,49 @@
{% extends "furo/page.html" %}
{% block footer %}
{% include "footer.html" %}
{% endblock footer %}
{% block body -%}
{% include "header.html" %}
{{ super() }}
{%- endblock body %}
{% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %}
{% set furo_hide_toc_orig = furo_hide_toc %}
{% set furo_hide_toc=false %}
{% endif %}
{% block right_sidebar %}
<div class="toc-sticky toc-scroll">
{% if not furo_hide_toc_orig %}
<div class="toc-title-container">
<span class="toc-title">
{{ _("Contents") }}
</span>
</div>
<div class="toc-tree-container">
<div class="toc-tree">
{{ toc }}
</div>
</div>
{% endif %}
{% if meta and ((meta.discourse and discourse_prefix) or meta.relatedlinks) %}
<div class="relatedlinks-title-container">
<span class="relatedlinks-title">
Related links
</span>
</div>
<div class="relatedlinks-container">
<div class="relatedlinks">
{% if meta.discourse and discourse_prefix %}
{{ discourse_links(meta.discourse) }}
{% endif %}
{% if meta.relatedlinks %}
{{ related_links(meta.relatedlinks) }}
{% endif %}
</div>
</div>
{% endif %}
</div>
{% endblock right_sidebar %}

4
.sphinx/_templates/sidebar/variant-selector.html Normal file
View File

@@ -0,0 +1,4 @@
<div class="version_dropdown">
Doc version: <button onclick="dropdown()" class="version_select" id="current"></button>
<div id="all-versions" class="available_versions"></div>
</div>

147
.sphinx/conf.py Normal file
View File

@@ -0,0 +1,147 @@
import datetime
import os
import sys
import yaml
# Project config.
project = "distrobuilder"
author = "distrobuilder contributors"
copyright = "2018-%s %s" % (datetime.date.today().year, author)
with open("../shared/version/version.go") as fd:
version = fd.read().split("\n")[-2].split()[-1].strip("\"")
# Extensions.
extensions = [
"myst_parser",
"sphinx_tabs.tabs",
"sphinx_reredirects",
"sphinxext.opengraph",
"youtube-links",
"related-links",
"custom-rst-roles",
"sphinxcontrib.jquery",
"sphinx_design"
]
myst_enable_extensions = [
"substitution",
"deflist",
"linkify"
]
myst_linkify_fuzzy_links=False
myst_heading_anchors = 7
if os.path.exists("../doc/substitutions.yaml"):
with open("../doc/substitutions.yaml", "r") as fd:
myst_substitutions = yaml.safe_load(fd.read())
# Setup theme.
templates_path = ["_templates"]
html_theme = "furo"
html_show_sphinx = False
html_last_updated_fmt = ""
html_favicon = "_static/download/favicon.ico"
html_static_path = ['_static']
html_css_files = ['custom.css']
html_js_files = ['header-nav.js','version-switcher.js']
html_extra_path = ['_extra']
html_theme_options = {
"sidebar_hide_name": True,
"light_css_variables": {
"font-stack": "Ubuntu, -apple-system, Segoe UI, Roboto, Oxygen, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif",
"font-stack--monospace": "Ubuntu Mono, Consolas, Monaco, Courier, monospace",
"color-foreground-primary": "#111",
"color-foreground-secondary": "var(--color-foreground-primary)",
"color-foreground-muted": "#333",
"color-background-secondary": "#FFF",
"color-background-hover": "#f2f2f2",
"color-brand-primary": "#111",
"color-brand-content": "#06C",
"color-api-background": "#cdcdcd",
"color-inline-code-background": "rgba(0,0,0,.03)",
"color-sidebar-link-text": "#111",
"color-sidebar-item-background--current": "#ebebeb",
"color-sidebar-item-background--hover": "#f2f2f2",
"toc-font-size": "var(--font-size--small)",
"color-admonition-title-background--note": "var(--color-background-primary)",
"color-admonition-title-background--tip": "var(--color-background-primary)",
"color-admonition-title-background--important": "var(--color-background-primary)",
"color-admonition-title-background--caution": "var(--color-background-primary)",
"color-admonition-title--note": "#24598F",
"color-admonition-title--tip": "#24598F",
"color-admonition-title--important": "#C7162B",
"color-admonition-title--caution": "#F99B11",
"color-highlighted-background": "#EbEbEb",
"color-link-underline": "var(--color-background-primary)",
"color-link-underline--hover": "var(--color-background-primary)",
},
"dark_css_variables": {
"color-foreground-secondary": "var(--color-foreground-primary)",
"color-foreground-muted": "#CDCDCD",
"color-background-secondary": "var(--color-background-primary)",
"color-background-hover": "#666",
"color-brand-primary": "#fff",
"color-brand-content": "#06C",
"color-sidebar-link-text": "#f7f7f7",
"color-sidebar-item-background--current": "#666",
"color-sidebar-item-background--hover": "#333",
"color-admonition-background": "transparent",
"color-admonition-title-background--note": "var(--color-background-primary)",
"color-admonition-title-background--tip": "var(--color-background-primary)",
"color-admonition-title-background--important": "var(--color-background-primary)",
"color-admonition-title-background--caution": "var(--color-background-primary)",
"color-admonition-title--note": "#24598F",
"color-admonition-title--tip": "#24598F",
"color-admonition-title--important": "#C7162B",
"color-admonition-title--caution": "#F99B11",
"color-highlighted-background": "#666",
"color-link-underline": "var(--color-background-primary)",
"color-link-underline--hover": "var(--color-background-primary)",
},
}
html_context = {
"github_url": "https://github.com/lxc/distrobuilder",
"github_version": "master",
"github_folder": "/doc/",
"github_filetype": "md",
"discourse_prefix": "https://discuss.linuxcontainers.org/t/"
}
html_sidebars = {
"**": [
"sidebar/variant-selector.html",
"sidebar/search.html",
"sidebar/scroll-start.html",
"sidebar/navigation.html",
"sidebar/scroll-end.html",
]
}
source_suffix = ".md"
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['html']
# Open Graph configuration
ogp_site_url = "https://linuxcontainers.org/distrobuilder/docs/latest/"
ogp_site_name = "distrobuilder documentation"
ogp_image = "https://linuxcontainers.org/static/img/containers.png"
# Links to ignore when checking links
linkcheck_ignore = [
]
# Setup redirects (https://documatt.gitlab.io/sphinx-reredirects/usage.html)
redirects = {
"index/index": "../index.html"
}

38
.sphinx/requirements.txt Normal file
View File

@@ -0,0 +1,38 @@
alabaster
Babel
certifi
charset-normalizer
colorama
docutils
idna
imagesize
Jinja2
livereload
MarkupSafe
packaging
Pygments
pyparsing
pytz
requests
six
snowballstemmer
Sphinx
sphinx-autobuild
sphinxcontrib-applehelp
sphinxcontrib-devhelp
sphinxcontrib-htmlhelp
sphinxcontrib-jsmath
sphinxcontrib-qthelp
sphinxcontrib-serializinghtml
sphinxcontrib-jquery
tornado
urllib3
myst-parser
sphinx-tabs
sphinx-reredirects
linkify-it-py
furo
sphinxext-opengraph>=0.6.1
lxd-sphinx-extensions
pyspelling
sphinx-design

277
.sphinx/wordlist.txt Normal file
View File

@@ -0,0 +1,277 @@
AAAA
ABI
ACL
ACLs
AIO
APIs
AppArmor
ARMv
ARP
ASN
AXFR
backend
backends
balancer
balancers
benchmarking
BGP
bibi
bool
bootable
Btrfs
bugfix
bugfixes
Centos
Ceph
CephFS
Ceph's
CFS
cgroup
cgroupfs
cgroups
checksum
checksums
Chocolatey
CIDR
CLI
CPUs
CRIU
CRL
cron
CSV
CUDA
customizable
dataset
DCO
dereferenced
devtmpfs
DHCP
DHCPv
DNS
DNSSEC
DoS
Dqlite
DRM
EB
Ebit
eBPF
ECDHE
ECDSA
EiB
Eibit
endian
ESA
ETag
failover
FQDNs
gapped
GARP
GbE
Gbit
Geneve
GiB
Gibit
GID
GIDs
Golang
goroutines
GPUs
Grafana
HAProxy
hardcoded
Homebrew
hotplug
hotplugged
hotplugging
HTTPS
ICMP
idmap
idmapped
idmaps
incrementing
InfiniBand
InfluxDB
init
initramfs
integrations
IOPS
IOV
IPs
IPv
IPVLAN
jq
JSON
kB
kbit
KiB
kibi
Kibit
lookups
LTS
LV
LVM
LXC
LXCFS
LXD
LXD's
MAAS
macOS
macvlan
Makefile
manpages
Mbit
MiB
Mibit
MicroCeph
MicroCloud
MII
MITM
MTU
multicast
MyST
namespace
namespaced
namespaces
NATed
natively
NDP
netmask
NFS
NIC
NICs
NUMA
NVRAM
OData
OpenMetrics
OpenSSL
OSD
overcommit
overcommitting
overlayfs
OVMF
OVN
OVS
Pbit
PCI
PCIe
peerings
Permalink
PFs
PiB
Pibit
PID
PKI
PNG
Pongo
POSIX
pre
preseed
proxied
proxying
PTS
QEMU
qgroup
qgroups
RADOS
RBAC
RBD
reconfiguring
requestor
RESTful
RHEL
rootfs
RSA
rST
runtime
SATA
scalable
SDN
Seccomp
SFTP
SHA
shiftfs
SIGHUP
SIGTERM
simplestreams
SLAAC
SMTP
Solaris
SPAs
SPL
SquashFS
SSDs
SSL
stateful
stderr
stdin
stdout
STP
struct
structs
subcommands
subitem
subnet
subnets
subpage
substep
subtree
subtrees
subvolume
subvolumes
superset
SVG
symlink
symlinks
syscall
syscalls
sysfs
Tbit
TCP
Telegraf
TiB
Tibit
TLS
tmpfs
toolchain
topologies
TPM
TSIG
TTL
UDP
UEFI
UFW
UI
UID
UIDs
unconfigured
unmanaged
unmount
unmounting
uplink
uptime
userspace
UUID
vCPU
vCPUs
VFs
VFS
VirtIO
virtualize
virtualized
VLAN
VLANs
VM
VMs
VPD
VPS
vSwitch
VXLAN
WebSocket
WebSockets
XFS
XHR
YAML
Zettabyte
ZFS
zpool
zpools

34
Makefile
View File

@@ -1,6 +1,7 @@
VERSION=$(shell grep "var Version" shared/version/version.go | cut -d'"' -f2)
ARCHIVE=distrobuilder-$(VERSION).tar
GO111MODULE=on
SPHINXENV=.sphinx/venv/bin/activate
.PHONY: default check dist
@@ -42,3 +43,36 @@ dist:
# Cleanup
rm -Rf $(TMP)
.PHONY: doc-setup
doc-setup:
@echo "Setting up documentation build environment"
python3 -m venv .sphinx/venv
. $(SPHINXENV) ; pip install --upgrade -r .sphinx/requirements.txt
mkdir -p .sphinx/deps/ .sphinx/themes/
wget -N -P .sphinx/_static/download https://linuxcontainers.org/static/img/favicon.ico https://linuxcontainers.org/static/img/containers.png https://linuxcontainers.org/static/img/containers.small.png
rm -Rf doc/html
.PHONY: doc
doc: doc-setup doc-incremental
.PHONY: doc-incremental
doc-incremental:
@echo "Build the documentation"
. $(SPHINXENV) ; sphinx-build -c .sphinx/ -b dirhtml doc/ doc/html/ -w .sphinx/warnings.txt
.PHONY: doc-serve
doc-serve:
cd doc/html; python3 -m http.server 8001
.PHONY: doc-spellcheck
doc-spellcheck: doc
. $(SPHINXENV) ; python3 -m pyspelling -c .sphinx/.spellcheck.yaml
.PHONY: doc-linkcheck
doc-linkcheck: doc-setup
. $(SPHINXENV) ; sphinx-build -c .sphinx/ -b linkcheck doc/ doc/html/
.PHONY: doc-lint
doc-lint:
.sphinx/.markdownlint/doc-lint.sh

1
README.md
View File

@@ -1 +0,0 @@
doc/index.md

237
README.md Normal file
View File

@@ -0,0 +1,237 @@
# distrobuilder
System container image builder for LXC and LXD
## Status
Type | Service | Status
--- | --- | ---
CI | GitHub | [![Build Status](https://github.com/lxc/distrobuilder/workflows/CI%20tests/badge.svg)](https://github.com/lxc/distrobuilder/actions)
Project status | CII Best Practices | [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1728/badge)](https://bestpractices.coreinfrastructure.org/projects/1728)
## Command line options
The following are the command line options of `distrobuilder`. You can use `distrobuilder` to create container images for both LXC and LXD.
```bash
$ distrobuilder
System container image builder for LXC and LXD
Usage:
distrobuilder [command]
Available Commands:
build-dir Build plain rootfs
build-lxc Build LXC image from scratch
build-lxd Build LXD image from scratch
help Help about any command
pack-lxc Create LXC image from existing rootfs
pack-lxd Create LXD image from existing rootfs
repack-windows Repack Windows ISO with drivers included
Flags:
--cache-dir Cache directory
--cleanup Clean up cache directory (default true)
--debug Enable debug output
--disable-overlay Disable the use of filesystem overlays
-h, --help help for distrobuilder
-o, --options Override options (list of key=value)
-t, --timeout Timeout in seconds
--version Print version number
Use "distrobuilder [command] --help" for more information about a command.
```
## Installing from package
`distrobuilder` is available from the snapstore.
```
sudo snap install distrobuilder --classic
```
## Installing from source
To compile `distrobuilder` from source, first install the Go programming language, and some other dependencies.
- Debian-based:
```
sudo apt update
sudo apt install -y golang-go debootstrap rsync gpg squashfs-tools git
```
- ArchLinux-based:
```
sudo pacman -Syu
sudo pacman -S go debootstrap rsync gnupg squashfs-tools git --needed
```
Second, download the source code of the `distrobuilder` repository (this repository).
```
git clone https://github.com/lxc/distrobuilder
```
Third, enter the directory with the source code of `distrobuilder` and run `make` to compile the source code. This will generate the executable program `distrobuilder`, and it will be located at `$HOME/go/bin/distrobuilder`.
```
cd ./distrobuilder
make
```
Finally, you can run `distrobuilder` as follows. You may also add to your $PATH the directory `$HOME/go/bin/` so that you do not need to run the command with the full path.
```
$HOME/go/bin/distrobuilder
```
## How to use
In the following, we see how to create a container image for LXD.
### Creating a container image
To create a container image, first create a directory where you will be placing the container images, and enter that directory.
```
mkdir -p $HOME/ContainerImages/ubuntu/
cd $HOME/ContainerImages/ubuntu/
```
Then, copy one of the example yaml configuration files for container images into this directory. In this example, we are creating an Ubuntu container image.
```
cp $HOME/go/src/github.com/lxc/distrobuilder/doc/examples/ubuntu.yaml ubuntu.yaml
```
### Build the container image for LXD
Finally, run `distrobuilder` to create the container image. We are using the `build-lxd` option to create a container image for LXD.
```
sudo $HOME/go/bin/distrobuilder build-lxd ubuntu.yaml
```
If the command is successful, you will get an output similar to the following. The `lxd.tar.xz` file is the description of the container image. The `rootfs.squasfs` file is the root filesystem (rootfs) of the container image. The set of these two files is the _container image_.
```bash
$ ls -l
total 100960
-rw-r--r-- 1 root root 676 Oct 3 16:15 lxd.tar.xz
-rw-r--r-- 1 root root 103370752 Oct 3 16:15 rootfs.squashfs
-rw-r--r-- 1 ubuntu ubuntu 7449 Oct 3 16:03 ubuntu.yaml
$
```
### Adding the container image to LXD
To add the container image to a LXD installation, use the `lxc image import` command as follows.
```bash
$ lxc image import lxd.tar.xz rootfs.squashfs --alias mycontainerimage
Image imported with fingerprint: 009349195858651a0f883de804e64eb82e0ac8c0bc51880
```
Let's see the container image in LXD. The `ubuntu.yaml` had a setting to create an Ubuntu 20.04 (`focal`) image. The size is 98.58MB.
```bash
$ lxc image list mycontainerimage
+------------------+--------------+--------+--------------+--------+---------+-----------------------------+
| ALIAS | FINGERPRINT | PUBLIC | DESCRIPTION | ARCH | SIZE | UPLOAD DATE |
+------------------+--------------+--------+--------------+--------+---------+-----------------------------+
| mycontainerimage | 009349195858 | no | Ubuntu focal | x86_64 | 98.58MB | Oct 3, 2020 at 5:10pm (UTC) |
+------------------+--------------+--------+--------------+--------+---------+-----------------------------+
```
### Launching a LXD container from the container image
To launch a container from the freshly created container image, use `lxc launch` as follows. Note that you do not specify a repository of container images (like `ubuntu:` or `images:`) because the image is located locally.
```bash
$ lxc launch mycontainerimage c1
Creating c1
Starting c1
```
### Build a LXC container image
Using LXC containers instead of LXD may require the installation of `lxc-utils`.
Having both LXC and LXD installed on the same system will probably cause confusion.
Use of raw LXC is generally discouraged due to the lack of automatic Apparmor
protection.
For LXC, instead use:
```bash
$ sudo $HOME/go/bin/distrobuilder build-lxc ubuntu.yaml
$ ls -l
total 87340
-rw-r--r-- 1 root root 740 Jan 19 03:15 meta.tar.xz
-rw-r--r-- 1 root root 89421136 Jan 19 03:15 rootfs.tar.xz
-rw-r--r-- 1 root root 4798 Jan 19 02:42 ubuntu.yaml
```
### Adding the container image to LXC
To add the container image to a LXC installation, use the `lxc-create` command as follows.
```bash
lxc-create -n myContainerImage -t local -- --metadata meta.tar.xz --fstree rootfs.tar.xz
```
Then start the container with
```bash
lxc-start -n myContainerImage
```
### Repack Windows ISO
With LXD it's possible to run Windows VMs. All you need is a Windows ISO and a bunch of drivers.
To make the installation a bit easier, `distrobuilder` added the `repack-windows` command. It takes a Windows ISO, and repacks it together with the necessary drivers.
Currently, `distrobuilder` supports Windows 10, Windows Server 2012, Windows Server 2016, Windows Server 2019 and Windows Server 2022. The Windows version will automatically be detected, but in case this fails you can use the `--windows-version` flag to set it manually. It supports the values `w10`, `2k12`, `2k16`, `2k19` and `2k22` for Windows 10, Windows Server 2012, Windows Server 2016, Windows Server 2019 and Windows Server 2022 respectively.
Here's how to repack a Windows ISO:
```bash
distrobuilder repack-windows path/to/Windows.iso path/to/Windows-repacked.iso
```
More information on `repack-windows` can be found by running
```bash
distrobuilder repack-windows -h
```
### Install Windows
Run the following commands to initialize the VM, to configure (=increase) the allocated disk space and finally attach the full path of your prepared ISO file. Note that the installation of Windows 10 takes about 10GB (before updates), therefore a 30GB disk gives you about 20GB of free space.
```bash
lxc init win10 --empty --vm -c security.secureboot=false
lxc config device override win10 root size=30GiB
lxc config device add win10 iso disk source=/path/to/Windows-repacked.iso boot.priority=10
```
Now, the VM win10 has been configured and it is ready to be started. The following command starts the virtual machine and opens up a VGA console so that we go through the graphical installation of Windows.
```bash
lxc start win10 --console=vga
```
Taken from: https://blog.simos.info/how-to-run-a-windows-virtual-machine-on-lxd-on-linux/
### Examples
Examples of yaml files for various distributions can be found in the [examples directory](./doc/examples) and in the [lxc-ci repository](https://github.com/lxc/lxc-ci/tree/master/images).
### Troubleshooting
#### Error "Cannot install into target '/var/cache/distrobuilder.123456789/rootfs' mounted with noexec or nodev"
You have installed `distrobuilder` into a LXD container and you are trying to run it. `distrobuilder` does not run in a LXD container. Run `distrobuilder` on the host, or in a VM.
##### Error "error: This revision of snap "distrobuilder" was published using classic confinement"
You are trying to install the `distrobuilder` snap package. The `distrobuilder` snap package has been configured to use the `classic` confinement. Therefore, when you install it, you have to add the flag `--classic` as shown above in the instructions.
##### Error "You must be root to run this tool"
You must be _root_ in order to run the `distrobuilder` tool. The tool runs commands such as `mknod` that require administrative privileges. Prepend `sudo` when running `distrobuilder`.

666
doc/doc-cheat-sheet.md Normal file
View File

@@ -0,0 +1,666 @@
---
orphan: true
myst:
substitutions:
reuse_key: "This is **included** text."
advanced_reuse_key: "This is a substitution that includes a code block:
```
code block
```"
---
# Documentation cheat sheet
The documentation files use a mixture of [Markdown](https://commonmark.org/) and [MyST](https://myst-parser.readthedocs.io/) syntax.
See the following sections for syntax help and conventions.
## Headings
```{list-table}
:header-rows: 1
* - Input
- Description
* - `# Title`
- Page title and H1 heading
* - `## Heading`
- H2 heading
* - `### Heading`
- H3 heading
* - `#### Heading`
- H4 heading
* - ...
- Further headings
```
Adhere to the following conventions:
- Do not use consecutive headings without intervening text.
- Use sentence style for headings (capitalize only the first word).
- Do not skip levels (for example, always follow an H2 with an H3, not an H4).
## Inline formatting
```{list-table}
:header-rows: 1
* - Input
- Output
* - `*Italic*`
- *Italic*
* - `**Bold**`
- **Bold**
* - `` `code` ``
- `code`
```
Adhere to the following conventions:
- Use italics sparingly. Common uses for italics are titles and names (for example, when referring to a section title that you cannot link to, or when introducing the name for a concept).
- Use bold sparingly. A common use for bold is UI elements ("Click **OK**"). Avoid using bold for emphasis and rather rewrite the sentence to get your point across.
## Code blocks
Start and end a code block with three back ticks:
```
You can specify the code language after the back ticks to enforce a specific lexer, but in many cases, the default lexer works just fine.
```{list-table}
:header-rows: 1
* - Input
- Output
* - ````
```
# Demonstrate a code block
code:
- example: true
```
````
- ```
# Demonstrate a code block
code:
- example: true
```
* - ````
```yaml
# Demonstrate a code block
code:
- example: true
```
````
- ```yaml
# Demonstrate a code block
code:
- example: true
```
```
To include back ticks in a code block, increase the number of surrounding back ticks:
```{list-table}
:header-rows: 1
* - Input
- Output
* -
`````
````
```
````
`````
-
````
```
````
```
## Links
How to link depends on if you are linking to an external URL or to another page in the documentation.
### External links
For external links, use only the URL, or Markdown syntax if you want to override the link text.
```{list-table}
:header-rows: 1
* - Input
- Output
* - `https://linuxcontainers.org`
- [{spellexception}`https://linuxcontainers.org`](https://linuxcontainers.org)
* - `[Linux Containers](https://linuxcontainers.org)`
- [Linux Containers](https://linuxcontainers.org)
```
To display a URL as text and prevent it from being linked, add a `<span></span>`:
```{list-table}
:header-rows: 1
* - Input
- Output
* - `https:/<span></span>/linuxcontainers.org`
- {spellexception}`https:/<span></span>/linuxcontainers.org`
```
### Internal references
For internal references, both Markdown and MyST syntax are supported. In most cases, you should use MyST syntax though, because it resolves the link text automatically and gives an indication of the link in GitHub rendering.
#### Referencing a page
To reference a documentation page, use MyST syntax to automatically extract the link text. When overriding the link text, use Markdown syntax.
```{list-table}
:header-rows: 1
* - Input
- Output
- Output on GitHub
- Status
* - `` {doc}`index` ``
- {doc}`index`
- {doc}<span></span>`index`
- Preferred.
* - `[](index)`
- [](index)
-
- Do not use.
* - `[LXD documentation](index)`
- [LXD documentation](index)
- [LXD documentation](index)
- Preferred when overriding the link text.
* - `` {doc}`LXD documentation <index>` ``
- {doc}`LXD documentation <index>`
- {doc}<span></span>`LXD documentation <index>`
- Alternative when overriding the link text.
```
Adhere to the following conventions:
- Override the link text only when it is necessary. If you can use the document title as link text, do so, because the text will then update automatically if the title changes.
- Never "override" the link text with the same text that would be generated automatically.
(a_section_target)=
#### Referencing a section
To reference a section within the documentation (on the same page or on another page), you can either add a target to it and reference that target, or you can use an automatically generated anchor in combination with the file name.
Adhere to the following conventions:
- Add targets for sections that are central and a "typical" place to link to, so you expect they will be linked frequently. For "one-off" links, use the automatically generated anchors.
- Override the link text only when it is necessary. If you can use the section title as link text, do so, because the text will then update automatically if the title changes.
- Never "override" the link text with the same text that would be generated automatically.
##### Using a target
You can add targets at any place in the documentation. However, if there is no heading or title for the targeted element, you must specify a link text.
(a_random_target)=
```{list-table}
:header-rows: 1
* - Input
- Output
- Output on GitHub
- Description
* - `(target_ID)=`
-
- \(target_ID\)=
- Adds the target ``target_ID``.
* - `` {ref}`a_section_target` ``
- {ref}`a_section_target`
- \{ref\}`a_section_target`
- References a target that has a title.
* - `` {ref}`link text <a_random_target>` ``
- {ref}`link text <a_random_target>`
- \{ref\}`link text <a_random_target>`
- References a target and specifies a title.
* - ``[`option name\](a_random_target)``
- [`option name`](a_random_target)
- [`option name`](a_random_target) (link is broken)
- Use Markdown syntax if you need markup on the link text.
```
##### Using an automatically generated anchor
When using MyST syntax, you must always specify the file name, even if the link points to a section in the same file.
When using Markdown syntax, you can leave out the file name when linking within the same file.
```{list-table}
:header-rows: 1
* - Input
- Output
- Output on GitHub
- Description
* - `` {ref}`doc-cheat-sheet.md#referencing-a-section` ``
- {ref}`doc-cheat-sheet.md#referencing-a-section`
- \{ref\}`doc-cheat-sheet.md#referencing-a-section`
- References an automatically generated anchor.
* - `[](#referencing-a-section)`
- [](#referencing-a-section)
-
- Do not use.
* - `[link text](#referencing-a-section)`
- [link text](#referencing-a-section)
- [link text](#referencing-a-section)
- Preferred when overriding the link text.
* - `` {ref}`link text <doc-cheat-sheet.md#referencing-a-section>` ``
- {ref}`link text <doc-cheat-sheet.md#referencing-a-section>`
- \{ref\}`link text <doc-cheat-sheet.md#referencing-a-section>`
- Alternative when overriding the link text.
```
## Navigation
Every documentation page must be included as a subpage to another page in the navigation.
This is achieved with the [`toctree`](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-toctree) directive in the parent page: <!-- wokeignore:rule=master -->
````
```{toctree}
:hidden:
subpage1
subpage2
```
````
If a page should not be included in the navigation, you can suppress the resulting build warning by putting the following instruction at the top of the file:
```
---
orphan: true
---
```
Use orphan pages sparingly and only if there is a clear reason for it.
## Lists
```{list-table}
:header-rows: 1
* - Input
- Output
* - ```
- Item 1
- Item 2
- Item 3
```
- - Item 1
- Item 2
- Item 3
* - ```
1. Step 1
1. Step 2
1. Step 3
```
- 1. Step 1
1. Step 2
1. Step 3
* - ```
1. Step 1
- Item 1
* Subitem
- Item 2
1. Step 2
1. Substep 1
1. Substep 2
```
- 1. Step 1
- Item 1
* Subitem
- Item 2
1. Step 2
1. Substep 1
1. Substep 2
```
Adhere to the following conventions:
- In numbered lists, use ``1.`` for all items to generate the step numbers automatically.
- Use `-` for unordered lists. When using nested lists, you can use `*` for the nested level.
### Definition lists
```{list-table}
:header-rows: 1
* - Input
- Output
* - ```
Term 1
: Definition
Term 2
: Definition
```
- Term 1
: Definition
Term 2
: Definition
```
## Tables
You can use standard Markdown tables. However, using the rST [list table](https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table) syntax is usually much easier.
Both markups result in the following output:
```{list-table}
:header-rows: 1
* - Header 1
- Header 2
* - Cell 1
Second paragraph cell 1
- Cell 2
* - Cell 3
- Cell 4
```
### Markdown tables
```
| Header 1 | Header 2 |
|------------------------------------|----------|
| Cell 1<br><br>2nd paragraph cell 1 | Cell 2 |
| Cell 3 | Cell 4 |
```
### List tables
````
```{list-table}
:header-rows: 1
* - Header 1
- Header 2
* - Cell 1
2nd paragraph cell 1
- Cell 2
* - Cell 3
- Cell 4
```
````
## Notes
```{list-table}
:header-rows: 1
* - Input
- Output
* - ````
```{note}
A note.
```
````
- ```{note}
A note.
```
* - ````
```{tip}
A tip.
```
````
- ```{tip}
A tip.
```
* - ````
```{important}
Important information
```
````
- ```{important}
Important information.
```
* - ````
```{caution}
This might damage your hardware!
```
````
- ```{caution}
This might damage your hardware!
```
```
Adhere to the following conventions:
- Use notes sparingly.
- Only use the following note types: `note`, `tip`, `important`, `caution`
- Only use a caution if there is a clear hazard of hardware damage or data loss.
## Images
```{list-table}
:header-rows: 1
* - Input
- Output
* - ```
![Alt text](https://linuxcontainers.org/static/img/containers.png)
```
- ![Alt text](https://linuxcontainers.org/static/img/containers.png)
* - ````
```{figure} https://linuxcontainers.org/static/img/containers.png
:width: 100px
:alt: Alt text
Figure caption
```
````
- ```{figure} https://linuxcontainers.org/static/img/containers.png
:width: 100px
:alt: Alt text
Figure caption
```
```
Adhere to the following conventions:
- For pictures in the `doc` folder, start the path with `/` (for example, `/images/image.png`).
- Use PNG format for screenshots and SVG format for graphics.
## Reuse
A big advantage of MyST in comparison to plain Markdown is that it allows to reuse content.
### Substitution
To reuse sentences or paragraphs without too much markup and special formatting, use substitutions.
Substitutions can be defined in the following locations:
- In the `substitutions.yaml` file. Substitutions defined in this file are available in all documentation pages.
- At the top of a single file in the following format:
````
---
myst:
substitutions:
reuse_key: "This is **included** text."
advanced_reuse_key: "This is a substitution that includes a code block:
```
code block
```"
---
````
You can combine both options by defining a default substitution in `reuse/substitutions.py` and overriding it at the top of a file.
```{list-table}
:header-rows: 1
* - Input
- Output
* - `{{reuse_key}}`
- {{reuse_key}}
* - `{{advanced_reuse_key}}`
- {{advanced_reuse_key}}
```
Adhere to the following convention:
- Substitutions do not work on GitHub. Therefore, use key names that indicate the included text (for example, `note_not_supported` instead of `reuse_note`).
### File inclusion
To reuse longer sections or text with more advanced markup, you can put the content in a separate file and include the file or parts of the file in several locations.
You cannot put any targets into the content that is being reused (because references to this target would be ambiguous then). You can, however, put a target right before including the file.
By combining file inclusion and substitutions, you can even replace parts of the included text.
`````{list-table}
:header-rows: 1
* - Input
- Output
* - ````
% Include parts of the content from file [../README.md](../README.md)
```{include} ../README.md
:start-after: Installing from source
:end-before: Second, download the source code
```
````
-
% Include parts of the content from file [../README.md](../README.md)
```{include} ../README.md
:start-after: Installing from source
:end-before: Second, download the source code
```
`````
Adhere to the following convention:
- File inclusion does not work on GitHub. Therefore, always add a comment linking to the included file.
- To select parts of the text, add HTML comments for the start and end points and use `:start-after:` and `:end-before:`, if possible. You can combine `:start-after:` and `:end-before:` with `:start-line:` and `:end-line:` if required. Using only `:start-line:` and `:end-line:` is error-prone though.
## Tabs
``````{list-table}
:header-rows: 1
* - Input
- Output
* - `````
````{tabs}
```{group-tab} Tab 1
Content Tab 1
```
```{group-tab} Tab 2
Content Tab 2
```
````
`````
- ````{tabs}
```{group-tab} Tab 1
Content Tab 1
```
```{group-tab} Tab 2
Content Tab 2
```
````
``````
## Collapsible sections
There is no support for details sections in rST, but you can insert HTML to create them.
```{list-table}
:header-rows: 1
* - Input
- Output
* - ```
<details>
<summary>Details</summary>
Content
</details>
```
- <details>
<summary>Details</summary>
Content
</details>
```
## Glossary
You can define glossary terms in any file. Ideally, all terms should be collected in one glossary file though, and they can then be referenced from any file.
`````{list-table}
:header-rows: 1
* - Input
- Output
* - ````
```{glossary}
example term
Definition of the example term.
```
````
- ```{glossary}
example term
Definition of the example term.
```
* - ``{term}`example term` ``
- {term}`example term`
`````

253
doc/index.md
View File

@@ -1,237 +1,24 @@
---
relatedlinks: https://linuxcontainers.org/distrobuilder/introduction/
---
[![LXD](../.sphinx/_static/download/containers.png)](https://linuxcontainers.org/lxd)
# distrobuilder
System container image builder for LXC and LXD
## Status
Type | Service | Status
--- | --- | ---
CI | GitHub | [![Build Status](https://github.com/lxc/distrobuilder/workflows/CI%20tests/badge.svg)](https://github.com/lxc/distrobuilder/actions)
Project status | CII Best Practices | [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1728/badge)](https://bestpractices.coreinfrastructure.org/projects/1728)
## Command line options
The following are the command line options of `distrobuilder`. You can use `distrobuilder` to create container images for both LXC and LXD.
```bash
$ distrobuilder
System container image builder for LXC and LXD
Usage:
distrobuilder [command]
Available Commands:
build-dir Build plain rootfs
build-lxc Build LXC image from scratch
build-lxd Build LXD image from scratch
help Help about any command
pack-lxc Create LXC image from existing rootfs
pack-lxd Create LXD image from existing rootfs
repack-windows Repack Windows ISO with drivers included
Flags:
--cache-dir Cache directory
--cleanup Clean up cache directory (default true)
--debug Enable debug output
--disable-overlay Disable the use of filesystem overlays
-h, --help help for distrobuilder
-o, --options Override options (list of key=value)
-t, --timeout Timeout in seconds
--version Print version number
Use "distrobuilder [command] --help" for more information about a command.
```{toctree}
:hidden:
:titlesonly:
self
readme
actions
building
filters
generators
image
mappings
packages
source
targets
```
## Installing from package
`distrobuilder` is available from the snapstore.
```
sudo snap install distrobuilder --classic
```
## Installing from source
To compile `distrobuilder` from source, first install the Go programming language, and some other dependencies.
- Debian-based:
```
sudo apt update
sudo apt install -y golang-go debootstrap rsync gpg squashfs-tools git
```
- ArchLinux-based:
```
sudo pacman -Syu
sudo pacman -S go debootstrap rsync gnupg squashfs-tools git --needed
```
Second, download the source code of the `distrobuilder` repository (this repository).
```
git clone https://github.com/lxc/distrobuilder
```
Third, enter the directory with the source code of `distrobuilder` and run `make` to compile the source code. This will generate the executable program `distrobuilder`, and it will be located at `$HOME/go/bin/distrobuilder`.
```
cd ./distrobuilder
make
```
Finally, you can run `distrobuilder` as follows. You may also add to your $PATH the directory `$HOME/go/bin/` so that you do not need to run the command with the full path.
```
$HOME/go/bin/distrobuilder
```
## How to use
In the following, we see how to create a container image for LXD.
### Creating a container image
To create a container image, first create a directory where you will be placing the container images, and enter that directory.
```
mkdir -p $HOME/ContainerImages/ubuntu/
cd $HOME/ContainerImages/ubuntu/
```
Then, copy one of the example yaml configuration files for container images into this directory. In this example, we are creating an Ubuntu container image.
```
cp $HOME/go/src/github.com/lxc/distrobuilder/doc/examples/ubuntu.yaml ubuntu.yaml
```
### Build the container image for LXD
Finally, run `distrobuilder` to create the container image. We are using the `build-lxd` option to create a container image for LXD.
```
sudo $HOME/go/bin/distrobuilder build-lxd ubuntu.yaml
```
If the command is successful, you will get an output similar to the following. The `lxd.tar.xz` file is the description of the container image. The `rootfs.squasfs` file is the root filesystem (rootfs) of the container image. The set of these two files is the _container image_.
```bash
$ ls -l
total 100960
-rw-r--r-- 1 root root 676 Oct 3 16:15 lxd.tar.xz
-rw-r--r-- 1 root root 103370752 Oct 3 16:15 rootfs.squashfs
-rw-r--r-- 1 ubuntu ubuntu 7449 Oct 3 16:03 ubuntu.yaml
$
```
### Adding the container image to LXD
To add the container image to a LXD installation, use the `lxc image import` command as follows.
```bash
$ lxc image import lxd.tar.xz rootfs.squashfs --alias mycontainerimage
Image imported with fingerprint: 009349195858651a0f883de804e64eb82e0ac8c0bc51880
```
Let's see the container image in LXD. The `ubuntu.yaml` had a setting to create an Ubuntu 20.04 (`focal`) image. The size is 98.58MB.
```bash
$ lxc image list mycontainerimage
+------------------+--------------+--------+--------------+--------+---------+-----------------------------+
| ALIAS | FINGERPRINT | PUBLIC | DESCRIPTION | ARCH | SIZE | UPLOAD DATE |
+------------------+--------------+--------+--------------+--------+---------+-----------------------------+
| mycontainerimage | 009349195858 | no | Ubuntu focal | x86_64 | 98.58MB | Oct 3, 2020 at 5:10pm (UTC) |
+------------------+--------------+--------+--------------+--------+---------+-----------------------------+
```
### Launching a LXD container from the container image
To launch a container from the freshly created container image, use `lxc launch` as follows. Note that you do not specify a repository of container images (like `ubuntu:` or `images:`) because the image is located locally.
```bash
$ lxc launch mycontainerimage c1
Creating c1
Starting c1
```
### Build a LXC container image
Using LXC containers instead of LXD may require the installation of `lxc-utils`.
Having both LXC and LXD installed on the same system will probably cause confusion.
Use of raw LXC is generally discouraged due to the lack of automatic Apparmor
protection.
For LXC, instead use:
```bash
$ sudo $HOME/go/bin/distrobuilder build-lxc ubuntu.yaml
$ ls -l
total 87340
-rw-r--r-- 1 root root 740 Jan 19 03:15 meta.tar.xz
-rw-r--r-- 1 root root 89421136 Jan 19 03:15 rootfs.tar.xz
-rw-r--r-- 1 root root 4798 Jan 19 02:42 ubuntu.yaml
```
### Adding the container image to LXC
To add the container image to a LXC installation, use the `lxc-create` command as follows.
```bash
lxc-create -n myContainerImage -t local -- --metadata meta.tar.xz --fstree rootfs.tar.xz
```
Then start the container with
```bash
lxc-start -n myContainerImage
```
### Repack Windows ISO
With LXD it's possible to run Windows VMs. All you need is a Windows ISO and a bunch of drivers.
To make the installation a bit easier, `distrobuilder` added the `repack-windows` command. It takes a Windows ISO, and repacks it together with the necessary drivers.
Currently, `distrobuilder` supports Windows 10, Windows Server 2012, Windows Server 2016, Windows Server 2019 and Windows Server 2022. The Windows version will automatically be detected, but in case this fails you can use the `--windows-version` flag to set it manually. It supports the values `w10`, `2k12`, `2k16`, `2k19` and `2k22` for Windows 10, Windows Server 2012, Windows Server 2016, Windows Server 2019 and Windows Server 2022 respectively.
Here's how to repack a Windows ISO:
```bash
distrobuilder repack-windows path/to/Windows.iso path/to/Windows-repacked.iso
```
More information on `repack-windows` can be found by running
```bash
distrobuilder repack-windows -h
```
### Install Windows
Run the following commands to initialize the VM, to configure (=increase) the allocated disk space and finally attach the full path of your prepared ISO file. Note that the installation of Windows 10 takes about 10GB (before updates), therefore a 30GB disk gives you about 20GB of free space.
```bash
lxc init win10 --empty --vm -c security.secureboot=false
lxc config device override win10 root size=30GiB
lxc config device add win10 iso disk source=/path/to/Windows-repacked.iso boot.priority=10
```
Now, the VM win10 has been configured and it is ready to be started. The following command starts the virtual machine and opens up a VGA console so that we go through the graphical installation of Windows.
```bash
lxc start win10 --console=vga
```
Taken from: https://blog.simos.info/how-to-run-a-windows-virtual-machine-on-lxd-on-linux/
### Examples
Examples of yaml files for various distributions can be found in the [examples directory](./doc/examples) and in the [lxc-ci repository](https://github.com/lxc/lxc-ci/tree/master/images).
### Troubleshooting
#### Error "Cannot install into target '/var/cache/distrobuilder.123456789/rootfs' mounted with noexec or nodev"
You have installed `distrobuilder` into a LXD container and you are trying to run it. `distrobuilder` does not run in a LXD container. Run `distrobuilder` on the host, or in a VM.
##### Error "error: This revision of snap "distrobuilder" was published using classic confinement"
You are trying to install the `distrobuilder` snap package. The `distrobuilder` snap package has been configured to use the `classic` confinement. Therefore, when you install it, you have to add the flag `--classic` as shown above in the instructions.
##### Error "You must be root to run this tool"
You must be _root_ in order to run the `distrobuilder` tool. The tool runs commands such as `mknod` that require administrative privileges. Prepend `sudo` when running `distrobuilder`.

6
doc/readme.md Normal file
View File

@@ -0,0 +1,6 @@
# Readme
% Include content from [../README.md](../README.md)
```{include} ../README.md
:start-line: 2
```

2
doc/substitutions.yaml Normal file
View File

@@ -0,0 +1,2 @@
# Key/value substitutions to use within the Sphinx doc.
{example_key: "Value"}