Skip to content

Commit

Permalink
Add Developer Quickstart and Development Setup Documentation (#9666)
Browse files Browse the repository at this point in the history
This PR introduces the development.md file that outlines the steps to set up the development environment for the Hedera Mirror Node project. It aims to provide a clear and concise guide for developers, especially first-time contributors, to bootstrap their environment and start contributing to the project.

Key Changes:

Added a development.md file with:
1: List of required software and versions (Java, Docker, Gradle, Node.js).
2: Instructions for setting up the development environment.
3: Steps to compile the project.
4: Guide on running tests (unit and integration).
5: Troubleshooting common issues (e.g., Java version mismatch, dependency issues).
6: Links to coding standards and contributing guidelines.

---------

Signed-off-by: b-l-u-e <winnie.gitau282@gmail.com>
  • Loading branch information
b-l-u-e authored Nov 6, 2024
1 parent 4542640 commit a0d93a0
Show file tree
Hide file tree
Showing 3 changed files with 805 additions and 8 deletions.
20 changes: 12 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -96,15 +96,16 @@ documentation for more information.
## Documentation

- Components
- [GraphQL API](docs/graphql/README.md)
- [gRPC API](docs/grpc/README.md)
- [Importer](docs/importer/README.md)
- [Monitor](docs/monitor/README.md)
- [REST API](docs/rest/README.md)
- [REST Java API](docs/rest-java/README.md)
- [Rosetta API](docs/rosetta/README.md)
- [Web3 API](docs/web3/README.md)
- [GraphQL API](docs/graphql/README.md)
- [gRPC API](docs/grpc/README.md)
- [Importer](docs/importer/README.md)
- [Monitor](docs/monitor/README.md)
- [REST API](docs/rest/README.md)
- [REST Java API](docs/rest-java/README.md)
- [Rosetta API](docs/rosetta/README.md)
- [Web3 API](docs/web3/README.md)
- [Configuration](docs/configuration.md)
- [Development Guide](docs/development.md)
- [Contributing](docs/contributing.md)
- [Installation](docs/installation.md)
- [Troubleshooting](docs/troubleshooting.md)
Expand All @@ -122,6 +123,9 @@ If you have a question on how to use the product, please see our

Contributions are welcome. Please see the [contributing guide](docs/contributing.md) to see how you can get involved.

For detailed instructions on setting up the development environment, IDE configurations, and running tests, refer to
the [Development Guide](docs/development.md).

## Code of Conduct

This project is governed by the
Expand Down
217 changes: 217 additions & 0 deletions docs/development.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,217 @@
# Hedera Mirror Node Development Guide

This document outlines the process to set up a development environment for the Hedera Mirror Node project. It covers the
required software, environment setup, IDE configurations, project compilation, and how to run tests.

## Prerequisites

To contribute to the Hedera Mirror Node project, you need to install the following software and tools:

### 1. **Java 21**

Hedera Mirror Node requires **Java 21** or a later version for development.

- **Install Java 21**:

On Ubuntu and macOS:
```bash
curl -s "https://get.sdkman.io" | bash
sdk install java 21-tem
```

- **Verify Installation**:
```bash
java -version
```

- **You should see output similar to:**
```
openjdk version "21.0.4" 2024-XX-XX
```
If you are managing multiple Java versions, you can use the sdk tool to switch to Java 21:
```bash
sdk use java 21-tem
```

### 2. **Docker**

Docker is used to manage and run containerized services (such as databases) for the mirror node.

- **Install Docker**:

On Ubuntu:
```bash
sudo apt update
sudo apt install docker.io
sudo systemctl enable docker --now
sudo usermod -aG docker $USER # Optional: allows non-root access
```

On macOS:
```bash
brew install --cask docker
open /Applications/Docker.app
```

- **Verify Installation**:
```bash
docker --version
```

## Coding Standards

We follow best practices to ensure that code quality and maintainability remain high. Below are the key coding standards
to follow:

1. **Java Coding Style**: Follow the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html) for
writing clean and readable Java code.
2. **Kotlin Style**: Follow the [Kotlin Style Guide](https://kotlinlang.org/docs/coding-conventions.html) for
Kotlin-based files.
3. **Spotless Plugin**: The project uses the Spotless plugin to enforce consistent formatting. You can run this before
submitting code:
```bash
./gradlew spotlessApply
```

## IDE Setup

We recommend using **IntelliJ IDEA** or **Eclipse** for developing the Hedera Mirror Node. Below are configuration steps
for IntelliJ IDEA.

### IntelliJ IDEA Setup

1. **Install IntelliJ IDEA**:
- Download from [IntelliJ IDEA website](https://www.jetbrains.com/idea/).

2. **Set up Project SDK**:
- Go to `File > Project Structure > Project`.
- Set **Project SDK** to `Java 21` (or higher).
- Set **Project language level** to `21 - Record patterns, pattern matching for switch`.

3. **Gradle Configuration**:
- Ensure **Gradle JVM** is set to **Java 21**: Go to
`File > Settings > Build, Execution, Deployment > Build Tools > Gradle` and set the **Gradle JVM** to Java 21.

4. **Enable Save Actions**:
- Go to `File > Settings > Tools > Actions on Save`
- Enable the following save actions:
- `Reformat code`: Ensures consistent code style by reformatting code on save.
- `Optimize imports`: Automatically removes unused imports and arranges them.
- `Rearrange code`: Arranges code based on predefined rules.
- `Run code cleanup`: Cleans up unnecessary elements in the code.
- `Build project`: Automatically builds the project upon saving if needed.

5. **Import Java Code Style**:
- `Download`
the Java code file located in the repository at [docs/palantir-style.xml](docs/palantir-style.xml)
- In IntelliJ, go to `File > Settings > Editor > Code Style`.
- Click on `Java` under `Code Style`.
- In the Code Style section for Java, look for an option to import the downloaded code style file. This can
typically be found by clicking on the `gear icon (⚙️)` or the `Scheme dropdown`.
- Choose `Import Scheme > IntelliJ IDEA code style XML` or a similar option.
- `Import` the downloaded Java code style file to ensure consistent formatting across the project.

6. **Enable Docker Integration**:
- Enable Docker integration in IntelliJ if you are running containerized services directly from the IDE.

## Compiling the Project

The Hedera Mirror Node uses **Gradle** for building and managing dependencies.

1. **Clean and Build the Project**:
Run the following command to clean and build the project:

```bash
./gradlew clean build
```

This command will:
- Clean previous builds.
- Compile the source code.
- Download any required dependencies.
- Run tests.

2. **Compile Specific Subprojects**:
If you want to build a specific subproject (e.g., `monitor`), run:

```bash
./gradlew :monitor:build
```

## Running Tests

You can run the project’s tests using Gradle.

1. **Run All Tests**:
To run all the tests, use:

```bash
./gradlew test
```

2. **Run Tests for a Specific Subproject**:
To run tests for a specific subproject (e.g., `common`):

```bash
./gradlew :common:test
```

3. **Running Specific Tests**:
You can also run specific test classes or methods:

```bash
./gradlew test --tests "*YourTestClassName"
```

or:

```bash
./gradlew test --tests "*YourTestClassName.yourTestMethodName"
```

## Docker Integration for Local Development

The mirror node often depends on containerized services such as **PostgreSQL** or **Redis**. These services are
defined in `docker-compose` files within the repository.

1. **Start Docker Services**:
To start all services needed for local development:

```bash
docker compose up
```

2. **Stop Docker Services**:
To stop the services:

```bash
docker compose down
```

## Generating Artifacts (Images)

For production or deployment, you may need to generate Docker images.

1. **Build Docker Images**:
You can build Docker images using Gradle and specify custom properties to control the platform, registry, and tag for
the Docker image.

```bash
./gradlew dockerBuild \
-PdockerPlatform=linux/amd64 \
-PdockerRegistry=docker.io \
-PdockerTag=1.0.0-SNAPSHOT
```

2. **Push Docker Images**:
After building the Docker image, you can push it to the specified Docker registry to make it available for use in a
remote Kubernetes environment.

```bash
./gradlew dockerPush \
-PdockerPlatform=linux/amd64 \
-PdockerRegistry=docker.io \
-PdockerTag=1.0.0-SNAPSHOT
```
NB: Ensure you are logged into the Docker registry if authentication is required. This command will push the image
with the specified tag to the registry.
Loading

0 comments on commit a0d93a0

Please sign in to comment.