Optional: Docker

Table of Contents

• • Environment Setup with Docker
  • Prerequisite: Docker
  • Step 0: be famous
  • Step 1: build the image
  • Step 2: create a starter script
  • Step 3: start a container from the start script
  • More words on each step
    • Step 0: be famous
    • Step 1: build the image
    • Step 2: create a starter script
    • Step 3: start a container from the start script
  • A note for Linux users

Environment Setup with Docker

Last updated: Tuesday October 28, 2025 on an M1 Mac.

1. You can build a Docker image using the Dockerfile.
2. You can start a Docker container using the Docker image.
   • Inside the container, the environment has been set up so you can simply compile the PUEO software.
   • There is a built-in editor (neovim) as well for you to fully work inside the container.

Prerequisite: Docker

Install Docker. Once installed, make sure the Docker daemon is running (On macOS, this means running the app Docker Desktop).

Step 0: be famous

• Create a text file called $HOME/.gitconfig and put the following in it:

  [user]
      name = Peter Parker
      email = Peter.Parker@theDailyBugle.com
  [core]
      editor = nvim

  Adjust as necessary.

Step 1: build the image

• Once you have Docker running on your computer, run the buildDockerImage.sh script,

  bash pueoBuilder/Docker/buildDockerImage.sh

  which builds a Docker image called pueo_image based on the Dockerfile.
• Building the image for the first time might take a few minutes.

Step 2: create a starter script

• Make a copy of the example script:

  cp pueoBuilder/Docker/startContainerFromImage.sh.example \
     pueoBuilder/Docker/startContainerFromImage.sh

  adjust the content of the copy as necessary.

Step 3: start a container from the start script

1. Running, for example, bash startContainerFromImage.sh.example will start a container.
2. You should be greeted by a welcome message and a prompt:

   Welcome to the container!
   You are in /usr/pueoBuilder.
   Home is at /root. 
    
   pueoBuilder >

3. Inside the container, the environment variables and dependencies have been taken care of, so you can simply follow Installing All Things PUEO to compile and install everything.

More words on each step

Step 0: be famous

• Without this file (which will be mounted), You will be asked to enter your user name and email pretty much every time you use a git command.
• This file will be mounted (see Step 2: create a starter script below).

Step 1: build the image

• The image is managed by Docker, so you won't see anything new in the directory if you type ls
• The script buildDockerImage.sh can be invoked from anywhere, so there's no need to cd to the Docker folder.

Step 2: create a starter script

• The script startContainerFromImage.sh.example starts a container from the image you just built.
• The script can be invoked anywhere, so there's no need to cd to the Docker folder.
• Normally, from within the container, you cannot access files elsewhere on your computer unless you mount them when starting the container. Vice versa, from your computer, you cannot access the folders of the container unless they are mounted.
• Mounting is done by the -v option.
  
• Adjust the paths of the mounted directory in the copy of the example script as you see fit. The copy will be automatically git ignored, so don't worry about accidentally commiting the copy.
• For example, in the startContainerFromImage.sh.example script, you will see

  docker run --rm -it \
    -v "${THIS_DIR}/../:/usr/pueoBuilder"  \
    -v "${HOME}/.ssh:/root/.ssh" \
    -v "${HOME}/.gitconfig:/root/.gitconfig" \
    pueo_image; 

  • ${THIS_DIR}
    1. To the left of the colon is the path on your computer, to the right is the corresponding path in the container.
    2. This is the path where you have cloned the pueoBuilder repository to on your computer,
    3. Incidentally, /usr/pueoBuilder is where you will land after starting the container.
  • ${HOME}/.ssh
    1. If you haven't set up the secure shell, see Step 1: set up secure shell.
    2. This directory has to be mounted. Otherwise, you would not be able to connect to GitHub in the container.

Step 3: start a container from the start script

• The container is destroyed upon exit (see option --rm in the example script), but you can change that behavior in your own copy of the starter script.

  Warning

  Whatever changes you make inside the container will not persist after the container gets destroyed, except the ones you perform in the mounted directory.

• Once you have a container running, you can simply open another terminal and attach to the running container:

  docker exec -it $(docker ps -lq) fish

  (This is like having multiple "windows" into the container.) This way you can multitask.
• You (most likely) are the root user in the container, in which case your home is /root, and /home will be empty. (ie. Running cd, cd ~, or cd ${HOME} will get you to /root)

A note for Linux users

Maybe don't use Docker if you are already on Linux.

When you first get Docker, you might not be able to run its commands without sudo access. I remember running into issues because of this. The scripts here are written and tested on a mac, so if you run into issues where you can't start a container using the scripts on Linyx, it might be due to the sudo problem.

To run docker commands without sudo, you need to create a group called docker and add yourself to it. You may need to log out or even restart the computer.

Another thing; in the container, you are the root user. On Linux, this means the ownership of the mounted directory might be an issue. This ownership issue can cause git commands to not function when you try to push or commit stuff. I am working on fixing this