Improving Local Environment Setup and Build Process Documentation

Ashish-CodeJourney commented 1 week ago

Discussion:

As I was setting up the local environment for this project, I noticed that the file structure is a bit complex, and the current setup guide lacks sufficient detail specially for newbies. To ensure that new contributors can quickly get started and contribute effectively, I believe we could enhance the documentation with the following:

1. Prerequisites for Local Setup:

It would be helpful to list the prerequisites explicitly, such as the tools and software needed before starting. This might include:

OS requirements (e.g., Linux, macOS, or Windows versions)
Language versions (e.g., Java 17, Node.js 16)
Docker setup (if required)

2. Dependencies/Tools Required:

Clear instructions on installing the required tools should be added:

Docker: Specify the version and commands to install and run Docker if needed for containerization.
Package managers: If both npm (Node.js) and Gradle (Java) are required, mention the installation process for each.
Additional tools: Any other necessary tools like kubectl, docker-compose, etc., should be documented.

3. Build Systems:

Clarify the required build systems with step-by-step commands:

Gradle: How to run Gradle tasks (gradle build, gradle test, etc.) if applicable.
npm: How to install dependencies (npm install), build the project (npm run build), and handle scripts (npm run start, etc.).
If other build systems are used, specify their setup too (Maven, Make, etc.).

4. Database and Environment Setup:

The current setup doesn't fully mention the databases or environment variables required. I suggest adding:

Database: Instructions on how to set up the local database (e.g., MySQL, MongoDB), including connection details, schema setup, and seed data if applicable.
Environment Variables: Define what environment variables are required, how to set them (e.g., .env file), and what values they should contain (with example files or documentation).

5. Step-by-Step Setup Guide:

We could improve the setup guide by including:

Commands to clone the repository and install the dependencies.
Steps to set up any services using Docker Compose or similar.
Clear instructions for running tests and starting the application locally.

Example:

# Clone the repository
git clone <repo-url>

# Navigate into the project directory
cd <project-directory>

# Set up Docker containers
docker-compose up

# Install npm dependencies
npm install

# Build the project using npm / pnpm or Gradle
pnpm run build
gradle build

# Start the application
npm run start

# Run tests
npm test

This level of detail would greatly assist future contributors and streamline the onboarding process. I'd love to hear the thoughts of other contributors and maintainers on this!

Thank you!

[PS: contribution guidelines and docs are great for experienced devs but it will be good for newbies if we create a separate guide specially when its mono repo containing multiple sub repos]

Yash-Koshti commented 1 week ago

👍

chavdarohit commented 1 week ago

👍

mkurapov commented 1 week ago

Hi @Ashish-CodeJourney, thank you for opening up the issue!

Are you referencing the online docs (https://rafiki.dev/integration/playground/overview) or the README in localenv folder in particular?

I think clarifying the environment setup commands in the live rafiki.dev docs will be helpful in particular

Ashish-CodeJourney commented 1 week ago

Hi @Ashish-CodeJourney, thank you for opening up the issue!

Are you referencing the online docs (https://rafiki.dev/integration/playground/overview) or the README in localenv folder in particular?

I think clarifying the environment setup commands in the live rafiki.dev docs will be helpful in particular

https://github.com/interledger/rafiki/blob/main/README.md#environment-setup https://github.com/interledger/rafiki/blob/main/localenv

these both part's are just pointing to each other creating problems in dev's understanding of how to set local environment

additionally, for local development, Docker is required, so it's a good idea to add information about prerequisite [tools] for whatever is required

interledger / rafiki