Pepper ROS Setup Guide

Get the Pepper robot simulation running inside a Docker container with ROS Noetic and Gazebo.

Initial Setup

1

Pull the Base Image

You may need to use sudo for Docker commands depending on your system permissions. 
sudo docker pull ghcr.io/00ducky13/pepper_stage1_ros:latest
2

Enable GUI Support

Allow Docker to access your display (Linux with X11).

xhost +local:docker
3

Launch the Container

Start the container and enter its terminal:

sudo docker run -it --rm \
    -e DISPLAY=$DISPLAY \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    -p 8080:8080 \
    ghcr.io/00ducky13/pepper_stage1_ros:latest

Inside the Container

4

Start ROS Core

Once your terminal prompt changes (indicating you are inside the Docker container), start the ROS core and configure your graphics:

roscore &
export LIBGL_ALWAYS_SOFTWARE=1
Hit Enter if you need to get your command prompt back after running roscore &.

Choose a launch mode:

With GUI

Launch the full Gazebo simulation window.

roslaunch pepper_gazebo_plugin pepper_gazebo_plugin_Y20.launch
Headless

View the simulation at http://localhost:8080.

roslaunch pepper_gazebo_plugin pepper_gazebo_plugin_Y20.launch gui:=false

Once Gazebo is running, move on to controlling the robot.

Robot Control Guide →

Troubleshooting

permission denied while trying to connect to the Docker daemon socket

Cause: Your user does not have permission to run Docker commands.

Fix: Prepend your Docker commands with sudo (e.g., sudo docker pull...), or permanently fix this by adding your user to the docker group on your Linux machine.

Unable to find image 'pepper:latest' locally

Cause: The docker run command is looking for an image with the wrong name.

Fix: Make sure you are using the full registry URL at the end of your docker run command: ghcr.io/00ducky13/pepper_stage1_ros:latest. Do not shorten it to just pepper.

RLException: [pepper_gazebo_plugin_Y20.launch] is neither a launch file...

Cause: You likely changed the internal ROS package names in the roslaunch command to match the new Docker image name.

Fix: While the Docker image is named pepper_stage1_ros, the ROS packages inside the container still use their original names. Always use roslaunch pepper_gazebo_plugin ... once inside the container.

The GUI doesn't open or throws a display error

Cause: The container cannot communicate with your host machine's display, or your graphics drivers are clashing with the container.

Fix: Ensure you ran xhost +local:docker before starting the container. If you are still having issues, make sure you ran export LIBGL_ALWAYS_SOFTWARE=1 inside the container to force software rendering.

Note: The xhost command is specific to Linux/X11. Mac or Windows users will need additional software like XQuartz or VcXsrv.