diff options
Diffstat (limited to 'docs/install.html')
| -rw-r--r-- | docs/install.html | 662 |
1 files changed, 662 insertions, 0 deletions
diff --git a/docs/install.html b/docs/install.html new file mode 100644 index 0000000..8f6e2a0 --- /dev/null +++ b/docs/install.html @@ -0,0 +1,662 @@ +<!DOCTYPE html> +<html lang="en"> +<head> +<!-- 2021-02-02 --> +<meta charset="utf-8"> +<meta name="viewport" content="width=device-width, initial-scale=1"> +<title>Installation Guide</title> +<meta name="generator" content="Org mode"> +<meta name="author" content="Cem Keylan"> +<link rel="stylesheet" type="text/css" href="/style.css"> +</head> +<body> +<div id="preamble" class="status"> +<nav id="navbar"> + <a href="/" class=navbartitle>Carbs Linux</a> + + <label for="hamburger">☰</label> + <input type="checkbox" id="hamburger" /> + <ul id=navbarlist> + <li><a href="/" title="Home Page">Home</a></li> + <li><a href="//git.carbslinux.org" title="Git Repository">Git</a></li> + <li><a href="/download.html" title="Download Carbs Linux">Download</a></li> + <li><a href="/blog" title="Blog Posts">Blog</a></li> + <li><a href="/install.html" title="Installation Instructions">Installation</a></li> + <li><a href="/docs.html" title="Documentation">Docs</a></li> + </ul> +</nav> +</div> +<div id="content"> +<header> +<h1 class="title">Installation Guide</h1> +</header><p> +These are the step-by-step instructions for installing Carbs Linux. It can be +acquired as plain-text to be viewed offline with a pager from +<a href="https://carbslinux.org/install.txt">https://carbslinux.org/install.txt</a>. +</p> + +<div class="org-src-container"> +<pre class="src src-sh">curl -sL https://carbslinux.org/install.txt | less +</pre> +</div> + +<div id="text-table-of-contents"> +<ul> +<li><a href="#org3ef8e84">1. Preparing Environment</a> +<ul> +<li><a href="#orgff14f1e">1.1. Download</a></li> +<li><a href="#orgb03d704">1.2. Signature verification</a></li> +<li><a href="#org44c5069">1.3. Extracting the tarball</a></li> +<li><a href="#orgea6ba02">1.4. Obtain the chroot helper</a></li> +</ul> +</li> +<li><a href="#org32c470a">2. Chroot</a> +<ul> +<li><a href="#orgffe47f7">2.1. Setting up repositories</a> +<ul> +<li><a href="#org7913b8a">2.1.1. Obtaining from git</a></li> +<li><a href="#org69ce01c">2.1.2. Obtaining from rsync</a></li> +<li><a href="#orge7a96e2">2.1.3. Making the package manager use the repositories</a></li> +</ul> +</li> +<li><a href="#orge7115ca">2.2. Updating packages</a></li> +<li><a href="#org498cf81">2.3. Installing packages</a></li> +<li><a href="#orgc580a0d">2.4. Essential Software</a></li> +<li><a href="#org543d436">2.5. Obtaining the documentation</a></li> +</ul> +</li> +<li><a href="#orgf4a305b">3. System Configuration</a> +<ul> +<li><a href="#orgbb6f72c">3.1. Configuring hostname</a></li> +<li><a href="#org91ebad2">3.2. Hosts file</a></li> +</ul> +</li> +<li><a href="#orgab5cd50">4. Kernel</a> +<ul> +<li><a href="#orgbe83919">4.1. Obtaining the kernel sources</a></li> +<li><a href="#orge17a922">4.2. Kernel dependencies</a></li> +<li><a href="#org3d10772">4.3. Building the kernel</a></li> +</ul> +</li> +<li><a href="#org9ea370c">5. Making your system bootable</a> +<ul> +<li><a href="#org0972750">5.1. Bootloader</a> +<ul> +<li><a href="#org6851c50">5.1.1. GRUB BIOS installation</a></li> +<li><a href="#orgf4bbd79">5.1.2. GRUB UEFI installation</a></li> +</ul> +</li> +<li><a href="#org2e0c9fd">5.2. Init scripts</a></li> +<li><a href="#org3ca705c">5.3. Fstab</a></li> +</ul> +</li> +<li><a href="#org3847026">6. Post-installation</a> +<ul> +<li><a href="#orgdcd7be8">6.1. KISS repositories</a></li> +</ul> +</li> +</ul> +</div> +<div id="outline-container-org3ef8e84" class="outline-2"> +<h2 id="org3ef8e84"><span class="section-number-2">1</span> Preparing Environment</h2> +<div class="outline-text-2" id="text-1"> +<p> +To install Carbs Linux, you will need a Live Linux ISO. For that purpose, you +can obtain a Gentoo or Void Linux live image. You can follow their instructions +to boot and setup your network. +</p> + +<p> +You will need the following programs in order to install Carbs Linux: +</p> + +<ul class="org-ul"> +<li>tar</li> +<li>wget</li> +<li>xz</li> +<li>some form of base utilities (coreutils, sbase, busybox, etc.)</li> +</ul> + +<p> +Rest of these instructions will assume that you have set all of these up, and +will continue on that point. +</p> +</div> + +<div id="outline-container-orgff14f1e" class="outline-3"> +<h3 id="orgff14f1e"><span class="section-number-3">1.1</span> Download</h3> +<div class="outline-text-3" id="text-1-1"> +<p> +First, we need to download the rootfs tarball. You can do the following in order +to obtain the rootfs. If you are using an i686 machine, replace the <code>x86_64</code> +with <code>i686</code>. We are setting this in a URL variable so that we don't have to +write it every time. +</p> + +<div class="org-src-container"> +<pre class="src src-sh">wget $<span class="org-variable-name">URL</span>/carbs-rootfs.tar.xz.sha256 +sha256sum -c carbs-rootfs.tar.xz.sha256 +</pre> +</div> +</div> +</div> + +<div id="outline-container-orgb03d704" class="outline-3"> +<h3 id="orgb03d704"><span class="section-number-3">1.2</span> Signature verification</h3> +<div class="outline-text-3" id="text-1-2"> +<p> +It is highly recommended to verify the signature of the tarball. You will need +GPG for this. +</p> + +<div class="org-src-container"> +<pre class="src src-sh">wget $<span class="org-variable-name">URL</span>/carbs-rootfs.tar.xz.sig +gpg --recv-keys FF484BDFEFCEF8FF +gpg --verify carbs-rootfs.tar.xz.sig +</pre> +</div> +</div> +</div> + +<div id="outline-container-org44c5069" class="outline-3"> +<h3 id="org44c5069"><span class="section-number-3">1.3</span> Extracting the tarball</h3> +<div class="outline-text-3" id="text-1-3"> +<p> +You will need to extract the tarball to your desired location. For partitioning, +you can follow <a href="https://wiki.archlinux.org/index.php/Partitioning">this guide</a>. This will assume that you will be mounting your root +partition to <code>/mnt</code>. +</p> + +<div class="org-src-container"> +<pre class="src src-sh">mount /dev/sdx1 /mnt +tar xf carbs-rootfs.tar.xz -C /mnt +</pre> +</div> +</div> +</div> + +<div id="outline-container-orgea6ba02" class="outline-3"> +<h3 id="orgea6ba02"><span class="section-number-3">1.4</span> Obtain the chroot helper</h3> +<div class="outline-text-3" id="text-1-4"> +<p> +You can obtain the <code>cpt-chroot</code> script in order to do a simple chroot into your +new root filesystem. +</p> + +<div class="org-src-container"> +<pre class="src src-sh">wget https://dl.carbslinux.org/distfiles/cpt-chroot +chmod a+x cpt-chroot +</pre> +</div> +</div> +</div> +</div> + +<div id="outline-container-org32c470a" class="outline-2"> +<h2 id="org32c470a"><span class="section-number-2">2</span> Chroot</h2> +<div class="outline-text-2" id="text-2"> +<p> +Chroot into Carbs Linux! +</p> + +<div class="org-src-container"> +<pre class="src src-sh">./cpt-chroot /mnt +</pre> +</div> +</div> + +<div id="outline-container-orgffe47f7" class="outline-3"> +<h3 id="orgffe47f7"><span class="section-number-3">2.1</span> Setting up repositories</h3> +<div class="outline-text-3" id="text-2-1"> +<p> +Newest tarballs do not come with repositories, so you will need to manually +obtain them, and set your <code>CPT_PATH</code> environment variable. Carbs Linux +repositories can either be obtained by <code>git</code> or <code>rsync</code>. While rsync +repositories are overall faster and smaller, git offers the whole history of the +repository and a means to manipulate your repository as you like it. If you want +to obtain the git repository, you will need to install <code>git</code> itself. +</p> + +<p> +The following guide will assume that you put the repositories into <code>~/repos/</code> +directory, but you can put the repositories into any directory you want. So go +ahead and create that directory: +</p> + +<div class="org-src-container"> +<pre class="src src-sh">mkdir -p $<span class="org-variable-name">HOME</span>/repos +</pre> +</div> +</div> + +<div id="outline-container-org7913b8a" class="outline-4"> +<h4 id="org7913b8a"><span class="section-number-4">2.1.1</span> Obtaining from git</h4> +<div class="outline-text-4" id="text-2-1-1"> +<p> +Carbs Linux git repositories can be found both from the main server and GitHub +(mirror). Here are both their repository links. You can clone any of them. +</p> + +<ul class="org-ul"> +<li>git://git.carbslinux.org/repository</li> +<li><a href="https://github.com/carbslinux/repository">https://github.com/carbslinux/repository</a></li> +</ul> + +<div class="org-src-container"> +<pre class="src src-sh">git clone git://git.carbslinux.org/repository $<span class="org-variable-name">HOME</span>/repos/carbs +</pre> +</div> +</div> +</div> + +<div id="outline-container-org69ce01c" class="outline-4"> +<h4 id="org69ce01c"><span class="section-number-4">2.1.2</span> Obtaining from rsync</h4> +<div class="outline-text-4" id="text-2-1-2"> +<p> +Carbs Linux rsync repositories live in rsync://carbslinux.org/repo. In +order to obtain it, run the following: +</p> + +<div class="org-src-container"> +<pre class="src src-sh">rsync -avc rsync://carbslinux.org/repo $<span class="org-variable-name">HOME</span>/repos/carbs +</pre> +</div> +</div> +</div> + +<div id="outline-container-orge7a96e2" class="outline-4"> +<h4 id="orge7a96e2"><span class="section-number-4">2.1.3</span> Making the package manager use the repositories</h4> +<div class="outline-text-4" id="text-2-1-3"> +<p> +In your shell's configuration file, or in your <code>~/.profile</code> file, add the +following lines: +</p> + +<div class="org-src-container"> +<pre class="src src-sh"><span class="org-variable-name">CPT_PATH</span>=$<span class="org-variable-name">HOME</span>/repos/carbs/core +<span class="org-variable-name">CPT_PATH</span>=$<span class="org-variable-name">CPT_PATH</span>:$<span class="org-variable-name">HOME</span>/repos/carbs/extra +<span class="org-variable-name">CPT_PATH</span>=$<span class="org-variable-name">CPT_PATH</span>:$<span class="org-variable-name">HOME</span>/repos/carbs/xorg +<span class="org-variable-name">CPT_PATH</span>=$<span class="org-variable-name">CPT_PATH</span>:$<span class="org-variable-name">HOME</span>/repos/carbs/community +<span class="org-builtin">export</span> CPT_PATH +</pre> +</div> +</div> +</div> +</div> + +<div id="outline-container-orge7115ca" class="outline-3"> +<h3 id="orge7115ca"><span class="section-number-3">2.2</span> Updating packages</h3> +<div class="outline-text-3" id="text-2-2"> +<p> +It is good practice to make sure your system is up to date, especially before +building new packages. If there is an update for the package manager you will +need to update twice. +</p> + +<div class="org-src-container"> +<pre class="src src-sh">cpt-update && cpt-update +</pre> +</div> +</div> +</div> + +<div id="outline-container-org498cf81" class="outline-3"> +<h3 id="org498cf81"><span class="section-number-3">2.3</span> Installing packages</h3> +<div class="outline-text-3" id="text-2-3"> +<p> +Since you are operating on a really small base, you might need to build and +install new programs to extend the functionality of your system. In order to +build and install packages new packages in Carbs, you need to execute the +following. "Package" is not actually a package and is given as an example. +</p> + +<div class="org-src-container"> +<pre class="src src-sh">cpt-build package +cpt-install package +</pre> +</div> +</div> +</div> + +<div id="outline-container-orgc580a0d" class="outline-3"> +<h3 id="orgc580a0d"><span class="section-number-3">2.4</span> Essential Software</h3> +<div class="outline-text-3" id="text-2-4"> +<p> +Here is a list of software that you might want to have on your system. +</p> + +<p> +<b>BOOTLOADERS</b> +</p> + +<ul class="org-ul"> +<li>efibootmgr</li> +<li>grub</li> +</ul> + +<p> +<b>FILESYSTEMS</b> +</p> + +<ul class="org-ul"> +<li>e2fsprogs</li> +<li>dosfstools</li> +<li>ntfs-3g</li> +</ul> + +<p> +<b>NETWORKING</b> +</p> + +<ul class="org-ul"> +<li>dhcpcd</li> +<li>wpa<sub>supplicant</sub></li> +</ul> + +<p> +<b>TEXT EDITORS</b> +</p> + +<ul class="org-ul"> +<li>nano</li> +<li>vim</li> +<li>neatvi</li> +<li>emacs</li> +<li>emacs-nox (terminal-only version of emacs)</li> +</ul> + +<p> +<b>USER SHELLS</b> +</p> + +<ul class="org-ul"> +<li>bash</li> +<li>zsh</li> +<li>oksh</li> +<li>rc</li> +</ul> + +<p> +<b>POSIX BASE UTILITIES</b> +</p> + +<ul class="org-ul"> +<li>busybox</li> +<li>sbase</li> +<li>coreutils</li> +</ul> + +<p> +<b>DOCUMENTATION</b> +</p> + +<ul class="org-ul"> +<li>carbs-docs</li> +<li>man-pages</li> +<li>man-pages-posix</li> +</ul> +</div> +</div> + +<div id="outline-container-org543d436" class="outline-3"> +<h3 id="org543d436"><span class="section-number-3">2.5</span> Obtaining the documentation</h3> +<div class="outline-text-3" id="text-2-5"> +<p> +All the documentation for Carbs Linux can be found on a single info manual to be +viewed offline. You can obtain texinfo or the info (standalone) package in order +to view the documentation. +</p> + +<div class="org-src-container"> +<pre class="src src-sh"><span class="org-comment-delimiter"># </span><span class="org-comment">Install the documentation.</span> +cpt b carbs-docs && cpt i carbs-docs + +<span class="org-comment-delimiter"># </span><span class="org-comment">Install either texinfo or the info package. We will be installing standalone info</span> +<span class="org-comment-delimiter"># </span><span class="org-comment">as it doesn't need perl.</span> +cpt b info && cpt i info + +<span class="org-comment-delimiter"># </span><span class="org-comment">You can then run info and navigate through the documentation.</span> +info carbslinux +</pre> +</div> +</div> +</div> +</div> + +<div id="outline-container-orgf4a305b" class="outline-2"> +<h2 id="orgf4a305b"><span class="section-number-2">3</span> System Configuration</h2> +<div class="outline-text-2" id="text-3"> +<p> +After you have finished installing some extra packages, you can configure your +system to your liking. +</p> +</div> + +<div id="outline-container-orgbb6f72c" class="outline-3"> +<h3 id="orgbb6f72c"><span class="section-number-3">3.1</span> Configuring hostname</h3> +<div class="outline-text-3" id="text-3-1"> +<p> +You might want to add a hostname, especially in a networked environment. Your +hostname will default to 'carbslinux' unless you set this. +</p> + +<div class="org-src-container"> +<pre class="src src-sh"><span class="org-builtin">echo</span> your-hostname > /etc/hostname +</pre> +</div> +</div> +</div> + +<div id="outline-container-org91ebad2" class="outline-3"> +<h3 id="org91ebad2"><span class="section-number-3">3.2</span> Hosts file</h3> +<div class="outline-text-3" id="text-3-2"> +<p> +You can edit your /etc/hosts file, which is the static lookup table for host +names. By default, there are two entries for localhost which are OKAY. You can +replace the 'localhost' part of these entries to your hostname. +</p> + +<pre class="example" id="org6b852dd"> +127.0.0.1 localhost.localdomain localhost +::1 localhost.localdomain localhost ip6-localhost +</pre> +</div> +</div> +</div> + +<div id="outline-container-orgab5cd50" class="outline-2"> +<h2 id="orgab5cd50"><span class="section-number-2">4</span> Kernel</h2> +<div class="outline-text-2" id="text-4"> +<p> +Kernel isn't managed under the main repositories, even though you could package +one for your personal use. Here is an <a href="https://github.com/cemkeylan/kiss-repository/tree/master/personal/linux">example kernel package</a>, which you will +need to reconfigure for your specific setup if you want to make use of it. +</p> +</div> + +<div id="outline-container-orgbe83919" class="outline-3"> +<h3 id="orgbe83919"><span class="section-number-3">4.1</span> Obtaining the kernel sources</h3> +<div class="outline-text-3" id="text-4-1"> +<p> +You can visit the <a href="https://kernel.org">https://kernel.org</a> website to choose a kernel that you want +to install. Though only the latest stable and longterm (LTS) versions are +supported. +</p> + +<div class="org-src-container"> +<pre class="src src-sh"><span class="org-comment-delimiter"># </span><span class="org-comment">Download the kernel and extract it</span> +wget https://cdn.kernel.org/pub/linux/kernel/v5.x/linux-5.9.1.tar.xz +tar xf linux-5.9.1.tar.xz + +<span class="org-comment-delimiter"># </span><span class="org-comment">Change directory into the kernel sources</span> +<span class="org-builtin">cd</span> linux-5.9.1 +</pre> +</div> +</div> +</div> + +<div id="outline-container-orge17a922" class="outline-3"> +<h3 id="orge17a922"><span class="section-number-3">4.2</span> Kernel dependencies</h3> +<div class="outline-text-3" id="text-4-2"> +<p> +In order to compile the kernel you will need to install some dependencies. You +will need <code>libelf</code>, and <code>bison</code> to compile the kernel. If you want to configure +using the menu interface you will also need <code>ncurses</code>. +</p> + +<div class="org-src-container"> +<pre class="src src-sh"><span class="org-comment-delimiter"># </span><span class="org-comment">The package manager asks to install if you are building more than one package,</span> +<span class="org-comment-delimiter"># </span><span class="org-comment">so no need to run 'cpt i ...'</span> +cpt b libelf ncurses +</pre> +</div> + +<p> +In the vanilla kernel sources, you need perl to compile the kernel, but it can +be easily patched out. You will need to apply the following patch. Patch was +written by <a href="https://github.com/E5ten">E5ten</a>. You will need to obtain and apply the patch in the kernel +source directory. +</p> + +<div class="org-src-container"> +<pre class="src src-sh">wget https://dl.carbslinux.org/distfiles/kernel-no-perl.patch +patch -p1 < kernel-no-perl.patch +</pre> +</div> +</div> +</div> + +<div id="outline-container-org3d10772" class="outline-3"> +<h3 id="org3d10772"><span class="section-number-3">4.3</span> Building the kernel</h3> +<div class="outline-text-3" id="text-4-3"> +<p> +Next step is configuring and building the kernel. You can check Gentoo's +<a href="https://wiki.gentoo.org/wiki/Kernel/Configuration">kernel configuration guide</a> to learn more about the matter. Overall, Gentoo Wiki +is a good place to learn about configuration according to your hardware. The +following will assume a monolithic kernel. +</p> + +<div class="org-src-container"> +<pre class="src src-sh">make menuconfig +make +install -Dm755 $(make -s image_name) /boot/vmlinuz-linux +</pre> +</div> +</div> +</div> +</div> + +<div id="outline-container-org9ea370c" class="outline-2"> +<h2 id="org9ea370c"><span class="section-number-2">5</span> Making your system bootable</h2> +<div class="outline-text-2" id="text-5"> +<p> +In order to be able to boot your fresh system, wou will need an init-daemon, +init-scripts and a bootloader. The init daemon is already provided by busybox, +but you can optionally change it. +</p> +</div> + +<div id="outline-container-org0972750" class="outline-3"> +<h3 id="org0972750"><span class="section-number-3">5.1</span> Bootloader</h3> +<div class="outline-text-3" id="text-5-1"> +<p> +In the main repository, there is efibootmgr and grub to serve as bootloaders. +efibootmgr can be used as a standalone bootloader, or can be used to install +grub in a UEFI environment. efibootmgr is needed unless you are using a device +without UEFI support (or you really want to use BIOS for a reason). +</p> +</div> + +<div id="outline-container-org6851c50" class="outline-4"> +<h4 id="org6851c50"><span class="section-number-4">5.1.1</span> GRUB BIOS installation</h4> +<div class="outline-text-4" id="text-5-1-1"> +<div class="org-src-container"> +<pre class="src src-sh">cpt b grub && cpt i grub +grub-install --target=i386-pc /dev/sdX +grub-mkconfig -o /boot/grub/grub.cfg +</pre> +</div> +</div> +</div> + +<div id="outline-container-orgf4bbd79" class="outline-4"> +<h4 id="orgf4bbd79"><span class="section-number-4">5.1.2</span> GRUB UEFI installation</h4> +<div class="outline-text-4" id="text-5-1-2"> +<div class="org-src-container"> +<pre class="src src-sh">cpt b efibootmgr && cpt i efibootmgr +cpt b grub && cpt i grub + +grub-install --target=x86_64-efi <span class="org-sh-escaped-newline">\</span> + --efi-directory=esp <span class="org-sh-escaped-newline">\</span> + --bootloader-id=CarbsLinux + +grub-mkconfig -o /boot/grub/grub.cfg +</pre> +</div> +</div> +</div> +</div> + +<div id="outline-container-org2e0c9fd" class="outline-3"> +<h3 id="org2e0c9fd"><span class="section-number-3">5.2</span> Init scripts</h3> +<div class="outline-text-3" id="text-5-2"> +<p> +Only thing left to do is installing the init-scripts, and now you are almost +ready to boot your system! +</p> + +<div class="org-src-container"> +<pre class="src src-sh">cpt b carbs-init && cpt i carbs-init +</pre> +</div> +</div> +</div> + +<div id="outline-container-org3ca705c" class="outline-3"> +<h3 id="org3ca705c"><span class="section-number-3">5.3</span> Fstab</h3> +<div class="outline-text-3" id="text-5-3"> +<p> +You can now manually edit your fstab entry, or you can use the genfstab tool. +If you want to use the tool, exit the chroot and run the following: +</p> + +<div class="org-src-container"> +<pre class="src src-sh">wget https://github.com/cemkeylan/genfstab/raw/master/genfstab +chmod +x genfstab +./genfstab -U /mnt >> /mnt/etc/fstab +</pre> +</div> +</div> +</div> +</div> + +<div id="outline-container-org3847026" class="outline-2"> +<h2 id="org3847026"><span class="section-number-2">6</span> Post-installation</h2> +<div class="outline-text-2" id="text-6"> +<p> +The base installation is now complete, you can now fine tune your system +according to your needs. Rest of these instructions are completely optional. +You can check the rest of the documentation to learn more about the system. +</p> +</div> + +<div id="outline-container-orgdcd7be8" class="outline-3"> +<h3 id="orgdcd7be8"><span class="section-number-3">6.1</span> KISS repositories</h3> +<div class="outline-text-3" id="text-6-1"> +<p> +While not 100% compatible with cpt, you can use kiss repositories in your +system the same way you are using the distribution repositories. Here is an +example for the KISS Linux Community repository. +</p> +</div> +</div> +</div> +</div> +<div id="postamble" class="status"> +<footer> + <p>Linux® is a registered trademark of Linus Torvalds</p> + <p>Copyright © 2019-2021 Cem Keylan</p> +</footer> +</div> +</body> +</html> |