# Use Docker to Compile Linux for ESP32-S3
## Overview
https://www.youtube.com/live/f6ZhVPpiNzM?
Have you ever wanted to run Linux on a microcontroller like the ESP32-S3? GitHub user [jcmvbkbc](https://github.com/jcmvbkbc) has a [Linux for ESP32-S3 script](https://gist.github.com/jcmvbkbc/316e6da728021c8ff670a24e674a35e6) that lets you do just that! However, compiling it can be tricky depending on your operating system with all of the toolchain dependencies. Don't worry though because there is a way around all of that: [a Docker container](https://www.hanselman.com/blog/docker-101-and-how-do-containers-work)! A container is a lightweight and fast virtual computer. The best part is it's easy for people to run no matter what operating system they are on. It's also much simpler and smaller than VirtualBox because it has only the bare essentials.
In this guide, you'll setup and install Docker, run a test Dockerfile to create a test container, run the ESP32-S3 Linux Dockerfile, upload the compiled files to the ESP32-S3 and then perform the ultimate skateboard trick: boot Linux on an ESP32-S3!
This version of Linux is barebones, the file system is utilizing [cramfs](https://en.wikipedia.org/wiki/Cramfs), so don't expect it to be like booting up a Raspberry Pi with Raspberry Pi OS. You'll access it over serial and you'll only be able to do super basic things but you'll learn a ton along the way.
## Parts
### Adafruit Metro ESP32-S3 with 16 MB Flash 8 MB PSRAM
[Adafruit Metro ESP32-S3 with 16 MB Flash 8 MB PSRAM](https://www.adafruit.com/product/5500)
What's Metro-shaped and has an ESP32-S3 WiFi module? What has a STEMMA QT connector for I2C devices and a Lipoly charger circuit? What has your favorite Espressif WiFi microcontroller and lots of memory for your next IoT project?
That's right - it's the new...
In Stock
[Buy Now](https://www.adafruit.com/product/5500)
[Related Guides to the Product](https://learn.adafruit.com/products/5500/guides)
### USB to TTL Serial Cable - Debug / Console Cable for Raspberry Pi
[USB to TTL Serial Cable - Debug / Console Cable for Raspberry Pi](https://www.adafruit.com/product/954)
The cable is easiest way ever to connect to your microcontroller/Raspberry Pi/WiFi router serial console port. Inside the big USB plug is a USB\<-\>Serial conversion chip and at the end of the 36" cable are four wire - red power, black ground, white RX into USB port, and green TX out...
In Stock
[Buy Now](https://www.adafruit.com/product/954)
[Related Guides to the Product](https://learn.adafruit.com/products/954/guides)
### Break-away 0.1" 36-pin strip male header - Black - 10 pack
[Break-away 0.1" 36-pin strip male header - Black - 10 pack](https://www.adafruit.com/product/392)
Breakaway header is like the duct tape of electronics. It's great for connecting things together, soldering to perf-boards, fits into any breakout or breadboard, etc. We go through these guys real fast, and thought that given how handy they are, we'd offer them in a pack of ten!
Out of Stock
[Buy Now](https://www.adafruit.com/product/392)
[Related Guides to the Product](https://learn.adafruit.com/products/392/guides)
### USB Type A to Type C Cable - approx 1 meter / 3 ft long
[USB Type A to Type C Cable - approx 1 meter / 3 ft long](https://www.adafruit.com/product/4474)
As technology changes and adapts, so does Adafruit. This **USB Type A to Type C** cable will help you with the transition to USB C, even if you're still totin' around a USB Type A hub, computer or laptop.
USB C is the latest industry-standard connector for...
In Stock
[Buy Now](https://www.adafruit.com/product/4474)
[Related Guides to the Product](https://learn.adafruit.com/products/4474/guides)
# Use Docker to Compile Linux for ESP32-S3
## Install Docker
Go to the [Docker website](https://www.docker.com/) and download the Docker version for your operating system. Then, launch the installer file that downloads.
After installation finishes, you may be prompted to logout of your system to finish setting things up.
When Docker launches for the first time, you'll be prompted with a service agreement. Click **Accept**.
Then you'll be prompted to sign up for a Docker account. Click the **Sign Up** button to create an account.
After creating an account on the Docker website, you'll be prompted to login for the first time. After logging in, you'll need to select a plan. There is a free plan for Docker ( **Personal** ) and everything covered in this guide works with the free tier.
Then you can log into the Docker desktop application, where you can access your containers and images.
Next, you'll create a test Docker image to get used to how Docker works and check your workflow.
# Use Docker to Compile Linux for ESP32-S3
## Docker Test Image
Before you go diving into compiling the Linux kernel, you can run this quick test Docker image to get familiar with Docker.
First, you're going to create a Dockerfile file. These files are run to create the Docker images and they use their own syntax. Copy and paste the following text into your preferred text editor:
```auto
FROM ubuntu:22.04
RUN apt-get update
ENTRYPOINT ["tail", "-f", "/dev/null"]
```
Then, save the file as **Dockerfile** with no file extension. The Dockerfile you just created builds an Ubuntu 22.04 system. Then, it runs `apt-get update` and opens a terminal window for you to interact with the system. If you were to leave out the `ENTRYPOINT` line, the image would simply run `apt-get update` and then close down.
Next, open up a terminal and navigate to the folder where you just saved your Dockerfile. Run the following command to build the image:
`docker build -t docker_test .`
This tells docker to build the Dockerfile as an image and tag it (name it) as **docker\_test**.
After running the command, you'll see Docker go through a series of build steps and then finish.
Go to your Docker desktop application and click on the **Images** tab. You should see your **docker\_test** image that you just built.
The image is static, similar to creating a USB drive with installation media if you've ever done a fresh install of Windows or Linux on hardware. To deploy the image that you just built, click on the **Play** button next to the image name. A dialog box will open and you'll click **Run**.
This launches your image into a container. The container is where your virtual computer lives and runs. It is given the name of an adjective along with the name of a scientist as a nickname by default.
If you click on the **Terminal** tab in the container, you can interact with your new Ubuntu image.
On the main Containers page, you can start or stop your container from running by clicking the **Play** or **Stop** buttons on the right-hand side of the window.
Now that you've created your first Dockerfile, image and container, you can try using Docker to compile Linux for the ESP32-S3.
# Use Docker to Compile Linux for ESP32-S3
## Docker ESP32-S3 Linux Image
To begin, you'll save the Dockerfile below to a folder on your local filesystem. Name it as **Dockerfile** with no file extension, just like you did on the [Test Image page](https://learn.adafruit.com/docker-esp32-s3-linux/docker-test-image).
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/ESP32S3_Linux/Dockerfile
As you can see, this Dockerfile is a lot more detailed than the test image that you just ran. It installs all of the toolchains and dependencies on an Ubuntu build and then runs the script to compile the files needed to load onto the ESP32-S3.
The steps for building are the same though. Open a terminal window, navigate to the folder where you saved the Dockerfile and enter:
`docker build -t esp32-s3_linux .`
This builds the image and names it **esp32-s3\_linux**.
After building, go to the Docker desktop app and look under **Images**. Select your newly created **esp32-s3\_linux** image and click the **Play** button. Then click **Run** to start a container with the image.
Once the container opens, go to the **Terminal** tab. You'll be able to interact with the Ubuntu machine that has your compiled files for the ESP32-S3.
If you change directories to the releases folder (`cd /app/build/releases`) you'll see the kernel, file system and binary files that will be loaded onto your ESP32-S3. To use these files, you'll need to copy them to your local filesystem out of the Docker container.
To do this, go back to a terminal window on your local desktop and navigate to the directory where you saved the Dockerfile. Enter the following command:
`docker cp CONTAINER-NAME:/app/build/release/ bin_files`
Replace `CONTAINER-NAME` with the name of your container in the Docker app. This copies the **/release** folder from your container in Docker to a folder called / **bin\_files**.
Open the file location on your computer. You should see the five files now stored locally in the folder. This will allow you to use esptool and the ESP-IDF to load the files onto your ESP32-S3.
# Use Docker to Compile Linux for ESP32-S3
## Upload the Files to the ESP32-S3
You will need two utilities from Espressif installed on your computer in order to upload the compiled files onto the ESP32-S3: esptool and the ESP-IDF.
## esptool
You'll use esptool to upload the binary files to the ESP32-S3. esptool is installed with `pip`. Open a terminal window and enter:
`pip install esptool`
For more information on esptool, you can check out the [documentation from Espressif](https://docs.espressif.com/projects/esptool/en/latest/esp32/installation.html).
[Espressif Documentation for esptool](https://docs.espressif.com/projects/esptool/en/latest/esp32/installation.html)
## ESP-IDF
The kernel and filesystem are written to the ESP32-S3 using parttool.py, which is a tool included in the ESP-IDF. You can install the ESP-IDF as a part of your IDE or separately on your local computer. [Espressif has documentation and installers](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/#installation) on their site.
[ESP-IDF Installers and Installation Documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/#installation)
## Prep the Metro ESP32-S3
Now you finally get to play with hardware. You'll use the Metro ESP32-S3, which has 16 MB of Flash and 8 MB of PSRAM making it perfect for this skateboard trick.
You'll want to upload the files that you just built over hardware UART. The RX and TX hardware UART pins are accessible next to the ESP32-S3 module on the board. Solder two headers to those pins.
### Break-away 0.1" 36-pin strip male header - Black - 10 pack
[Break-away 0.1" 36-pin strip male header - Black - 10 pack](https://www.adafruit.com/product/392)
Breakaway header is like the duct tape of electronics. It's great for connecting things together, soldering to perf-boards, fits into any breakout or breadboard, etc. We go through these guys real fast, and thought that given how handy they are, we'd offer them in a pack of ten!
Out of Stock
[Buy Now](https://www.adafruit.com/product/392)
[Related Guides to the Product](https://learn.adafruit.com/products/392/guides)
### USB to TTL Serial Cable - Debug / Console Cable for Raspberry Pi
[USB to TTL Serial Cable - Debug / Console Cable for Raspberry Pi](https://www.adafruit.com/product/954)
The cable is easiest way ever to connect to your microcontroller/Raspberry Pi/WiFi router serial console port. Inside the big USB plug is a USB\<-\>Serial conversion chip and at the end of the 36" cable are four wire - red power, black ground, white RX into USB port, and green TX out...
In Stock
[Buy Now](https://www.adafruit.com/product/954)
[Related Guides to the Product](https://learn.adafruit.com/products/954/guides)
Attach a USB to serial cable to the Metro ESP32-S3. You should see the board power up once you plug in the USB cable.
- **USB RX** to **ESP32-S3 TX (white wire)**
- **USB TX** to **ESP32-S3 RX (green wire)**
- **USB power** to **ESP32-S3 VIN (red wire)**
- **USB ground** to **ESP32-S3 GND (black wire)**
## Binary Files
First, you'll upload the three binary files ( **bootloader.bin** , **network\_adapter.bin** and **partition-table.bin** ) to the ESP32-S3 with esptool.
Put the Metro ESP32-S3 into bootloader mode by holding down the boot button, pressing the reset button and then releasing the boot button. Then, open a terminal window and navigate to the directory where you saved the exported files from the Docker container. Enter this command to upload the three files to the ESP32-S3:
```terminal
python esptool.py --chip esp32s3 -p YOUR-PORT-HERE -b 921600 --before=default_reset --after=hard_reset write_flash 0x0 bootloader.bin 0x10000 network_adapter.bin 0x8000 partition-table.bin
```
Replace `YOUR-PORT-HERE` with the USB port number that the ESP32-S3 is attached to. On Linux or Mac it may look like `/dev/ttyUSB0`. On Windows, it will be COM followed by a number. For example, `COM3`.
## File System and Kernel
Next, you'll use the ESP-IDF terminal to upload the file system and kernel file. Open an ESP-IDF terminal window and navigate to the directory where you saved the exported files from the Docker container. First, put the Metro ESP32-S3 into bootloader mode by holding down the boot button, pressing the reset button and then releasing the boot button. Then upload the kernel file ( **xipImage** ) first with:
```terminal
parttool.py write_partition --partition-name linux --input xipImage
```
Put the Metro ESP32-S3 into bootloader mode again and then upload the file system file ( **rootfs.cramfs** ) with:
```terminal
parttool.py write_partition --partition-name rootfs --input rootfs.cramfs
```
Next you'll boot into Linux on an ESP32-S3!
# Use Docker to Compile Linux for ESP32-S3
## Boot Linux on the ESP32-S3
You'll be able to log into Linux on the ESP32-S3 by using a serial connection.
Using your preferred serial client, open a serial connection with the hardware UART port on the ESP32-S3 at a 115200 baudrate.
Press the reset button on the ESP32-S3. In your serial monitor, you should see Linux booting up. When its ready, it will prompt you for a login. Enter `root`. This will bring you to the filesystem.
You may see spurious `FW_MAIN` print statements randomly pop up in your serial monitor. This is the WiFi core printing status messages and is normal for this build.
## WiFi
To connect to WiFi, enter the following commands:
```terminal
ip link set espsta0 up
cat > /tmp/wpa_supplicant.conf <Serial conversion chip and at the end of the 36" cable are four wire - red power, black ground, white RX into USB port, and green TX out...
In Stock
[Buy Now](https://www.adafruit.com/product/954)
[Related Guides to the Product](https://learn.adafruit.com/products/954/guides)
### Break-away 0.1" 36-pin strip male header - Black - 10 pack
[Break-away 0.1" 36-pin strip male header - Black - 10 pack](https://www.adafruit.com/product/392)
Breakaway header is like the duct tape of electronics. It's great for connecting things together, soldering to perf-boards, fits into any breakout or breadboard, etc. We go through these guys real fast, and thought that given how handy they are, we'd offer them in a pack of ten!
Out of Stock
[Buy Now](https://www.adafruit.com/product/392)
[Related Guides to the Product](https://learn.adafruit.com/products/392/guides)
### USB Type A to Type C Cable - approx 1 meter / 3 ft long
[USB Type A to Type C Cable - approx 1 meter / 3 ft long](https://www.adafruit.com/product/4474)
As technology changes and adapts, so does Adafruit. This **USB Type A to Type C** cable will help you with the transition to USB C, even if you're still totin' around a USB Type A hub, computer or laptop.
USB C is the latest industry-standard connector for...
In Stock
[Buy Now](https://www.adafruit.com/product/4474)
[Related Guides to the Product](https://learn.adafruit.com/products/4474/guides)
## Related Guides
- [Adafruit Metro ESP32-S3](https://learn.adafruit.com/adafruit-metro-esp32-s3.md)
- [ESP-NOW in CircuitPython](https://learn.adafruit.com/esp-now-in-circuitpython.md)
- [Networking in CircuitPython](https://learn.adafruit.com/networking-in-circuitpython.md)
- [Plotting Offline Data - JSONL to CSV files, filters and graphs](https://learn.adafruit.com/plotting-offline-data-jsonl-to-csv-files-filters-and-graphs.md)
- [MP3 Playback with CircuitPython](https://learn.adafruit.com/mp3-playback-with-circuitpython.md)
- [Gravatars: What they are and how to add or change one](https://learn.adafruit.com/gravatars-what-they-are-and-how-to-add-or-change-one.md)
- [LEGO Set Lighting](https://learn.adafruit.com/lego-set-lighting.md)
- [Neon LED Signs](https://learn.adafruit.com/led-neon-signs.md)
- [Computer Perfection Synthesizer](https://learn.adafruit.com/computer-perfection-synthesizer.md)
- [Sideloading Apps on Oculus Quest](https://learn.adafruit.com/sideloading-on-oculus-quest.md)
- [Contribute to CircuitPython with Git and GitHub](https://learn.adafruit.com/contribute-to-circuitpython-with-git-and-github.md)
- [Ladyada's Learn Arduino - Lesson #0](https://learn.adafruit.com/ladyadas-learn-arduino-lesson-number-0.md)
- [No-Code IKEA Vindriktning Air Quality Sensor Hack with Adafruit IO](https://learn.adafruit.com/no-code-ikea-vindriktning-hack-with-qt-py-esp32-s3-and-adafruit-io.md)
- [Cynaps Bone Conduction Headset Teardown](https://learn.adafruit.com/cynaps-bone-conduction-headset-teardown.md)
- [Digital Circuits 6: An EPROM Emulator](https://learn.adafruit.com/digital-circuits-6-eprom-emulator.md)