# Building Container-Optimized OS from source

Container-Optimized OS is based on, and built using, tools from the
open-source [Chromium OS](http://www.chromium.org/chromium-os)
project. If you like, you can build a Container-Optimized OS image yourself
directly from the Container-Optimized OS source code.

## Prerequisites

To build a Container-Optimized OS image, you'll need to install the following
tools on your development machine:

- `git` and `curl`
- A package of Chromium scripts called [`depot_tools`](http://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools_tutorial.html) that includes tools like `repo` and `cros_sdk`.

## Obtaining the Container-Optimized OS source code

You can download the source code for Container-Optimized OS by using the
`repo` tool that is included in `depot_tools`.

First, create a directory to store the source code. For example, `cos-src` in
your home directory:

    mkdir $HOME/cos-src
    cd $HOME/cos-src

Now download source code using the following commands:

    repo init https://cos.googlesource.com/cos/manifest.git
    repo sync

> [!NOTE]
> **Note:** Depending on your network speed, downloading the source code may take several minutes.

## Building a Container-Optimized OS image

To build Container-Optimized OS, you must create a suitable `chroot`
environment. You can use the `cros_sdk` tool included in `depot_tools` to create
and enter a `chroot` that's ready for Container-Optimized OS compilation by
running the following command in the source directory that you created in the
previous step:

    cd $HOME/cos-src
    cros_sdk --enter

Once inside `chroot`, you can build the disk image. To build
Container-Optimized OS, specify `lakitu` (x86 image) or `lakitu-arm64`
(Arm image) for the board name as follows:

### x86 image

       build_packages --board=lakitu
       build_image --board=lakitu test

### Arm image

       build_packages --board=lakitu-arm64
       build_image --board=lakitu-arm64 test

In addition to **`test`** , you can build either a **`base`** , or **`dev`** image
by passing the appropriate parameter to the `./build image` script command. If
you don't specify a parameter, *the `dev` image is built by default*.

The `dev` image contains some additional debug tools installed on top of the
`base` image. The `test` image includes the debug tools from the `dev` image as
well as tools necessary for running automatic Container-Optimized OS tests.

> [!NOTE]
> **Note:** You can log into a `test` image as the root user with the password "test0000", which can be useful if the SSH service is not accessible.

## Attribution Requirements

When you produce a Container-Optimized OS image, you need to fulfill various
attribution requirements of third party licenses. The image generated by a build
contains all relevant attribution information in
`/opt/google/chrome/resources/about_os_credits.html`. As a separate build
artifact it is also available as `license_credits.html` file in the build output
directory.

## Running Your Image

Once you've built your Container-Optimized OS image, you can run the image
using KVM, or import the image to a [Compute Engine](https://docs.cloud.google.com/compute) instance.

### Running in hypervisor

To boot your image in hypervisor, run the following command:

### x86 image

       kvm -m 1024 -nographic -net nic,model=virtio -net user,hostfwd=tcp:127.0.0.1:9222-:22 -hda src/build/images/lakitu/latest/chromiumos_test_image.bin

### Arm image

       sudo apt-get install qemu-system-arm qemu-efi

       dd if=/dev/zero of=/tmp/flash0.img bs=1M count=64
       dd if=/usr/share/qemu-efi/QEMU_EFI.fd of=/tmp/flash0.img conv=notrunc

       sudo qemu-system-aarch64 -m 1024 -cpu cortex-a57 -M virt -nographic \
             -pflash /tmp/flash0.img \
             -device virtio-scsi-pci,id=scsi \
             -drive if=none,file=src/build/images/lakitu-arm64/latest/chromiumos_test_image.bin,id=hd0 \
             -device scsi-hd,drive=hd0,bootindex=0 \
             -net nic \
             -net user,hostfwd=tcp::9222-:22
       
Booting in this manner leaves the VM's serial port connected to your console,
letting you log in without using SSH. If you're running a `test` image, you can
log in with the username/password pair "root/test0000".

Once the VM is started, you can access your `dev` or `test` image using SSH. To
SSH into the image, use the key generated for that image, as follows:

### x86 image

       ssh root@localhost -p 9222 -i src/build/images/lakitu/latest/id_rsa

### Arm image

       ssh root@localhost -p 9222 -i src/build/images/lakitu-arm64/latest/id_rsa

### Running on Compute Engine

To import your image to a Compute Engine instance, you must compress the image
into a `.tar` file. To compress the image, run the following command:

### x86 image

       tar -Sczf compressed-image.tar.gz images/lakitu/latest/chromiumos_image.bin --transform 's|images/lakitu/latest/chromiumos_image.bin|disk.raw|'

### Arm image

       tar -Sczf compressed-image.tar.gz images/lakitu-arm64/latest/chromiumos_image.bin --transform 's|images/lakitu-arm64/latest/chromiumos_image.bin|disk.raw|'

After you've created your `.tar` file, you can follow the instructions to
[import an existing image](https://docs.cloud.google.com/compute/docs/images/import-existing-image#import_image)
in the Compute Engine documentation.