training/tutorial-creating-an-ubuntu-container-with-distrobox.md

@@ -2,4 +2,80 @@
 
 [[_TOC_]]
 
-#
+# Quick Glossary
+
+- Host = Your Linux installation. "Outside" of the Distrobox container.
+
+- "Enter a Distrobox". Your shell is now inside of the Distrobox. Here are various ways to think about it:
+  - "Entering" the Distrobox.
+  - "Enabling" the Distrobox.
+  - "Opening" the Distrobox.
+
+# What is Distrobox?
+
+[Distrobox](https://distrobox.privatedns.org/) is a tool that lets you run (almost) any Linux distribution or distribution version. It is built on top of Docker containers.
+
+For our use case, you'll be using Distrobox to run a specific Ubuntu version on your existing Linux installation. Your Linux installation does not need to be Ubuntu.
+
+# Installing Distrobox
+
+Official instructions: https://distrobox.privatedns.org/#installation
+
+If Distrobox is already packaged for your Linux distribution, you can install it with your package manager. If you're on the latest version of your distribution, Distrobox is probably available in the package repositories.
+
+Otherwise follow the "Curl or Wget" instructions.
+
+# Creating the Ubuntu container
+
+By default Distrobox does not create a separate home directory for the container, and the container will just use your host home directory. We will want to modify the shell configuration for ROS, so we will need a home directory for the container.
+
+I like to store the home directories for my Distroboxes under `~/distrobox/`. --- Jeff
+
+```sh
+mkdir -p ~/distrobox/ram
+```
+
+Now, create the Distrobox container. We will use the container name "ram", but you can use whatever name you want.
+
+```sh
+distrobox create --name ram --home ~/distrobox/ram --image ubuntu:focal
+```
+
+Creation should be quick, though it may take a few minutes if it needs to download the `ubuntu:focal` image for the first time.
+
+Once it's done, enter the Distrobox to finish the setup:
+
+```sh
+distrobox enter ram
+```
+
+Now you're done, and can move onto [Tutorial: Setting up ROS](/training/tutorial-setting-up-ros).
+
+# Things to know about Distrobox
+
+- You will have access to your regular files. Your home directory automatically be mounted.
+  - Note that this means you can **delete** your regular files! And remember that the `rm` command **cannot be undone**! Consider installing `trash-cli` and using the `trash` command, or using a GUI file manager to delete files that sends them to trash.
+- You will have a separate root directory.
+  - You won't easily be able to access your host root directory.
+  - Programs you have installed in the Distrobox won't automatically show up on your host, and vice versa. The Distrobox container is its own separated box where you can install stuff.
+- `sudo` inside the Distrobox is not the same as `sudo` outside.
+  - If you're using Podman instead of Docker, this is definitely the case because Podman is intended to run without root.
+  - You won't need a password to use `sudo` inside the Distrobox.
+
+# FAQ
+
+## Inside the Distrobox, run a program on the host
+
+This can be convenient if you don't want to install a common program in the Distrobox, or need to access the version on your host and don't want to open a new terminal.
+
+Use the `distrobox-host-exec` command. For example:
+
+```
+user@distrobox:~$ git
+bash: git: command not found
+user@distrobox:~$ distrobox-host-exec git
+```
+
+To make it easier to use you can add a Bash alias.
+
+I alias `distrobox-host-exec` to `h` so it is very quick to type. --- Jeff