diff --git a/content/learning-paths/laptops-and-desktops/chrome-os-lxc/_images/chromeos-shell.png b/content/learning-paths/laptops-and-desktops/chrome-os-lxc/_images/chromeos-shell.png new file mode 100644 index 0000000000..0611fafa46 Binary files /dev/null and b/content/learning-paths/laptops-and-desktops/chrome-os-lxc/_images/chromeos-shell.png differ diff --git a/content/learning-paths/laptops-and-desktops/chrome-os-lxc/_images/shared-folders.png b/content/learning-paths/laptops-and-desktops/chrome-os-lxc/_images/shared-folders.png new file mode 100644 index 0000000000..85bf90ce40 Binary files /dev/null and b/content/learning-paths/laptops-and-desktops/chrome-os-lxc/_images/shared-folders.png differ diff --git a/content/learning-paths/laptops-and-desktops/chrome-os-lxc/_index.md b/content/learning-paths/laptops-and-desktops/chrome-os-lxc/_index.md new file mode 100644 index 0000000000..1ce1b789e7 --- /dev/null +++ b/content/learning-paths/laptops-and-desktops/chrome-os-lxc/_index.md @@ -0,0 +1,48 @@ +--- +title: Install Ubuntu on ChromeOS Crostini as an LXC Container + +draft: true +cascade: + draft: true + +minutes_to_complete: 60 + +who_is_this_for: This Learning Path is for software developers who want to install Ubuntu and other Linux distributions on their Arm-based Chromebook with ChromeOS file sharing and GUI support. + +learning_objectives: + - Create an Ubuntu 24.04 container on ChromeOS Crostini using the Termina shell and LXC. + - Set up ChromeOS integration for file sharing and GUI applications. + - Manage LXC containers on ChromeOS. + +prerequisites: + - A ChromeOS device with the Linux development environment enabled. The Lenovo Chromebook Plus 14 is recommended. + - Basic knowledge of the Linux command line. + +author: Jason Andrews + +### Tags +skilllevels: Introductory +subjects: Containers and Virtualization +armips: + - Cortex-A +operatingsystems: + - ChromeOS +tools_software_languages: + - Ubuntu + +further_reading: + - resource: + title: Official ChromeOS Linux Support + link: https://chromeos.dev/en/linux + type: documentation + - resource: + title: Linux Containers + link: https://linuxcontainers.org/ + type: website + +### FIXED, DO NOT MODIFY +# ================================================================================ +weight: 1 # _index.md always has weight of 1 to order correctly +layout: "learningpathall" # All files under learning paths have this same wrapper +learning_path_main_page: "yes" # This should be surfaced when looking for related content. Only set for _index.md of learning path content. +--- diff --git a/content/learning-paths/laptops-and-desktops/chrome-os-lxc/_next-steps.md b/content/learning-paths/laptops-and-desktops/chrome-os-lxc/_next-steps.md new file mode 100644 index 0000000000..825303482f --- /dev/null +++ b/content/learning-paths/laptops-and-desktops/chrome-os-lxc/_next-steps.md @@ -0,0 +1,6 @@ +--- +weight: 21 +title: "Next Steps" +layout: "learningpathall" +--- + diff --git a/content/learning-paths/laptops-and-desktops/chrome-os-lxc/chromeos-shell.png b/content/learning-paths/laptops-and-desktops/chrome-os-lxc/chromeos-shell.png new file mode 100644 index 0000000000..0611fafa46 Binary files /dev/null and b/content/learning-paths/laptops-and-desktops/chrome-os-lxc/chromeos-shell.png differ diff --git a/content/learning-paths/laptops-and-desktops/chrome-os-lxc/page-1.md b/content/learning-paths/laptops-and-desktops/chrome-os-lxc/page-1.md new file mode 100644 index 0000000000..432390867a --- /dev/null +++ b/content/learning-paths/laptops-and-desktops/chrome-os-lxc/page-1.md @@ -0,0 +1,132 @@ +--- +title: "Create an Ubuntu container" +weight: 2 +layout: "learningpathall" +--- + +The [Lenovo Chromebook Plus 14](https://www.bestbuy.com/site/lenovo-chromebook-plus-14-oled-2k-touchscreen-laptop-mediatek-kompanio-ultra-16gb-memory-256gb-ufs-seashell/6630493.p?skuId=6630493&intl=nosplash) is is powered by the MediaTek Kompanio Ultra processor, featuring an Arm-based MediaTek Kompanio Ultra processor, offers software developers a powerful and energy-efficient platform for Linux development. Its compatibility with containerized environments and support for ChromeOS Linux (Crostini) make it an excellent choice for coding, testing, and running modern development workflows on the go. + +This Learning Path will walk you through setting up an Ubuntu 24.04 container on your Arm-based Chromebook using ChromeOS's built-in Linux development environment. You'll learn how to create and manage containers, install essential development tools, and integrate your Ubuntu environment with ChromeOS features like file sharing and GUI application support. By the end, you'll have a flexible and powerful Arm Linux development environment. + +## Access the ChromeOS terminal + +The first step to creating an Ubuntu container on ChromeOS is to open the ChromeOS shell. + +Open the Chrome browser and press **Ctrl + Alt + T** to open crosh, the ChromeOS shell, crosh. + +![ChromeOS shell #center](_images/chromeos-shell.png) + +Run the command below to start the Termina shell. + +```console +vsh termina +``` + +You are now in the Termina environment where you can manage containers. + +The `lxc` command is used to manage containers on ChromeOS. + +You can list the running containers. + +```console +lxc list +``` + +If you have the default Debian container running you see output similar to: + +```output ++---------+---------+-----------------------+------+-----------+-----------+ +| NAME | STATE | IPV4 | IPV6 | TYPE | SNAPSHOTS | ++---------+---------+-----------------------+------+-----------+-----------+ +| penguin | RUNNING | 100.115.92.204 (eth0) | | CONTAINER | 0 | ++---------+---------+-----------------------+------+-----------+-----------+ +``` + +The name of the Debian container is penguin. When you enable the Linux subsystem on ChromeOS the Debian container named penguin is created, but you can create additional containers with different Linux distributions and different names. + +## Create a Ubuntu 24.04 container + +This command creates and starts a new Ubuntu 24.04 container named `u1`. + +```bash +lxc launch ubuntu:24.04 u1 +``` + +The output is: + +```output +Creating u1 +Starting u1 +``` + +Check the status of the new container and confirm the status is RUNNING. + +```bash +lxc list +``` + +Now there are 2 containers running. + +```output ++---------+---------+-----------------------+------+-----------+-----------+ +| NAME | STATE | IPV4 | IPV6 | TYPE | SNAPSHOTS | ++---------+---------+-----------------------+------+-----------+-----------+ +| penguin | RUNNING | 100.115.92.204 (eth0) | | CONTAINER | 0 | ++---------+---------+-----------------------+------+-----------+-----------+ +| u1 | RUNNING | 100.115.92.206 (eth0) | | CONTAINER | 0 | ++---------+---------+-----------------------+------+-----------+-----------+ +``` + +Create a new shell in the Ubuntu container. + +```bash +lxc exec u1 -- bash +``` + +## Complete the Ubuntu setup + +Once inside the Ubuntu container, you need to perform some initial setup tasks. + +Update the package lists and upgrade installed packages to the latest versions. + +```bash +apt update && apt upgrade -y +``` + +Install essential packages for development and system management. You can select your favorite software packages, these are examples. + +```bash +apt install -y net-tools gcc +``` + +Creating a non-root user is a crucial security best practice and ensures that applications don't have unnecessary administrative privileges. The username `ubuntu` is already available in the container. You are free to use `ubuntu` as your non-root user or create a new user. + +{{% notice Note %}} +The following commands use `user1` as a new username. You can replace it with your actual desired username in all subsequent steps. +{{% /notice %}} + +Create a new user account. Skip if you want to use the `ubuntu` user. + +```bash +adduser user1 +``` + +Add the new user to the sudo group to grant administrative privileges. Skip if you want to use the `ubuntu` user. + +```bash +usermod -aG sudo user1 +``` + +Switch to your new user account to continue the setup. + +```bash +su - user1 +``` + +If you didn't creat a new user switch to `ubuntu` as the non-root user. + +```bash +su - ubuntu +``` + +Continue to learn how to integrate the new Ubuntu container with ChromeOS features like file sharing. \ No newline at end of file diff --git a/content/learning-paths/laptops-and-desktops/chrome-os-lxc/page-2.md b/content/learning-paths/laptops-and-desktops/chrome-os-lxc/page-2.md new file mode 100644 index 0000000000..5487c9a61f --- /dev/null +++ b/content/learning-paths/laptops-and-desktops/chrome-os-lxc/page-2.md @@ -0,0 +1,97 @@ +--- +title: ChromeOS integration +weight: 3 +layout: "learningpathall" +--- + +## File sharing between ChromeOS and Linux + +Chromebooks with Linux offer convenient file sharing capabilities between the main ChromeOS environment and the Linux subsystem. + +Key Features: + +- Selective Folder Sharing: ChromeOS allows you to share specific folders (not individual files) from the native files app with the Linux container. This is done by right-clicking a folder and selecting "Share with Linux." Once shared, these directories become accessible to Linux apps and the command line within the Linux environment. + +- Two-Way Access: Files and folders created within the Linux container appear in the "Linux files" section of the ChromeOS Files app, enabling seamless movement of data between environments. + +- Sandboxed Security: The Linux environment is sandboxed for security, meaning it doesn't have access to the full ChromeOS file system by default. Only the folders explicitly shared by the you are visible in Linux, ensuring protected data separation. + +- Easy Integration: Shared folders can be navigated from Linux at paths such as /mnt/chromeos/MyFiles/. Applications and command-line tools within Linux can read and write to these shared folders. + +- Management Tools: You can manage and revoke shared folder access through the ChromeOS Files app, allowing for flexible control over what is accessible to Linux. + +These features make it simple to move files between ChromeOS and Linux applications while maintaining security and user control. + +## Configure File System Integration + +### Share ChromeOS directories + +To access your ChromeOS files from within the Ubuntu container, you need to configure shared directories. + +You can share directories using the ChromeOS File application. Right click on any directory and select **Share with Linux**. + +If you share a ChromeOS directory it appears in `/mnt/chromeos/MyFiles/` in your Ubuntu container. For example, share your Downloads directory in ChromeOS and it is visible in Ubuntu. + +```bash +ls /mnt/chromeos/MyFiles/Downloads/ +``` + +### Share Google Drive directories + +You can also share Google Drive directories using the ChromeOS Files application. Use the same right click and select **Share with Linux**. + +If you share a Google Drive folder it appears in `/mnt/chromeos/GoogleDrive/MyDrive/` in your Ubuntu container. For example, share your `AndroidAssets` directory in Google Drive it is visible in Ubuntu. + +```bash +ls /mnt/chromeos/GoogleDrive/MyDrive/AndroidAssets +``` + +Your shared folders appear in the **Linux Settings** under **Manage shared folders** as shown below: + +![Shared folders #center](_images/shared-folders.png) + +### Share a folder using the command line + +You can use the commands below from the Termina shell. + +Mount the entire ChromeOS file system to /mnt/chromeos in the container. + +```bash +lxc config device add ubuntu-main shared-chromeos disk source=/mnt/chromeos path=/mnt/chromeos +``` + +Share your ChromeOS Downloads folder with the container + +```bash +lxc config device add ubuntu-main downloads disk source=/mnt/chromeos/MyFiles/Downloads path=/home/username/Downloads +``` + +Share your ChromeOS Documents folder with the container. + +```bash +lxc config device add ubuntu-main documents disk source=/mnt/chromeos/MyFiles/Documents path=/home/username/Documents +``` + +## File Operations + +You can use the `lxc file` command to copy files to and from a container from the Termina shell. + +As an example create a file named file1 + +```bash +echo "test file 1" >> /mnt/shared/MyFiles/Downloads/file1 +``` + +Copy the file from your ChromeOS Downloads folder to the tmp directory in the container. + +```bash +lxc file push file1 u1/tmp/file1 +``` + +Copy the same file back to the Downloads directory with a new name. + +```bash +lxc file pull u1/tmp/file1 file2 +``` + +You now have the file in your Downloads directory with a new name. diff --git a/content/learning-paths/laptops-and-desktops/chrome-os-lxc/page-3.md b/content/learning-paths/laptops-and-desktops/chrome-os-lxc/page-3.md new file mode 100644 index 0000000000..7b1bce81a9 --- /dev/null +++ b/content/learning-paths/laptops-and-desktops/chrome-os-lxc/page-3.md @@ -0,0 +1,96 @@ +--- +title: Enable desktop applications +weight: 4 +layout: "learningpathall" +--- + +To use desktop applications like browsers in the Ubuntu container you need to enable the connection to the ChromeOS desktop using Sommelier. + +Sommelier acts as a bridge, enabling seamless integration and smooth operation of Linux apps within the ChromeOS environment. + +## Enable GUI Application Support + +Install a minimal desktop environment to provide the necessary libraries for graphical applications. + +```bash +sudo apt install -y xubuntu-desktop-minimal +``` + +Install a test application. + +```bash +sudo apt install -y terminator +``` + +Configure the display environment variables to ensure GUI applications know where to render their windows + +```console +echo 'export DISPLAY=:0' >> ~/.bashrc +``` + +Install the necessary tools to build Sommelier. + +```bash +sudo apt install -y clang meson libwayland-dev cmake pkg-config libgbm-dev libdrm-dev libxpm-dev libpixman-1-dev libx11-xcb-dev libxcb-composite0-dev libxkbcommon-dev libgtest-dev python3-jinja2 +``` + +You need to build Sommelier from source code because it is not available in Ubuntu repositories. + +```bash +git clone https://chromium.googlesource.com/chromiumos/platform2 +cd platform2/vm_tools/sommelier +meson build +cd build +ninja +sudo ninja install +``` + +Sommelier is now installed in `/usr/local/bin/` + +Create a systemd user unit file for X11 support. + +```bash +mkdir -p ~/.config/systemd/user +``` + +Use a text editor to create the file `~/.config/systemd/user/sommelier@.service` with the contents below. + +```ini +[Unit] +Description=Sommelier X11 bridge instance %i + +[Service] +Environment=DISPLAY=:0 +ExecStart=/usr/local/bin/sommelier -X --scale=1 --no-exit-with-child -- /bin/true +Restart=on-failure + +[Install] +WantedBy=default.target +``` + +Reload the Systemd user manager and start the Sommelier service. + +```bash +systemctl --user daemon-reload +systemctl --user enable --now sommelier@0.service +``` + +Confirm the Sommelier service is running. + +```bash +systemctl --user status sommelier@0.service +``` + +Test a graphical application works. You can pick other applications to try. + +```bash +terminator & +``` + +You should see a new terminal open on your ChromeOS desktop. + +If needed, you can restart Sommelier. + +```bash +sudo systemctl restart sommelier@0 +``` \ No newline at end of file diff --git a/content/learning-paths/laptops-and-desktops/chrome-os-lxc/page-4.md b/content/learning-paths/laptops-and-desktops/chrome-os-lxc/page-4.md new file mode 100644 index 0000000000..e3b6e07f2b --- /dev/null +++ b/content/learning-paths/laptops-and-desktops/chrome-os-lxc/page-4.md @@ -0,0 +1,183 @@ +--- +title: Learn more Linux Container commands +weight: 5 +layout: "learningpathall" +--- + +## Container Management + +Now that you have the basics, here are some useful commands for managing your container from the Termina shell. + +Start a stopped container. + +```bash +lxc start u1 +``` + +Stop a running container. + +```bash +lxc stop u1 +``` + +Enter the container's shell. + +```bash +lxc exec u1 -- bash +``` + +List all available containers and their status. + +```bash +lxc list +``` + +Delete a container. This is a permanent action. + +```bash +lxc delete u1 +``` + +Print additional container information. + +```bash +lxc info u1 +``` + +The output is similar to: + +```output +Name: u1 +Status: RUNNING +Type: container +Architecture: aarch64 +PID: 24141 +Created: 2025/08/07 04:46 EDT +Last Used: 2025/08/07 04:46 EDT + +Resources: + Processes: 120 + CPU usage: + CPU usage (in seconds): 384 + Memory usage: + Memory (current): 1.58GiB + Memory (peak): 4.86GiB + Network usage: + eth0: + Type: broadcast + State: UP + Host interface: veth7df9a2e6 + MAC address: 00:16:3e:18:59:08 + MTU: 1500 + Bytes received: 1.28GB + Bytes sent: 6.11MB + Packets received: 308930 + Packets sent: 83115 + IP addresses: + inet: 100.115.92.202/28 (global) + inet6: fe80::216:3eff:fe18:5908/64 (link) +``` + +Add the Google Debian container to your list of containers you can install. + +```bash +lxc remote add google https://storage.googleapis.com/cros-containers --protocol=simplestreams +``` + +List the remote containers. + +```bash +lxc remote list +``` + +The output is similar to: + +```output ++-----------------+------------------------------------------------+---------------+-------------+--------+--------+--------+ +| NAME | URL | PROTOCOL | AUTH TYPE | PUBLIC | STATIC | GLOBAL | ++-----------------+------------------------------------------------+---------------+-------------+--------+--------+--------+ +| google | https://storage.googleapis.com/cros-containers | simplestreams | none | YES | NO | NO | ++-----------------+------------------------------------------------+---------------+-------------+--------+--------+--------+ +| images | https://images.linuxcontainers.org | simplestreams | none | YES | NO | NO | ++-----------------+------------------------------------------------+---------------+-------------+--------+--------+--------+ +| local (current) | unix:// | lxd | file access | NO | YES | NO | ++-----------------+------------------------------------------------+---------------+-------------+--------+--------+--------+ +| ubuntu | https://cloud-images.ubuntu.com/releases | simplestreams | none | YES | YES | NO | ++-----------------+------------------------------------------------+---------------+-------------+--------+--------+--------+ +| ubuntu-daily | https://cloud-images.ubuntu.com/daily | simplestreams | none | YES | YES | NO | ++-----------------+------------------------------------------------+---------------+-------------+--------+--------+--------+ +``` + +Using the `images` remote you can create a container with images from [Linux Containers](https://images.linuxcontainers.org/). + +For example, to start Alpine Linux 3.22 run: + +```bash +lxc launch images:alpine/3.22 a1 +``` + +## Configure container auto-start + +From the Termina shell, you can configure the container to start automatically when you start the Linux development environment. + +```bash +# Set the container to start automatically +lxc config set u1 boot.autostart true + +# Set the startup priority. A lower number means a higher priority. +lxc config set u1 boot.autostart.priority 1 +``` + +## Save and restore + +Once you have a container configured with your preferences, you can save it and use the backup to create new containers. + +Follow the steps below to save and restore a container from the Termina shell. + +### Create a Backup + +First, stop the running container to ensure a consistent state. + +```bash +lxc stop u1 +``` + +Save the container to a compressed tar file using the `export` command. + +```bash +lxc export u1 my-ubuntu.tar.gz +``` + +Save the backup file to your Google Drive or another easy to access location. + +### Create a new container from the backup + +Import the backup file to create a new container + +```bash +lxc import my-ubuntu.tar.gz u2 +``` + +Now you have a fresh container named `u2` at the same state you saved the backup. + +## Performance Tips + +For a smoother experience, especially on devices with limited resources, you can monitor and manage your container's performance. + +### Limit Container Resources + +You can configure resource limits for your container from the Termina shell. This can prevent the container from consuming too many system resources. + +Limit the container to 2 CPU cores. + +```bash +lxc config set u1 limits.cpu 4 +``` + +You can confirm using the Linux `lscpu` command and on an 8-core system you will see 4 cores have been moved to offline. + +Limit the container to 2GB of RAM. + +```bash +lxc config set u1 limits.memory 2GB +```