feat(docs): Improve documentation for local coordinator development (#1037)

* Create local-development-guide.md

Signed-off-by: Gengar <creeptogengar@gmail.com>

* Update README.md

Signed-off-by: Gengar <creeptogengar@gmail.com>

* Update get-started.md

Signed-off-by: Gengar <creeptogengar@gmail.com>

* Update local-development-guide.md

Signed-off-by: Gengar <creeptogengar@gmail.com>

* Update docs/local-development-guide.md

Co-authored-by: jonesho <81145364+jonesho@users.noreply.github.com>
Signed-off-by: Gengar <creeptogengar@gmail.com>

* Update docs/local-development-guide.md

Co-authored-by: jonesho <81145364+jonesho@users.noreply.github.com>
Signed-off-by: Gengar <creeptogengar@gmail.com>

* Update docs/local-development-guide.md

Co-authored-by: jonesho <81145364+jonesho@users.noreply.github.com>
Signed-off-by: Gengar <creeptogengar@gmail.com>

* Update docs/local-development-guide.md

Co-authored-by: jonesho <81145364+jonesho@users.noreply.github.com>
Signed-off-by: Gengar <creeptogengar@gmail.com>

---------

Signed-off-by: Gengar <creeptogengar@gmail.com>
Co-authored-by: jonesho <81145364+jonesho@users.noreply.github.com>

README.md

@@ -29,6 +29,8 @@ It serves developers by making the Linea tech stack open source under the [Apach
 
 If you already have an understanding of the tech stack, use our [Get Started](docs/get-started.md) guide.
 
+For developers looking to build services locally (e.g., the coordinator), see our detailed [Local Development Guide](docs/local-development-guide.md).
+
 ## Looking for the Linea code?
 
 Linea's stack is made up of multiple repositories, these include:

docs/get-started.md

@@ -84,3 +84,5 @@ If you want bigger conflations, increase the deadline accordingly.
 ## Next steps
 
 Consider reviewing the [Linea architecture](architecture-description.md) description.
+
+For detailed instructions on local development and building services locally, see the [Local Development Guide](local-development-guide.md).

docs/local-development-guide.md

@@ -0,0 +1,172 @@
+# Local Development Guide
+
+This guide provides instructions for setting up and running Linea services locally, with a specific focus on the coordinator service.
+
+## Prerequisites
+
+Before you start, make sure you have the following installed:
+
+- Node.js v20 or higher
+- Docker v24 or higher
+  - Docker should have ~16 GB of Memory and 4+ CPUs to run the entire stack
+- Docker Compose version v2.19+
+- Make v3.81+
+- Pnpm v9.14.4 (https://pnpm.io/installation)
+- Java Development Kit (JDK) 21 (required for building the coordinator)
+- Gradle 8.5+ (for building Java-based services)
+
+## Building the Coordinator Locally
+
+The coordinator is a Java-based service that orchestrates the Linea protocol's operations. You can build it locally using the following steps:
+
+### 1. Clone the Repository
+
+If you haven't already, clone the repository and navigate to the project directory:
+
+```bash
+git clone https://github.com/ConsenSys/linea-monorepo.git
+cd linea-monorepo
+```
+
+### 2. Install Dependencies
+
+Install the Node.js dependencies:
+
+```bash
+make pnpm-install
+```
+
+### 3. Build the Coordinator
+
+The coordinator can be built using Gradle:
+
+```bash
+./gradlew :coordinator:app:build
+```
+
+This will generate the coordinator JAR file in the `coordinator/app/build/libs` directory.
+
+### 4. Building the Coordinator Docker Image Locally
+
+To build a local Docker image of the coordinator:
+
+```bash
+# First build the coordinator JAR
+./gradlew coordinator:app:installDist
+
+# Then build the Docker image
+docker buildx build --file coordinator/Dockerfile --build-context libs=./coordinator/app/build/install/coordinator/lib --tag consensys/linea-coordinator:local .
+```
+
+## Running the Coordinator Locally
+
+There are two main ways to run the coordinator:
+
+### 1. Running as Part of the Full Stack
+
+The recommended way to run the coordinator is as part of the complete Linea stack:
+
+```bash
+# Start the entire stack with tracing v2 using your local coordinator image
+COORDINATOR_TAG=local make start-env-with-tracing-v2
+```
+
+This command:
+1. Starts all necessary services (L1 node, L2 node, sequencer, etc.)
+2. Deploys the required smart contracts
+3. Starts the coordinator service with your locally built image
+
+### 2. Running the Coordinator Standalone
+
+If you want to run just the coordinator for development purposes, you can use:
+
+```bash
+# Set necessary environment variables
+export POSTGRES_USER=postgres
+export POSTGRES_PASSWORD=postgres
+
+# Run only PostgreSQL database (required by coordinator)
+docker compose -f docker/compose-tracing-v2.yml up -d postgres
+
+# Run the coordinator with your local build
+java -Dvertx.configurationFile=config/coordinator/vertx-options.json \
+     -Dlog4j2.configurationFile=config/coordinator/log4j2-dev.xml \
+     -jar coordinator/app/build/libs/coordinator.jar \
+     --traces-limits-v2 config/common/traces-limits-v2.toml \
+     --smart-contract-errors config/common/smart-contract-errors.toml \
+     --gas-price-cap-time-of-day-multipliers config/common/gas-price-cap-time-of-day-multipliers.toml \
+     config/coordinator/coordinator-config-v2.toml
+```
+
+Note: When running the coordinator standalone, you'll need to ensure that all its dependencies (such as L1 and L2 nodes) are properly configured and running.
+
+## Configuration
+
+The coordinator uses several configuration files:
+
+- `config/coordinator/coordinator-config-v2.toml`: Main configuration file
+- `config/common/traces-limits-v2.toml`: Traces limits configuration
+- `config/common/smart-contract-errors.toml`: Smart contract errors configuration
+- `config/common/gas-price-cap-time-of-day-multipliers.toml`: Gas price cap multipliers
+
+For development, you may want to modify the following parameters in the coordinator configuration:
+
+- `conflation.conflation-deadline`: Controls how long the coordinator waits before conflating blocks (default is 6 seconds)
+- `l1-submission.blob.l1-endpoint`: Configure the connection to the L1 node for submitting blob tx (defaults to default.l1-endpoint)
+- `l1-submission.aggregation.l1-endpoint`: Configure the connection to the L1 node for submitting aggregation tx (defaults to default.l1-endpoint)
+- `conflation.l2-endpoint`: Configure the connection to the L2 node for conflation (defaults to default.l2-endpoint)
+- `l1-finalization-monitor.l2-endpoint`: Configure the connection to the L2 node for retrieving L2 block data (defaults to default.l2-endpoint)
+- `message-anchoring.l2-endpoint`: Configure the connection to the L2 node for submitting message anchoring tx (defaults to default.l2-endpoint)
+- `prover` section: Configure the paths for prover requests and responses
+
+## Troubleshooting
+
+### Docker Issues
+
+If you encounter issues with the Docker setup:
+
+```bash
+# Clean the environment and remove Docker volumes
+make clean-environment
+docker system prune --volumes
+```
+
+### Coordinator Connection Issues
+
+If the coordinator has trouble connecting to other services:
+
+1. Check that all required services are running:
+   ```bash
+   docker compose -f docker/compose-tracing-v2.yml ps
+   ```
+
+2. Verify network connectivity between containers:
+   ```bash
+   docker run --rm -it --network=docker_linea weibeld/ubuntu-networking bash
+   ping coordinator
+   ping postgres
+   ping l1-el-node
+   ```
+
+3. Check the coordinator logs:
+   ```bash
+   docker logs coordinator
+   ```
+
+## Development Workflow
+
+When developing the coordinator:
+
+1. Make your code changes
+2. Run tests: `./gradlew :coordinator:app:test`
+3. Build the coordinator: `./gradlew :coordinator:app:build`
+4. Build a local Docker image (as shown above)
+5. Start the environment with your local image
+6. Test your changes
+
+## Relevant Endpoints
+
+- Coordinator API: http://localhost:9545
+- Sequencer RPC: http://localhost:8545
+- Traces Node: http://localhost:8745
+- PostgreSQL: localhost:5432