Installation

This guide covers installing IOTA SDK and setting up your development environment.

Prerequisites

Ensure these tools are installed before you begin:

Windows Setup

1. Go

Download from golang.org, install, and verify with:

go version

2. Air

Install Air for hot-reloading:

go install github.com/air-verse/air@v1.61.5

Add %USERPROFILE%\go\bin to your PATH.

3. Docker Desktop

Download and install from docker.com. Enable WSL 2 during installation.

4. Templ

Install the Templ templating engine:

go install github.com/a-h/templ/cmd/templ@v0.3.857

5. TailwindCSS

Install using npm (requires Node.js):

npm install -g tailwindcss

Or download the standalone executable:

curl.exe -sLO https://github.com/tailwindlabs/tailwindcss/releases/v3.4.13/download/tailwindcss-windows-x64.exe
rename tailwindcss-windows-x64.exe tailwindcss.exe

6. golangci-lint

Install the Go linter:

curl.exe -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.ps1 | powershell -Command -

7. cloudflared

Install Cloudflare Tunnel:

winget install --id Cloudflare.cloudflared

macOS/Linux Setup

1. Go

Install Go using your package manager or download from golang.org:

# Using Homebrew (macOS)
brew install go

# Verify installation
go version

2. Air

Install Air for hot-reloading:

go install github.com/air-verse/air@v1.61.5

3. Docker

Install Docker Desktop from docker.com or use your package manager:

# Homebrew (macOS)
brew install docker

# Or download Docker Desktop

4. Templ

Install the Templ templating engine:

go install github.com/a-h/templ/cmd/templ@v0.3.857

5. TailwindCSS

Install using npm or Homebrew:

# Using npm
npm install -g tailwindcss

# Using Homebrew (macOS)
brew install tailwindcss

6. golangci-lint

Install the Go linter:

curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin

7. cloudflared

Install Cloudflare Tunnel:

# macOS
brew install cloudflare/cloudflare/cloudflared

# Linux
curl -L --output cloudflared.deb https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared.deb

Development Setup

1. Clone the Repository 

git clone https://github.com/iota-uz/iota-sdk.git
cd iota-sdk

2. Create Environment File

Copy the example environment file:

# macOS/Linux
cp .env.example .env

# Windows
copy .env.example .env

Edit .env with your configuration as needed.

3. Install Dependencies 

make deps

Note for Windows: If make is unavailable, install via GnuWin32 or use Git Bash.

4. Run PostgreSQL

Ensure Docker is running, then start PostgreSQL:

make db local

5. Apply Migrations 

make db migrate up && make db seed

This creates the database schema and loads initial data.

6. Run TailwindCSS in Watch Mode

Open a new terminal and run:

make css watch

7. Start Development Server

In another terminal, start the development server with hot-reloading:

air

8. Access the Application

Development Tools Manager

For convenience, use the DevHub TUI tool to manage all development services:

make devtools

The DevHub allows you to:

  • Start/stop the development server
  • Toggle template file watching (templ generate --watch)
  • Toggle CSS file watching (TailwindCSS watch mode)
  • Manage local PostgreSQL database
  • Start/stop Cloudflare tunnel

Navigate with arrow keys, toggle services with Space/Enter, and quit with ‘q’.

Running Tests

Unit and Integration Tests

Run the full test suite:

make test

Run tests with coverage:

make test coverage

Run a specific test:

go test -v ./path/to/package -run TestSpecificName

E2E Testing with Playwright

The project includes Playwright end-to-end tests that run against a separate database.

Setup

Create and prepare the E2E database:

make e2e setup

Start E2E Server

In a separate terminal, start the server connected to the E2E database:

make e2e server

The server runs on port 3201 (development server on 3200).

Run Tests 

# Run all tests
make e2e test

# Interactive mode
make e2e run

# Direct npm command
cd e2e/
pnpm run test:headed

Available E2E Commands

  • make e2e setup - Create E2E database, run migrations, and seed
  • make e2e reset - Drop and recreate E2E database with fresh data
  • make e2e server - Start server on port 3201 (E2E database)
  • make e2e test - Run all E2E tests
  • make e2e run - Open Playwright UI mode
  • make e2e clean - Drop E2E database

Important Notes:

  • E2E tests use a separate database (iota_erp_e2e) from development (iota_erp)
  • E2E server runs on port 3201, development server runs on port 3200
  • Configuration: /e2e/.env.e2e, /e2e/playwright.config.ts

Code Documentation

Generate code documentation:

# For entire project
make docs

# With specific options
go run cmd/command/main.go doc -dir [directory] -out [output file] [-recursive] [-exclude "dir1,dir2"]

Options:

  • -dir: Target directory (default: current directory)
  • -out: Output file path (default: DOCUMENTATION.md)
  • -recursive: Process subdirectories
  • -exclude: Skip specified directories (comma-separated)

Troubleshooting

Windows Setup Issues

Make commands fail

Install via GnuWin32 or use Git Bash.

Docker issues

  • Ensure WSL 2 is properly configured
  • Run wsl --update as administrator
  • Restart Docker Desktop

Air hot-reloading problems

  • Verify Air is in your PATH
  • Check for .air.toml configuration
  • Try air init to create new configuration

PostgreSQL connection issues

  • Ensure Docker is running: docker ps
  • Verify database credentials in .env

Linting Issues

Do not run:

golangci-lint run --fix

It may break the code. If you encounter linting errors, try:

go mod tidy

Cloudflare Tunnel

To intercept incoming traffic from third-party systems (like payment gateways), use a Cloudflare Tunnel:

make tunnel

Next Steps

For help, see the FAQ or open a GitHub issue.

Back to top

IOTA SDK - Multi-tenant Business Management Platform