# Soroban DApp Setup Documentation

## Table of Contents
1. [Introduction](#introduction)
2. [Dependencies](#dependencies)
3. [Installation Instructions](#installation-instructions)
4. [Script Execution Instructions](#script-execution-instructions)
5. [Environment Variables Configuration](#environment-variables-configuration)
6. [Updating `preview_version.json`](#updating-preview_versionjson)
7. [Updating `quickstart.sh`](#updating-quickstartsh)
8. [Tutorial: Building and Running `esteblock/soroban-preview-docker` Image](#tutorial-building-and-running-esteblocksoroban-preview-docker-image)
9. [Acceptance Criteria](#acceptance-criteria)
10. [Troubleshooting](#troubleshooting)

## Introduction
Welcome to the official documentation for setting up a Soroban DApp! This guide will walk you through the entire process, from installing necessary dependencies to deploying a greeting contract to the testnet.

`@create-soroban-dapp` is both an npx script and a boilerplate DApp, inspired by the ink!athon project by Scio Labs and @create-t3-app by T3 Open Source for script mechanisms.

Read the docs here 📚📚

## Dependencies
To successfully set up a Soroban DApp, you need to have the following dependencies installed:

- **Docker**: Required for containerized environment setup.
- **Node.js**: Version 12 or higher.
- **npm** or **yarn**: Package managers for managing Node.js packages.

## Installation Instructions

### Docker
Docker is an essential tool for containerization, which allows you to package and run your applications in isolated environments.

#### Steps to Install Docker

1. **Download Docker:**
- Visit the [Docker official website](https://www.docker.com/products/docker-desktop) and download Docker Desktop for your operating system.

2. **Install Docker:**
- Follow the installation instructions provided on the Docker website for your specific OS.

3. **Verify Installation:**
- Open a terminal or command prompt and run the following command to verify Docker is installed correctly:

     docker --version

- You should see the Docker version information if the installation was successful.

## Node.js Installation

Node.js is a JavaScript runtime built on Chrome's V8 JavaScript engine, and npm (Node Package Manager) is the default package manager for Node.js.

### Windows

1. **Download Node.js:**
- Visit the [Node.js download page](https://nodejs.org/).
- Download the Windows Installer (MSI) for the latest LTS (Long Term Support) version.

2. **Install Node.js:**
- Run the downloaded `.msi` installer.
- Follow the installation prompts and accept the license agreement.
- Choose the installation path (default is recommended).
- Ensure that the "Install npm" option is checked.

3. **Verify Installation:**
- Open Command Prompt and run the following commands:

     node --version
     npm --version

- You should see the installed versions of Node.js and npm.

### macOS

1. **Download Node.js:**
- Visit the [Node.js download page](https://nodejs.org/).
- Download the macOS Installer (PKG) for the latest LTS version.

2. **Install Node.js:**
- Open the downloaded `.pkg` installer.
- Follow the installation prompts and accept the license agreement.

3. **Verify Installation:**
- Open Terminal and run the following commands:

     node --version
     npm --version

- You should see the installed versions of Node.js and npm.

### Linux

1. **Use NodeSource Binaries (recommended for most distributions):**

- Open Terminal and run the following commands to install Node.js and npm:

     curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
     sudo apt-get install -y nodejs

2. **Verify Installation:**
- Run the following commands:

     node --version
     npm --version

- You should see the installed versions of Node.js and npm.

## Installing Yarn

Yarn is an alternative package manager to npm, known for its speed and reliability.

### Windows

1. **Install via npm:**
- Open Command Prompt and run:

     npm install --global yarn

2. **Verify Installation:**
- Run the following command:

     yarn --version

- You should see the installed version of Yarn.

### macOS

1. **Install via Homebrew:**
- Open Terminal and run:

     brew install yarn

2. **Verify Installation:**
- Run the following command:

     yarn --version

- You should see the installed version of Yarn.

### Linux

1. **Install via npm:**
- Open Terminal and run:

     npm install --global yarn

2. **Verify Installation:**
- Run the following command:

     yarn --version

- You should see the installed version of Yarn.

## Example Commands for Using npm and Yarn

- **Installing a Package (e.g., Express):**

  npm install express
  # or
  yarn add express

- **Running a Script:**

  npm run <script-name>
  # or
  yarn run <script-name>

- **Updating Packages:**

  npm update
  # or
  yarn upgrade

By following these steps, you will have Node.js, npm, and Yarn installed on your system, allowing you to manage and run JavaScript packages efficiently.

## Script Execution Instructions

### Usage
To create a new Soroban DApp project, execute one of the following commands:

npx create-soroban-dapp@latest

or

npm create soroban-dapp@latest

Then, navigate inside the new project repository:

cd <your-new-project>

### Running the Setup Script
After running the `create-soroban-dapp` npx script, set up the project by executing:

bash quickstart.sh standalone

## Environment Variables Configuration
Proper configuration of environment variables is crucial for the correct functioning of your Soroban DApp. Follow these steps:

1. **Copy the `.env.example` file to `.env`:**

   cp .env.example .env

2. **Edit the `.env` file:**
- Open the `.env` file in a text editor.
- Set the `ADMIN_SECRET_KEY` and `MAINNET_RPC_URL` values according to your setup.

Example:

ADMIN_SECRET_KEY=your_admin_secret_key
MAINNET_RPC_URL=your_mainnet_rpc_url

## Updating `preview_version.json`
Ensure the `preview_version.json` file contains the correct preview version:

{
  "previewVersion": "21.0.1"
}

## Updating `quickstart.sh`
Update the `quickstart.sh` script to consider both `.env` files when running and expose port 3000:

#!/bin/bash

# Load environment variables
if [ -f .env ]; then
  export $(cat .env | xargs)
fi

if [ -f .env.local ]; then
  export $(cat .env.local | xargs)
fi

# Run the Soroban preview image
docker run -p 3000:3000 --env-file .env esteblock/soroban-preview:21.0.1

## Tutorial: Building and Running `esteblock/soroban-preview-docker` Image
This tutorial will guide you through the process of building and running the `esteblock/soroban-preview-docker` image with version 21.0.1.

### Step-by-Step Instructions

1. **Build the Docker Image:**

   docker build -t esteblock/soroban-preview:21.0.1 .

2. **Run the Docker Image:**

   bash quickstart.sh standalone

## Acceptance Criteria
To ensure the documentation is effective, users should be able to deploy a greeting contract to the testnet by following the updated documentation. All steps should be clear and concise, and the deployment process should work as expected.

## Troubleshooting

### If the npm Create Script Malfunctions
The script is in its early stages and may not function perfectly on every OS and configuration. If the script does not function properly, please report to `@benjaminsalon` on the Stellar Developer Discord channel.

### Manual Cloning
If the create script malfunctions, you can manually clone the repo:

git clone [e-mail]:paltalabs/create-soroban-dapp.git

The DApp will not be in the root folder; this folder is occupied by the npx script. You will find the DApp in the subfolder `soroban-react-dapp`:

cd soroban-react-dapp

From there, it is a normal Next.js app. Install dependencies using your preferred package manager:

yarn install
# or
npm install
# or
pnpm install

---

By following this documentation, you should be able to set up, configure, and run your Soroban DApp seamlessly. Enjoy building your decentralized applications with Soroban! If you encounter any issues, feel free to reach out to the community or the maintainers for support.