Improving Local Environment Setup and Build Process Documentation

[Ashish-CodeJourney]

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]

👍

[chavdarohit]

👍

[mkurapov]

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]

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

[melissahenderson]

For the tech writing team:

• The localenv README wasn't updated when we did the playground revisions in the Rafiki user doc. The README should be updated to match (where appropriate) the user doc.
• The user doc is missing the link to the Test Wallet in the note placed above "Running the local environment". The link in the README points to the GitHub repo. Both should either link to the repo or the new test wallet site.
• The environment setup commands in the user doc should be clarified, and the updates also made to the README
• We're working on updates to the glossary. The Rafiki README has links to glossary terms. We need to check whether any will break. Mohammed is working on the glossary.
• Updates to the Accounting concepts may break links in the Rafiki README. Melissa is working on accounting.
• The community call details in the Rafiki README are out of date.

This is not an exhaustive list of all needed updates. We still need to consider all the comments made above.