Pre-commit

docker/snippets/chrono.dockerfile

@@ -41,6 +41,7 @@ RUN wget -qO- https://packages.lunarg.com/lunarg-signing-key-pub.asc | tee /etc/
 USER ${USERNAME}
 
 # chrono_ros_interfaces
+ARG ROS_DISTRO
 ARG ROS_WORKSPACE_DIR="${USERHOME}/ros_workspace"
 ARG CHRONO_ROS_INTERFACES_DIR="${ROS_WORKSPACE_DIR}/src/chrono_ros_interfaces"
 RUN mkdir -p ${CHRONO_ROS_INTERFACES_DIR} && \

docs/README.md

@@ -0,0 +1,16 @@
+# Autonomy Research Testbed Documentation
+
+These docs are meant to be a _succinct_ reference to commands, packages, and any other
+information that may be useful to document as it relates to the
+`autonomy-research-testbed` platform.
+
+## Table of Contents
+
+1. [Repository Structure](./repository_structure.md)
+    1. [`atk.yml`](./atk.md)
+    2. [Dockerfiles](./dockerfiles.md)
+    3. [ROS Workspace](./ros_workspace.md)
+    4. [Launch System](./launch_system.md)
+2. [Development Workflow](./development_workflow.md)
+    1. [How to Run](./how-to-run.md)
+3. [Frequently Asked Questions](./faq.md)

docs/atk.md

