Onboarding Guide

Welcome to the Space Station OS (SSOS) onboarding guide. This page walks you through getting started with SSOS either by running the pre-built Docker image (recommended for quick setup) or building the project from source if you're contributing to development.

---

Quick Start with Docker

Run Space Station OS in seconds using our prebuilt Docker image.

1. Install Docker (if not already installed)

Run the following on Ubuntu 22.04 or 24.04:

sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Verify:

docker --version

---

2. Pull the Prebuilt Docker Image

We maintain a single latest image with all SSOS packages and ROS 2 pre-installed:

docker pull ghcr.io/space-station-os/space_station_os:latest

This is the official SSOS image tagged :latest. No setup required.

---

3. Run the Container

docker run -it --rm ghcr.io/space-station-os/space_station_os:latest

Once inside, you're in a fully configured ROS 2 workspace ready to explore and simulate Space Station OS.

---

🛠️ Troubleshooting (Optional)

If the image fails to pull or you're working offline:

git clone https://github.com/space-station-os/space_station_os.git
cd space_station_os
docker build -t space_station_os:latest -f docker/ros2-dev/Dockerfile .
docker run -it --rm \
  --env="DISPLAY=$DISPLAY" \
  --env="QT_X11_NO_MITSHM=1" \
  --env="LIBGL_ALWAYS_SOFTWARE=1" \
  --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" \
  --network=host \
  space_station_os:latest

---

🧑‍💻 Build from Source (For Developers & Contributors)

Use this method if you want to modify the codebase or run SSOS natively on your system.

---

🔧 Prerequisites

• OS: Ubuntu 22.04 (for ROS 2 Humble) or Ubuntu 24.04 (for ROS 2 Jazzy)
• ROS 2: Installed based on your distro

Install ROS 2:

• [ROS 2 Humble Installation Guide (22.04)](https://docs.ros.org/en/humble/Installation/Ubuntu-Install-Debs.html)
• [ROS 2 Jazzy Installation Guide (24.04)](https://docs.ros.org/en/jazzy/Installation/Ubuntu-Install-Debs.html)

---

1. Create and Initialize the Workspace

mkdir -p ~/ssos_ws/src
cd ~/ssos_ws/src

2. Clone the Repository

git clone https://github.com/space-station-os/space_station_os.git
cd ..

If you're targeting a specific branch (e.g., v0.8.4-dev):

cd space_station_os
git checkout v0.8.4-dev
cd ../..

---

3. Build the Workspace

cd ~/ssos_ws
rosdep update
rosdep install --from-paths src --ignore-src -r -y
colcon build --symlink-install
source install/setup.bash

Add the source line to .bashrc for convenience:

echo "source ~/ssos_ws/install/setup.bash" >> ~/.bashrc

---

You're Now Ready!

You can now:

• Launch simulation worlds
• Interact with ECLSS, GNC, or Thermal subsystems
• Use RViz, Gazebo Harmonic, and other tools

Check out the subsystem-specific README files for more details.