Improve linux build docs

.dockerignore

@@ -0,0 +1,3 @@
+# Exclude everything because we expect users to mount this dir as a volume,
+# so none of this repos' content should be part of the docker build context.
+*

.gitignore

@@ -51,3 +51,7 @@ __generated__
 /metrics/integration/query-tests/**/actual.json
 /metrics/integration/render-tests/**/actual.png
 /metrics/integration/render-tests/**/diff.png
+
+cache.sqlite
+cache.sqlite-journal
+out.png

platform/linux/Dockerfile

@@ -1,7 +1,33 @@
 FROM ubuntu:22.04
 
-RUN apt-get update && \
-    DEBIAN_FRONTEND=noninteractive apt-get install -y libcurl4-openssl-dev libglfw3-dev libuv1-dev libpng-dev libicu-dev libjpeg-turbo8-dev libwebp-dev xvfb clang git cmake ccache ninja-build pkg-config && \
-    rm -rf /var/lib/apt/lists/*
+# When running docker with -u flag, the user should exist in the container to avoid various warnings
+RUN groupadd -f user && useradd -m -g user user
 
-WORKDIR /root
+# Install build tools and dependencies
+RUN    apt-get update \
+    && DEBIAN_FRONTEND=noninteractive apt-get install -y \
+        apt-transport-https \
+        curl \
+        gnupg \
+    && curl -fsSL https://bazel.build/bazel-release.pub.gpg | gpg --dearmor >bazel-archive-keyring.gpg \
+    && mv bazel-archive-keyring.gpg /usr/share/keyrings \
+    && echo "deb [arch=amd64 signed-by=/usr/share/keyrings/bazel-archive-keyring.gpg] https://storage.googleapis.com/bazel-apt stable jdk1.8" | tee /etc/apt/sources.list.d/bazel.list \
+    && apt-get update \
+    && DEBIAN_FRONTEND=noninteractive apt-get install -y \
+        bazel \
+        libcurl4-openssl-dev \
+        libglfw3-dev \
+        libuv1-dev \
+        libpng-dev \
+        libicu-dev \
+        libjpeg-turbo8-dev \
+        libwebp-dev \
+        xvfb \
+        clang \
+        git \
+        cmake \
+        ccache \
+        ninja-build \
+        pkg-config
+
+WORKDIR /code

platform/linux/README.md

@@ -2,77 +2,85 @@
 
 This guide explains how to get started building and running MapLibre Native on Linux. The guide focusses on a Ubuntu 22.04. The build process should give you a set of `.a` files that you can use to include MapLibre Native in other C++ projects, as well as a set of executables that you can run to render map tile images and test the project.
 
-## Requirements
+## Clone the repo
 
-The following system libraries need to be installed.
+First, clone the repository. This repository uses [git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules), that are required to build the project.
 
 ```bash
-apt install libcurl4-openssl-dev libglfw3-dev libuv1-dev libpng-dev libicu-dev libjpeg-turbo8-dev libwebp-dev xvfb
+git clone --recurse-submodules -j8 https://github.com/maplibre/maplibre-native.git
+cd maplibre-native
 ```
 
-Optional: `libsqlite3-dev` (also available as vendored dependency).
-
-The following tools need to be available.
+## Requirements
+### Building without Docker
 
 ```bash
-apt install clang git cmake ccache ninja-build pkg-config
+# Install build tools
+apt install clang cmake ccache ninja-build pkg-config
+
+# Install system dependencies
+apt install libcurl4-openssl-dev libglfw3-dev libuv1-dev libpng-dev libicu-dev libjpeg-turbo8-dev libwebp-dev xvfb
 ```
 
-## Docker
+Optional: `libsqlite3-dev` (also available as vendored dependency).
+
+### Building with Docker
 
 You can use a Docker container to build MapLibre Native. A `Dockerfile` that installes the required dependencies when the image is built is provided in this directory.
 
-Build image with:
 ```bash
-# in platform/linux
-docker build -t maplibre-native-image .
-```
+# Build docker image from the repo root
+docker build -t maplibre-native-image -f platform/linux/Dockerfile .
 
-Run image with:
-```bash
-# in repo root directory
-docker run --rm -it -v "$(pwd)":/root/ maplibre-native-image
+# Run docker image as the current user.
+# This ensures that the files created in the container are owned by the current user.
+docker run --rm -it -v "$PWD:/code/" -u $(id -u):$(id -g) maplibre-native-image
 ```
 
-## Build
-
-First, clone the repository. This repository uses [git submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules), that are required to build the project.
+You can safely ignore this type of message and a missing username. It happens if your linux user was not the first one created on the system.
 
-```bash
-git clone --recurse-submodules -j8 https://github.com/maplibre/maplibre-native.git
-cd maplibre-native
+```
+groups: cannot find name for group ID ....
+I have no name!@...:/root$ `
 ```
 
-To create the build, run the following commands from the root of the project:
+## Build
 
 ```bash
+# Run from the root of the project to init the build  
 cmake -B build -GNinja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ -DCMAKE_BUILD_TYPE=RelWithDebInfo -DMLN_WITH_CLANG_TIDY=OFF -DMLN_WITH_COVERAGE=OFF -DMLN_DRAWABLE_RENDERER=ON -DCMAKE_BUILD_WITH_INSTALL_RPATH=ON
-```
 
-```bash
+# Build mbgl-render using all available CPUs
 cmake --build build --target mbgl-render -j $(nproc 2>/dev/null || sysctl -n hw.ncpu 2>/dev/null)
 ```
 
-## `mbgl-render`
 
-If all went well, there should now be a `./build/bin/mbgl-render` binary that you can run to generate map tile images. To test that it is working properly, run the following command.
+## Running `mbgl-render`
+Running `mbgl-render --style https://raw.githubusercontent.com/maplibre/demotiles/gh-pages/style.json` should produce a map tile image with the default MapLibre styling from [the MapLibre demo](https://maplibre.org/).
+
+![Sample image of world from mbgl-render command](/misc/sample-maplibre-style-mbgl-render-out.png)
+
+### Outside of Docker
+
+Render output image using default MapLibre demo tiles server. You can run this binary on your host machine even if you built it inside a Docker container.
 
 ```bash
 ./build/bin/mbgl-render --style https://raw.githubusercontent.com/maplibre/demotiles/gh-pages/style.json --output out.png
+open out.png
 ```
 
-> I get an error `Error: Failed to open X display.` when I run this command.
+### Inside Docker
+
+If you run `mbgl-render` inside a Docker or on a remote headless server, you will likely get this error because there is no X server running in the container.
 
-If you're setting up MapLibre Native on a headless server (i.e. one without a display), you'll need to simulate an X server to do any rendering. Install `xvfb` and `xauth` and run the following command:
+> `Error: Failed to open X display.`
+
+You'll need to simulate an X server to do any rendering. Install `xvfb` and `xauth` and run the following command:
 
 ```bash
 xvfb-run -a ./build/bin/mbgl-render --style https://raw.githubusercontent.com/maplibre/demotiles/gh-pages/style.json --output out.png
 ```
 
-This should produce an `out.png` map tile image with the default MapLibre styling from [the MapLibre demo](https://maplibre.org/).
-
-![Sample image of world from mbgl-render command](/misc/sample-maplibre-style-mbgl-render-out.png)
-
 ### Using your own style/tiles 
 
 You can also use the `mbgl-render` command to render images from your own style or tile set. To do so, you will need a data source and a style JSON file.
@@ -131,4 +139,4 @@ Or a single test with:
 ./build/mbgl-render-test-runner --manifestPath metrics/linux-clang8-release-style.json --filter "render-tests/fill-visibility/visible"
 ```
 
-The render test results are summarized in a HTML website located next to the manifest file. For example, running `metrics/linux-clang8-release-style.json` produces a summary at `metrics/linux-clang8-release-style.html`.
+The render test results are summarized in a HTML website located next to the manifest file. For example, running `metrics/linux-clang8-release-style.json` produces a summary at `metrics/linux-clang8-release-style.html`.