@@ -0,0 +1,66 @@
+# `atk.yml`
+
+This file describes the `atk.yml` configuration file specific to this repository. For
+a more general overview of `autonomy-toolkit` and it's configuration parameters, please
+refer to the [official documentation](https://projects.sbel.org/autonomy-toolkit).
+
+For information on how to actually run `atk` for this repo, refer to the
+[How to Run](./how-to-run.md) page.
+
+> [!NOTE]
+> `autonomy-toolkit` is a simple wrapper around `docker compose`. As such, the `atk.yml`
+> is fully compatible with `docker compose`. The main advantage of `autonomy-toolkit`
+> is [Optionals](#optionals).
+
+## Services
+
+For the `autonomy-research-testbed` repo specifically, there are three main service
+types: `dev`/`<vehicle>`, `chrono` and `vnc`.
+
+### `dev`/`<vehicle>`
+
+The `dev` and `<vehicle>` services help spin up images/containers that correspond with
+development of the autonomy stack. These are the main development containers and most
+commonly used. `dev` should be used on non-vehicle platforms (i.e. lab workstations)
+for common development work. The `<vehicle>` service (where `<vehicle>` corresponds to
+an actual vehicle, such as `art-1`) is nearly identical to `dev` with vehicle-specific
+config (such as device exposure, etc.).
+
+### `chrono`
+
+The `chrono` service spins up a container that contains Chrono and is used to run the
+simulation. The `chrono` service should really only ever be run on a powerful
+workstation and not on the vehicle itself. The autonomy stack then can communicate with
+the simulator using [Networks](#networks) (if on the same host) or over WiFi/Cellular/LAN.
+
+### `vnc`
+
+The `vnc` service spins up a container that allows visualizing X windows in a browser
+while in containers. It builds on top of NoVNC. Please see
+[How to Run](./how-to-run.md#vnc) for a detailed usage explanation.
+
+## Optionals
+
+In addition to services, the `atk.yml` defines a few optionals. Optionals are useful
+configurations that are optionally included in the `docker compose` command at runtime.
+For instance, if someone is developing on a Mac (which doesn't have a NVIDIA gpu),
+attaching a gpu to the container will throw an error considering one doesn't exist.
+Optionals provide a helpful mechanism to only apply certain configurations when they
+are desired/supported.
+
+See [How to Run](./how-to-run.md#optionals) for a detailed usage explanation.
+
+## Networks
+
+Another useful tool in `docker compose` are networks. Networks allow containers running
+on the same host to communicate with one another in a virtualized away from the host.
+This means, if there are two containers running on the same host (e.g. `dev` and
+`chrono`), they can communicate with each other without needing to expose any ports or
+do any special networking. By default, all containers spawned in this repository are put
+on the same network.
+
+> [!NOTE]
+> The `vnc` service requires a like-network to work. For instance, for `dev` to display
+> a window in the `vnc` browser, the environment variable `DISPLAY` should be set to
+> `vnc:0.0` and the `vnc` service should be spun up on the host. Using the default
+> network, the windows will be displayed automatically.

docs/dockerfiles.md

@@ -0,0 +1,236 @@
+# Dockerfiles
+
+The `docker/` folder holds the dockerfiles and data files associated with docker
+image/container creation. Background regarding docker, images/containers, and
+dockerfiles is outside the scope of this document. For more information, please
+refer to the [official documentation](https://docs.docker.org).
+
+This folder is structured as follows:
+
+```
+docker/
+├── data/
+├── common/
+│   ├── base.dockerfile
+│   ├── common.dockerfile
+│   └── final.dockerfile
+├── snippets/
+│   ├── chrono.dockerfile
+│   ├── ros.dockerfile
+│   └── rosdep.dockerfile
+├── chrono.dockerfile
+├── dev.dockerfile
+└── vnc.dockerfile
+```
+
+> [!NOTE]
+> In order to be more extensible and general purpose, the dockerfiles mentioned below
+> were built around `dockerfile-x`.
+> [`dockerfile-x`](https://github.com/devthefuture/dockerfile-x.git) is a docker plugin
+> that supports importing of other dockerfiles through the `INCLUDE` docker build
+> action. Using `INCLUDE`, we can construct service dockerfiles that mix and match
+> different [snippets](#dockersnippets) that we implement.
+
+> [!INFO]
+> This repository was built to accommodate is
+[autonomy-toolkit](https://projects.sbel.org/autonomy-toolkit). For more information
+regarding specific commands, please see [Workflow](./02_workflow.md)
+
+## `docker/data/`
+
+This folder holds data files that may be used by dockerfile snippets.
+
+## `docker/common/`
+
+This subfolder of `docker/` holds common dockerfile code that is shared across _most_
+services. It currently contains three dockerfiles.
+
+### `docker/common/base.dockerfile`
+
+This dockerfile helps initialize the docker system as a whole. It defines global `ARGS`,
+such as `USERNAME`, `PROJECT`, etc. Furthermore, it will create a user that has the
+desired `uid` and `gid` (can be defined through the `USER_UID` and the `USER_GID`
+`ARGS`), and will assign any user groups that the user should be apart of.
+
+#### Required `ARGS`
+
+**IMAGE_BASE**: Used in conjunction with **IMAGE_TAG**; defines that base image which
+the custom docker image will be constructed from. The image is constructed using the
+following base image: `${IMAGE_BASE}:${IMAGE_TAG}`. An **IMAGE_BASE** of `ubuntu` and an
+**IMAGE_TAG** of `22.04` would then build the image from `ubuntu::22.04`.
+
+**IMAGE_TAG**: Used in conjunction with **IMAGE_TAG**. See above for details. An
+**IMAGE_BASE** of `ubuntu` and an **IMAGE_TAG** of `22.04` would then build the image
+from `ubuntu::22.04`.
+
+**PROJECT**: The name of the project. Synonymous with `project` in docker. The created
+user in the container is assigned to **PROJECT**, as well as the home directory.
+
+#### Optional `ARGS`
+
+**USERNAME** _(Default: `${PROJECT}`)_: The username to assign to the new user created
+in the image.
+
+**USERHOME** _(Default: `/home/${USERNAME}`)_: The home directory for the new user.
+
+**USERSHELL** _(Default: `bash`)_: The shell to use in the container. Bash is
+recommended.
+
+**USERSHELLPATH** _(Default: `/bin/${USERSHELL}`)_: The path to the new user's shell.
+
+**USERSHELLPROFILE** _(Default: `${USERHOME}/.${USERSHELL}rc`): The path to the new
+user's shell profile.
+
+**USER_UID** _(Default: 1000)_: The user id (User ID -> UID) that the created user is
+assigned. In Linux, this must match the system user with which you launch `atk` from.
+If it's not assigned correctly, you will have permission issues when trying to edit
+files from the host and/or the container. See the [FAQs](./faq.md#file-permissions)
+for more information.
+
+**USER_GID** _(Default: 1000)_: See **USER_UID** above.
+
+**USER_GROUPS** _(Default: "")_: User groups to add to the new user.
+
+### `docker/common/common.dockerfile`
+
+This dockerfile runs command that we can assume most services want, like package
+installation.
+
+#### Required `ARGS`
+
+There are no required args.
+
+#### Optional `ARGS`
+
+**APT_DEPENDENCIES** _(Default: "")_: A space separated list of apt dependencies to
+install in the image. Installed with `apt install`.
+
+**PIP_REQUIREMENTS** _(Default: "")_: A space separated list of pip dependencies to
+install in the image. Installed with `pip install`.
+
+**USER_SHELL_ADD_ONS** _(Default: "")_: Profile shell addons that are directly echoed
+into the user shell profile. For instance,
+`USER_SHELL_ADD_ONS: "source /opt/ros/${ROS_DISTRO}/setup.bash"` will run
+`echo "source /opt/ros/${ROS_DISTRO}/setup.bash" >> ${USERSHELLPROFILE}`.
+
+### `docker/common/final.dockerfile`
+
+This dockerfile runs commands that are expected to be run after all main installation
+snippets are run. It will set the `USER` to our new user, set environment variables, and
+set the `CMD` to be `${USERSHELLPATH}`.
+
+#### Required `ARGS`
+
+There are no required args.
+
+#### Optional `ARGS`
+
+There are no optional args.
+
+## `docker/snippets`
+
+This folder contains dockerfile "snippets", or small scripts that are included in
+service dockerfiles to build specific packages, such as Chrono or ROS.
+
+### `docker/snippets/chrono.dockerfile`
+
+This file builds Chrono from source. It currently builds a non-configurable list of
+chrono modules that is listed below:
+
+- `PyChrono`
+- `Chrono::VSG`
+- `Chrono::Irrlicht`
+- `Chrono::Vehicle`
+- `Chrono::Sensor`
+- `Chrono::Parsers`
+- `Chrono::ROS`
+
+Furthermore,
+[`chrono_ros_interfaces`](https://github.com/projectchrono/chrono_ros_interfaces) is
+built. This is required to build `Chrono::ROS`.
+
+#### Required `ARGS`
+
+**OPTIX_SCRIPT**: The location _on the host_ that the optix script is located at. This
+script can be found on NVIDIA's OptiX downloads page. For more information, see the
+[FAQs](./faq.md#optix-install).
+
+**ROS_DISTRO**: The ROS distro to use.
+
+#### Optional `ARGS`
+
+**ROS_WORKSPACE_DIR** _(Default: `${USERHOME}/ros_workspace`)_. The directory to build
+`chrono_ros_interfaces` at. Helpful so that you can add custom messages after building
+the image. Ensure you copy the changes to the host before tearing down the container
+as this is _not_ a volume.
+
+**CHRONO_ROS_INTERFACES_DIR** _(Default: `${ROS_WORKSPACE_DIR}/src/chrono_ros_interfaces`)_:
+The folder where the `chrono_ros_interfaces` package is actually cloned.
+
+**CHRONO_BRANCH** _(Default: `main`)_: The Chrono branch to build from.
+
+**CHRONO_REPO** _(Default: `https://github.com/projectchrono/chrono.git`)_: The url of
+the Chrono repo to clone and build from.
+
+**CHRONO_DIR** _(Default: `${USERHOME}/chrono`)_: The directory to clone chrono to. The
+clone is _not_ deleted to allow people to make changes to the build from within the
+container. Ensure you copy the changes to the host before tearing down the container
+as this is _not_ a volume.
+
+**CHRONO_INSTALL_DIR** _(Default: `/opt/chrono`)_: The path where Chrono is installed.
+The user profile is updated to add the python binary directory to `PYTHONPATH` and
+the lib directory is appended to `LD_LIBRARY_PATH`.
+
+### `docker/snippets/ros.dockerfile`
+
+To decrease image size and allow easy customization, ROS is installed separately (as
+opposed to the usual method of building _on top_ of an official ROS image). This
+snippet will install ROS here.
+
+#### Required `ARGS`
+
+**ROS_DISTRO**: The ROS distro to use.
+
+#### Optional `ARGS`
+
+There are no optional args.
+
+### `docker/snippets/rosdep.dockerfile`
+
+`rosdep` is a useful tool in ROS that parses nested packages, looks inside each
+`package.xml` for build dependencies (through `<build_depend>`), and installs the
+package through the best means (e.g. `apt`, `pip`, etc.). This file will run `rosdep` on
+the ROS workspace located within the `autonomy-research-testbed` repository.
+
+#### Required `ARGS`
+
+**ROS_DISTRO**: The ROS distro to use.
+
+#### Optional `ARGS`
+
+**ROS_WORKSPACE** _(Default: `./workspace`)_: The directory location _on the host_ of
+the ROS workspace to run `rosdep` on.
+
+## `docker/chrono.dockerfile`
+
+The dockerfile for the `chrono` service. It will do the following:
+
+1. Run `base.dockerfile`
+2. Install ROS
+3. Install Chrono
+4. Run `common.dockerfile`
+5. Run `final.dockerfile`
+
+## `docker/dev.dockerfile`
+
+The dockerfile for the `dev` service. It will do the following:
+
+1. Run `base.dockerfile`
+2. Install ROS
+3. Run `rosdep`
+4. Run `common.dockerfile`
+5. Run `final.dockerfile`
+
+## `docker/vnc.dockerfile`
+
+The dockerfile for the `vnc` service.

docs/faq.md

@@ -0,0 +1,43 @@
+# Frequently Asked Questions
+
+## File Permissions
+
+For Linux users, you may run into issues regarding file permissions when using docker.
+By properly setting the user id (UID) and group id (GID) of the created user in the
+image, these issues can usually be avoided. By default, in the `base.dockerfile` file,
+the UID and GID are both set to 1000 (the default UID/GID for new users in most linux
+distributions).
+
+If you are running into file permission issues, you may want to try the following.
+
+First, check the user id and group id with the following commands:
+
+```bash
+$ id -u
+1001
+
+$ id -g
+1001
+```
+
+If you see something similar to the above, where the output id's are _not_ 1000, you
+will need to update the `USER_UID` and `USER_GID` environment variables. It is
+recommended this is done either through your host's profile file (e.g. `~/.bashrc` or
+`~/.zshrc`) or assigning the variables in the `.env` file in the root of the
+`autonomy-research-testbed` repo.
+
+```bash
+# In your ~/.bashrc or ~/.zshrc file
+export USER_UID=1001
+export USER_GID=1001
+```
+
+```bash
+# In <path-to-art>/autonomy-research-testbed/.env
+USER_UID=1001
+USER_GID=1001
+```
+
+## OptiX Install
+
+TODO

docs/how-to-run.md

@@ -0,0 +1,4 @@
+# How to Run
+
+## Optionals
+## VNC

docs/launch_system.md

@@ -0,0 +1 @@
+# Launch System