chore: dockerization of the tuono repo! (#276)

Co-authored-by: Marco Pasqualetti <marco.pasqualetti@live.com>

.github/workflows/repo-root-ci.yml

@@ -9,12 +9,14 @@ on:
     branches:
       - 'main'
     paths:
-      - '.github/**'
       - '*'
+      - '.github/**'
+      - '.docker/**'
   pull_request:
     paths:
-      - '.github/**'
       - '*'
+      - '.github/**'
+      - '.docker/**'
 
 jobs:
   build-and-test:

apps/documentation/src/routes/documentation/contributing/local-development.mdx

@@ -30,12 +30,16 @@ git clone https://github.com/<your-name-here>/tuono
 cd tuono
 ```
 
-### Rust tool chain
+For the next steps, you can either set up the environment directly on your computer or use a ready-to-use Docker image (go to the [Docker setup](#docker-setup) part).
+
+### Local setup
+
+#### Rust tool chain
 
 Install the Rust programming language tool chain (`rust` and `cargo`).
 Follows instructions in the official [docs](https://rustup.rs/)
 
-### Node.js — runtime
+#### Node.js — runtime
 
 Install `Node.js`.
 You can follow the instructions from the [Node official site](https://nodejs.org/en/download/package-manager)
@@ -50,13 +54,13 @@ You can follow the instructions from the [Node official site](https://nodejs.org
 >
 > to simply pick up the correct version!
 
-### Node.js — package manager
+#### Node.js — package manager
 
 We use [`pnpm`](https://pnpm.io) as Node.js package manager.
 
 You can see which version of yarn we use by checking the `packageManager` field in the root `package.json`.
 
-### Pre-flight checks
+#### Pre-flight checks
 
 To check that everything is working properly, run:
 
@@ -65,6 +69,47 @@ pnpm run check-all
 cargo build
 ```
 
+### Docker setup
+
+#### Introduction
+
+Docker takes care of configuring the development environment, so you don’t need to worry about installing specific versions of packages like Node.js or pnpm. The Docker image handles this for you!
+Using Docker, **the only operations you’ll need to manage on your host machine are related to git**. (don't use phpnm, cargo, ... from your host machine)
+Some IDEs (such as vscode with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)) allow you to connect directly to the Docker container.
+
+**Before proceeding with this guide, make sure that the `node_modules` and `target` directories are either absent or empty in the subprojects of Tuono from your host machine where you want to contribute.** This ensures a clean and consistent environment when using Docker.
+
+#### Build the Tuono's Docker Container
+
+First, ensure Docker is installed on your machine by following the instructions on the [Docker official site](https://docs.docker.com/engine/install/).
+
+Once Docker is installed, use the following command to build the image into a container named tuono-source-container:
+
+```sh
+# Note: Execute this command in the project root
+docker compose -f docker/compose.yml up --build -d
+```
+
+To verify that everything is working as expected, run the following command:
+
+```sh
+docker images && docker ps -a --size
+```
+
+Or on Windows:
+
+```powershell
+docker images; docker ps -a --size
+```
+
+You should see the image named tuono-source-image and the container tuono-source-container. The container's status should be "up".
+
+Use the following command to connect to the container:
+
+```sh
+docker exec -it tuono-source-container /bin/bash
+```
+
 ## Tuono development
 
 1. Start tuono frontend build using

docker/.dockerignore

@@ -0,0 +1,19 @@
+# project
+node_modules
+.pnpm-store
+target
+.turbo
+
+# git
+.git
+.gitignore
+
+# docker
+docker/compose.yml
+docker/Dockerfile
+docker/.dockerignore
+
+# IDE
+.vscode
+.idea
+*.iml

docker/Dockerfile

@@ -0,0 +1,51 @@
+# ARGs obtained from the compose.yml file
+
+ARG BASE_OS=bookworm
+ARG RUST_VERSION=1.83
+
+FROM rust:${RUST_VERSION}-${BASE_OS}
+
+# Nodejs installation
+
+RUN ["mkdir", "/usr/local/node"]
+WORKDIR /usr/local/node
+
+## Retrieves the targeted version of Node in the container
+
+COPY .nvmrc /tmp/.nvmrc
+
+## Download the Node.js standelone binary archive && extract it && clean files
+
+RUN ["/bin/sh", "-c", "NODE_VERSION=$(cat /tmp/.nvmrc) && \
+    wget https://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}-linux-x64.tar.xz && \
+    tar xf node-v${NODE_VERSION}-linux-x64.tar.xz --strip-components 1 && \
+    rm node-v${NODE_VERSION}-linux-x64.tar.xz /tmp/.nvmrc"]
+
+## Ensure Node.js binaries are available in the PATH
+
+ENV PATH /usr/local/node/bin:$PATH
+
+# cargo-watch installation (for Rust live-reloading during dev')
+
+RUN ["cargo", "install", "cargo-watch"]
+
+# global configuration done ! let's focus on the project itself
+
+## Copy project files into the container (excepted files/dir declared in .dockerignore) to /tuono directory
+
+WORKDIR /tuono
+COPY . .
+
+# pnpm installation based on version found in package.json
+
+RUN ["corepack", "enable"]
+RUN ["corepack", "install"]
+
+## Install Node.js dependencies (defined in package.json)
+
+RUN ["pnpm", "install", "--frozen-lockfile"]
+
+## Compile and add the directory with compiled binaries to the PATH for direct access
+
+RUN ["cargo", "build"]
+ENV PATH=/tuono/target/debug:$PATH

docker/compose.yml

@@ -0,0 +1,29 @@
+services:
+  tuono:
+    platform: linux/amd64
+    container_name: tuono-source-container
+    hostname: tuono-source-container
+    build:
+      context: ../
+      dockerfile: ./docker/Dockerfile
+      args:
+        RUST_VERSION: 1.83 # if change, think to update the default ARGs in Dockerfile
+        BASE_OS: bookworm # if change, think to update the default ARGs in Dockerfile
+    image: tuono-source-image
+    ports:
+      - '3000:3000' # expose default port used by tuono server
+    volumes: # mount the project into a volume but node_modules / .pnpm-store / target / ... directories won't by sync from container to host
+      - ..:/tuono
+      - /tuono/node_modules
+      - /tuono/target
+      - /tuono/.pnpm-store
+      - /tuono/.turbo
+      - /tuono/apps/documentation/node_modules
+      - /tuono/apps/documentation/target
+      - /tuono/examples/tuono-app/node_modules
+      - /tuono/examples/tuono-app/target
+      - /tuono/examples/tuono-tutorial/node_modules
+      - /tuono/examples/tuono-tutorial/target
+      - /tuono/examples/with-mdx/node_modules
+      - /tuono/examples/with-mdx/target
+    tty: true