mirror of
https://github.com/containers/youki
synced 2025-11-11 11:28:42 +01:00
353 lines
19 KiB
HTML
353 lines
19 KiB
HTML
<!DOCTYPE HTML>
|
|
<html lang="en" class="light sidebar-visible" dir="ltr">
|
|
<head>
|
|
<!-- Book generated using mdBook -->
|
|
<meta charset="UTF-8">
|
|
<title>Basic Setup - Youki User and Developer Documentation</title>
|
|
|
|
|
|
<!-- Custom HTML head -->
|
|
|
|
<meta name="description" content="">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1">
|
|
<meta name="theme-color" content="#ffffff">
|
|
|
|
<link rel="icon" href="../favicon.svg">
|
|
<link rel="shortcut icon" href="../favicon.png">
|
|
<link rel="stylesheet" href="../css/variables.css">
|
|
<link rel="stylesheet" href="../css/general.css">
|
|
<link rel="stylesheet" href="../css/chrome.css">
|
|
<link rel="stylesheet" href="../css/print.css" media="print">
|
|
|
|
<!-- Fonts -->
|
|
<link rel="stylesheet" href="../FontAwesome/css/font-awesome.css">
|
|
<link rel="stylesheet" href="../fonts/fonts.css">
|
|
|
|
<!-- Highlight.js Stylesheets -->
|
|
<link rel="stylesheet" id="highlight-css" href="../highlight.css">
|
|
<link rel="stylesheet" id="tomorrow-night-css" href="../tomorrow-night.css">
|
|
<link rel="stylesheet" id="ayu-highlight-css" href="../ayu-highlight.css">
|
|
|
|
<!-- Custom theme stylesheets -->
|
|
|
|
|
|
<!-- Provide site root and default themes to javascript -->
|
|
<script>
|
|
const path_to_root = "../";
|
|
const default_light_theme = "light";
|
|
const default_dark_theme = "navy";
|
|
window.path_to_searchindex_js = "../searchindex.js";
|
|
</script>
|
|
<!-- Start loading toc.js asap -->
|
|
<script src="../toc.js"></script>
|
|
</head>
|
|
<body>
|
|
<div id="mdbook-help-container">
|
|
<div id="mdbook-help-popup">
|
|
<h2 class="mdbook-help-title">Keyboard shortcuts</h2>
|
|
<div>
|
|
<p>Press <kbd>←</kbd> or <kbd>→</kbd> to navigate between chapters</p>
|
|
<p>Press <kbd>S</kbd> or <kbd>/</kbd> to search in the book</p>
|
|
<p>Press <kbd>?</kbd> to show this help</p>
|
|
<p>Press <kbd>Esc</kbd> to hide this help</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
<div id="body-container">
|
|
<!-- Work around some values being stored in localStorage wrapped in quotes -->
|
|
<script>
|
|
try {
|
|
let theme = localStorage.getItem('mdbook-theme');
|
|
let sidebar = localStorage.getItem('mdbook-sidebar');
|
|
|
|
if (theme.startsWith('"') && theme.endsWith('"')) {
|
|
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
|
|
}
|
|
|
|
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
|
|
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
|
|
}
|
|
} catch (e) { }
|
|
</script>
|
|
|
|
<!-- Set the theme before any content is loaded, prevents flash -->
|
|
<script>
|
|
const default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? default_dark_theme : default_light_theme;
|
|
let theme;
|
|
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
|
|
if (theme === null || theme === undefined) { theme = default_theme; }
|
|
const html = document.documentElement;
|
|
html.classList.remove('light')
|
|
html.classList.add(theme);
|
|
html.classList.add("js");
|
|
</script>
|
|
|
|
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
|
|
|
|
<!-- Hide / unhide sidebar before it is displayed -->
|
|
<script>
|
|
let sidebar = null;
|
|
const sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
|
|
if (document.body.clientWidth >= 1080) {
|
|
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
|
|
sidebar = sidebar || 'visible';
|
|
} else {
|
|
sidebar = 'hidden';
|
|
sidebar_toggle.checked = false;
|
|
}
|
|
if (sidebar === 'visible') {
|
|
sidebar_toggle.checked = true;
|
|
} else {
|
|
html.classList.remove('sidebar-visible');
|
|
}
|
|
</script>
|
|
|
|
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
|
|
<!-- populated by js -->
|
|
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
|
|
<noscript>
|
|
<iframe class="sidebar-iframe-outer" src="../toc.html"></iframe>
|
|
</noscript>
|
|
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
|
|
<div class="sidebar-resize-indicator"></div>
|
|
</div>
|
|
</nav>
|
|
|
|
<div id="page-wrapper" class="page-wrapper">
|
|
|
|
<div class="page">
|
|
<div id="menu-bar-hover-placeholder"></div>
|
|
<div id="menu-bar" class="menu-bar sticky">
|
|
<div class="left-buttons">
|
|
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
|
|
<i class="fa fa-bars"></i>
|
|
</label>
|
|
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
|
|
<i class="fa fa-paint-brush"></i>
|
|
</button>
|
|
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
|
|
<li role="none"><button role="menuitem" class="theme" id="default_theme">Auto</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
|
|
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
|
|
</ul>
|
|
<button id="search-toggle" class="icon-button" type="button" title="Search (`/`)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="/ s" aria-controls="searchbar">
|
|
<i class="fa fa-search"></i>
|
|
</button>
|
|
</div>
|
|
|
|
<h1 class="menu-title">Youki User and Developer Documentation</h1>
|
|
|
|
<div class="right-buttons">
|
|
<a href="../print.html" title="Print this book" aria-label="Print this book">
|
|
<i id="print-button" class="fa fa-print"></i>
|
|
</a>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div id="search-wrapper" class="hidden">
|
|
<form id="searchbar-outer" class="searchbar-outer">
|
|
<div class="search-wrapper">
|
|
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
|
|
<div class="spinner-wrapper">
|
|
<i class="fa fa-spinner fa-spin"></i>
|
|
</div>
|
|
</div>
|
|
</form>
|
|
<div id="searchresults-outer" class="searchresults-outer hidden">
|
|
<div id="searchresults-header" class="searchresults-header"></div>
|
|
<ul id="searchresults">
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
|
|
<script>
|
|
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
|
|
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
|
|
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
|
|
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
|
|
});
|
|
</script>
|
|
|
|
<div id="content" class="content">
|
|
<main>
|
|
<h1 id="basic-setup"><a class="header" href="#basic-setup">Basic Setup</a></h1>
|
|
<p>This explains the requirements to use youki as a low-level container runtime, or to depend once of its crates as dependency for your own project.</p>
|
|
<p>Youki currently only supports Linux Platform, and to use it on other platform you will need to use some kind of virtualization.</p>
|
|
<p>Also note that youki currently only supports and expects systemd as init system, and would not work on other systems. There is currently work on-going to put systemd dependent features behind a feature flag, but till then you will need a systemd enabled system to work with youki.</p>
|
|
<h2 id="getting-started"><a class="header" href="#getting-started">Getting Started</a></h2>
|
|
<h3 id="runtime-requirements"><a class="header" href="#runtime-requirements">Runtime requirements</a></h3>
|
|
<p>The static binary (musl) builds of youki have no additional runtime requirements. Otherwise you need to install the runtime requirements using your distribution's package manager:</p>
|
|
<h4 id="debian-ubuntu-and-related-distributions"><a class="header" href="#debian-ubuntu-and-related-distributions">Debian, Ubuntu and related distributions</a></h4>
|
|
<pre><code class="language-console">sudo apt-get install libseccomp2
|
|
</code></pre>
|
|
<h4 id="fedora-centos-rhel-and-related-distributions"><a class="header" href="#fedora-centos-rhel-and-related-distributions">Fedora, CentOS, RHEL and related distributions</a></h4>
|
|
<pre><code class="language-console">sudo dnf install libseccomp
|
|
</code></pre>
|
|
<h3 id="install-youki-prebuilt-binary"><a class="header" href="#install-youki-prebuilt-binary">Install youki (prebuilt binary)</a></h3>
|
|
<p>Install from the GitHub release as root:</p>
|
|
<!--youki release begin-->
|
|
<pre><code class="language-console"># curl -sSfL https://github.com/youki-dev/youki/releases/download/v0.5.7/youki-0.5.7-$(uname -m)-musl.tar.gz | tar -xzvC /usr/bin/ youki
|
|
</code></pre>
|
|
<!--youki release end-->
|
|
<h3 id="running-youki"><a class="header" href="#running-youki">Running youki</a></h3>
|
|
<p>You can use youki by itself to start and run containers, but it can be a little tedious, as it is a low-level container runtime. You can use a High-level container runtime, with its runtime set to youki, so that it will be easier to use.</p>
|
|
<p>This documentation uses Docker in its examples, which can be installed from <a href="https://docs.docker.com/engine/install">here</a>.
|
|
After installing Docker, configure youki as a Docker runtime as follows:</p>
|
|
<pre><code class="language-console">sudo cat > /etc/docker/daemon.json <<EOF
|
|
{
|
|
"runtimes": {
|
|
"youki": {
|
|
"path": "/usr/bin/youki"
|
|
}
|
|
}
|
|
}
|
|
EOF
|
|
|
|
sudo systemctl reload docker
|
|
</code></pre>
|
|
<p>Once configured, you can run a container using youki like this:</p>
|
|
<pre><code class="language-console">docker run --rm --runtime youki hello-world
|
|
</code></pre>
|
|
<p>For more details, see <a href="./basic_usage.html">Basic Usage</a>.</p>
|
|
<hr />
|
|
<h2 id="installing-youki-from-source"><a class="header" href="#installing-youki-from-source">Installing youki from source</a></h2>
|
|
<h3 id="build-requirements"><a class="header" href="#build-requirements">Build Requirements</a></h3>
|
|
<p>As youki is written in Rust, you will need to install and setup Rust toolchain to compile it. The instructions for that can be found on Rust's official site <a href="https://www.rust-lang.org/tools/install">here</a>.
|
|
If you installed it using rustup, the correct compiler version will be setup automatically from <code>rust-toolchain.toml</code> in the repo root.</p>
|
|
<h3 id="build-with-cross-rs"><a class="header" href="#build-with-cross-rs">Build with cross-rs</a></h3>
|
|
<p>You can compile youki using <a href="https://github.com/cross-rs/cross">cross-rs</a>, which provides:</p>
|
|
<ul>
|
|
<li>Seamless compilation for different architectures (see <code>Cross.toml</code> in the repo root for the list of supported targets)</li>
|
|
<li>No build time dependencies (compilation runs in a container)</li>
|
|
<li>No runtime dependencies when building static binaries (musl targets)</li>
|
|
</ul>
|
|
<p>The only build dependency is <a href="https://github.com/cross-rs/cross?tab=readme-ov-file#installation">cross-rs</a> and its <a href="https://github.com/cross-rs/cross?tab=readme-ov-file#dependencies">dependencies</a> (rustup and docker or podman).</p>
|
|
<pre><code class="language-console">CARGO=cross TARGET=musl just youki-dev # or youki-release
|
|
</code></pre>
|
|
<h3 id="build-without-cross-rs"><a class="header" href="#build-without-cross-rs">Build without cross-rs</a></h3>
|
|
<p>Install the build dependencies and then run:</p>
|
|
<pre><code class="language-console">just youki-dev # or youki-release
|
|
</code></pre>
|
|
<p>Install the build dependencies using your distribution's package manger</p>
|
|
<h4 id="debian-ubuntu-and-related-distributions-1"><a class="header" href="#debian-ubuntu-and-related-distributions-1">Debian, Ubuntu and related distributions</a></h4>
|
|
<pre><code class="language-console">sudo apt-get install \
|
|
pkg-config \
|
|
libsystemd-dev \
|
|
build-essential \
|
|
libelf-dev \
|
|
libseccomp-dev \
|
|
libclang-dev \
|
|
libssl-dev
|
|
</code></pre>
|
|
<h4 id="fedora-centos-rhel-and-related-distributions-1"><a class="header" href="#fedora-centos-rhel-and-related-distributions-1">Fedora, CentOS, RHEL and related distributions</a></h4>
|
|
<pre><code class="language-console">sudo dnf install \
|
|
pkg-config \
|
|
systemd-devel \
|
|
elfutils-libelf-devel \
|
|
libseccomp-devel \
|
|
clang-devel \
|
|
openssl-devel
|
|
</code></pre>
|
|
<h3 id="getting-the-source"><a class="header" href="#getting-the-source">Getting the source</a></h3>
|
|
<p>Currently youki can only be installed from the source code itself, so you will need to clone the youki GitHub repository to get the source code for using it as a runtime. If you are using any crates of youki as dependency you need to do this step, as Cargo will automatically clone the repository for you.</p>
|
|
<p>To clone the repository, run</p>
|
|
<pre><code class="language-console">git clone https://github.com/youki-dev/youki.git
|
|
</code></pre>
|
|
<p>This will create a directory named youki in the directory you ran the command in. This youki directory will be referred to as root directory throughout the documentation.</p>
|
|
<h3 id="build-from-source"><a class="header" href="#build-from-source">Build from source</a></h3>
|
|
<p>Once you have cloned the source, you can build it with <a href="https://github.com/casey/just#installation">just</a> :</p>
|
|
<pre><code class="language-console"># go into the cloned directory
|
|
cd youki
|
|
just youki-dev # or youki-release
|
|
./youki -h # get information about youki command
|
|
</code></pre>
|
|
<p>This will build the youki binary, and put it at the root level of the cloned directory, that is in the youki/ .</p>
|
|
<hr />
|
|
<h3 id="using-sub-crates-as-dependency"><a class="header" href="#using-sub-crates-as-dependency">Using sub-crates as dependency</a></h3>
|
|
<p>To use any of the sub-crate as a dependency in your own project, you can specify the dependency as follows,</p>
|
|
<pre><code class="language-toml">[dependencies]
|
|
...
|
|
liboci-cli = { git = "https://github.com/youki-dev/youki.git" }
|
|
...
|
|
</code></pre>
|
|
<p>Here we use <code>liboci-cli</code> as an example, which can be replaced by the sub-crate that you need.</p>
|
|
<p>Then you can use it in your source as</p>
|
|
<pre><code>use liboci_cli::{...}
|
|
</code></pre>
|
|
<hr />
|
|
<h3 id="using-vagrant-to-run-youki-on-non-linux-platform"><a class="header" href="#using-vagrant-to-run-youki-on-non-linux-platform">Using Vagrant to run youki on non-Linux Platform</a></h3>
|
|
<p>As explained before, youki only support Linux, and to build/use it on non-Linux Platforms, you will need to use some kind of virtualization. The repo provides a Vagrantfile to do the required VM setup using Vagrant, which can be installed from <a href="https://www.vagrantup.com/docs/installation">here</a>.</p>
|
|
<p>Once installed and setup, you can run vagrant commands in the cloned directory to run youki inside the VM created by vagrant :</p>
|
|
<pre><code class="language-console"># in the youki directory
|
|
|
|
# for rootless mode, which is default
|
|
vagrant up default
|
|
vagrant ssh default
|
|
|
|
# or if you want to develop in rootful mode
|
|
vagrant up rootful
|
|
vagrant ssh rootful
|
|
|
|
# in virtual machine
|
|
cd youki
|
|
just youki-dev # or youki-release
|
|
</code></pre>
|
|
|
|
</main>
|
|
|
|
<nav class="nav-wrapper" aria-label="Page navigation">
|
|
<!-- Mobile navigation buttons -->
|
|
<a rel="prev" href="../user/introduction.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|
<i class="fa fa-angle-left"></i>
|
|
</a>
|
|
|
|
<a rel="next prefetch" href="../user/basic_usage.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|
<i class="fa fa-angle-right"></i>
|
|
</a>
|
|
|
|
<div style="clear: both"></div>
|
|
</nav>
|
|
</div>
|
|
</div>
|
|
|
|
<nav class="nav-wide-wrapper" aria-label="Page navigation">
|
|
<a rel="prev" href="../user/introduction.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
|
|
<i class="fa fa-angle-left"></i>
|
|
</a>
|
|
|
|
<a rel="next prefetch" href="../user/basic_usage.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
|
|
<i class="fa fa-angle-right"></i>
|
|
</a>
|
|
</nav>
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<script>
|
|
window.playground_copyable = true;
|
|
</script>
|
|
|
|
|
|
<script src="../elasticlunr.min.js"></script>
|
|
<script src="../mark.min.js"></script>
|
|
<script src="../searcher.js"></script>
|
|
|
|
<script src="../clipboard.min.js"></script>
|
|
<script src="../highlight.js"></script>
|
|
<script src="../book.js"></script>
|
|
|
|
<!-- Custom JS scripts -->
|
|
|
|
|
|
|
|
</div>
|
|
</body>
|
|
</html>
|