1 files changed, 172 insertions, 0 deletions

diff --git a/subprojects/docs/src/develop/contributing/commands.md b/subprojects/docs/src/develop/contributing/commands.md
new file mode 100644
index 00000000..abfea704
--- /dev/null
+++ b/subprojects/docs/src/develop/contributing/commands.md
@@ -0,0 +1,172 @@
+---
+SPDX-FileCopyrightText: 2024 The Refinery Authors
+SPDX-License-Identifier: EPL-2.0
+sidebar_position: 1
+title: Build commands
+---
+
+# Building from the command line
+
+## Gradle commands
+
+We use [Gradle](https://gradle.org/) to manage the compilation and tests of Refinery.
+
+Java code is built directly by Gradle.
+We use the [frontend-gradle-plugin](https://siouan.github.io/frontend-gradle-plugin/) to manage a [Node.js](https://nodejs.org/en) and [Yarn](https://yarnpkg.com/) installation, which in turn is used to build TypeScript code (including this documentation website).
+Typically, Yarn commands are issued by Gradle and you don't need to work with the TypeScript build system directly if you're only working on the Java parts of Refinery.
+
+### `build`
+
+```bash posix2windows
+./gradlew build
+```
+
+Compile all code, run all tests, and produce all build artifacts.
+
+You should run this command before submitting a [Pull request](https://github.com/graphs4value/refinery/pulls) to make sure that all code builds and tests pass on your local machine.
+This will also be run by GitHub Actions for each commit or pull requests.
+
+### `publishToMavenLocal`
+
+
+```bash posix2windows
+./gradlew publishToMavenLocal
+```
+
+Publishes the Refinery Java artifacts to the [Maven local repository](https://www.baeldung.com/maven-local-repository).
+
+Build tools, such as Gradle, will be able to consume such artifacts, which enables you to use the latest version of Refinery -- possibly including your own modification -- in other Java projects.
+
+For example, in Gradle, you may set
+
+```kotlin title="build.gradle.kts"
+repositories {
+  mavenLocal()
+}
+
+dependencies {
+  implementation("tools.refinery:refinery-generator:0.0.0-SNAPSHOT")
+}
+```
+
+to add a dependency on Refinery to your Java project.
+
+### `serve`
+
+```bash posix2windows
+./gradlew serve
+```
+
+Starts the Refinery backend and web interface on port 1312.
+
+This task is ideal for running the Refinery backend if you don't intend to work on the frontend.
+The Refinery frontend TypeScript projects is automatically built before the server starts.
+The server will use the latest build output of the frontend as static assets.
+
+The behavior of this task is influenced by the same [environmental variables](/learn/docker#environmental-variables) as the Refinery [Docker container](/learn/docker).
+However, the default value of `REFINERY_LISTEN_PORT` is `1312`.
+
+### `serveBackend`
+
+```bash posix2windows
+./gradlew serveBackend
+```
+
+Starts the Refinery backend on port 1312.
+
+This task is ideal for running the Refinery backend if you're working on the frontend.
+No static assets will be build.
+You'll need to use [`yarnw frontend dev`](#frontend-dev)
+
+Like [`gradlew serve`](#serve), the behavior of this task is influenced by the same [environmental variables](/learn/docker#environmental-variables) as the Refinery [Docker container](/learn/docker).
+However, the default value of `REFINERY_LISTEN_PORT` is `1312`.
+
+## Yarn commands
+
+We provide a `yarnw` wrapper script to invoke the Yarn distribution installed by frontend-gradle-plugin directly.
+The following commands can only be run once [`gradlew build`](#build) has installed the necessary Node.js and Yarn packages.
+
+### `docs dev`
+
+```bash posix2windows
+./yarn docs dev
+```
+
+Builds and serves this documentation in development mode on port 3000.
+Saved changes to most documentation sources are immediately reflected in the browse without reloading.
+
+You can set the port with the `-p` option, e.g. to use port 1313, use
+
+```bash posix2windows
+./yarn docs dev -p 1313
+```
+
+:::note
+
+Running this command for the first time may generate error messages like
+```
+ERROR  failed to read input source map: failed to parse inline source map url
+```
+which can be safely ignored.
+
+:::
+
+### `frontend dev`
+
+```bash posix2windows
+./yarn frontend dev
+```
+
+Builds and serves the refinery frontend on port 1313.
+Saved changes to most source files are immediately reflected in the browser without reload.
+
+Before running this command, you need to start [`gradlew serveBackend`](#servebackend) to provide a backend for the frontend to connect to.
+The development server of the frontend will proxy all WebSocket connections to the backend.
+
+The following environmental variables influence the behavior of this command:
+
+#### `REFINERY_LISTEN_HOST`
+
+Hostname to listen at for incoming HTTP connections.
+
+**Default value:** `localhost`
+
+#### `REFINERY_LISTEN_PORT`
+
+TCP port to listen at for incoming HTTP connections.
+
+**Default value:** `1313`
+
+#### `REFINERY_BACKEND_HOST`
+
+Hostname of the Refinery backend.
+
+This should match the `REFINERY_LISTEN_HOST` passed to [`gradlew serveBackend`](#servebackend).
+
+**Default value:** `127.0.0.1` (connect to `localhost` over IPv4 only)
+
+#### `REFINERY_LISTEN_PORT`
+
+TCP port of the Refinery backend.
+
+This should match the `REFINERY_LISTEN_PORT` passed to [`gradlew serveBackend`](#servebackend).
+
+**Default value:** `1312`
+
+#### `REFINERY_PUBLIC_HOST`
+
+Publicly visible hostname of the Refinery instance.
+
+If you use a reverse proxy in front of the development server, you must set this variable.
+Otherwise, connections to the development server will fail due to cross-origin protection.
+
+**Default value:** equal to `REFINERY_LISTEN_HOST`
+
+#### `REFINERY_PUBLIC_PORT`
+
+Publicly visible port of the Refinery instance.
+
+If you use a reverse proxy in front of the development server, you must set this variable.
+Otherwise, connections to the development server will fail due to cross-origin protection.
+
+**Default value:** equal to `REFINERY_LISTEN_PORT`