Getting Started Installation

Installation

This guide walks you through setting up the IOTA SDK development environment.

System Requirements

Required Software

Verify Installations

go version          # Should show 1.24 or later
psql --version      # Should show 17.x or later
node --version      # Should show 18.x or later
git --version       # Any recent version
just --version      # Any recent version

Database Setup

Create Database

Connect to PostgreSQL and create the development database:

# Connect to PostgreSQL
psql -U postgres
 
# Create database
CREATE DATABASE iota_sdk_dev;
 
# Create user (optional, you can use postgres)
CREATE USER iota_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE iota_sdk_dev TO iota_user;

Project Setup

Clone the Repository

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

Install Dependencies

# Install Go dependencies
go mod download
 
# Install Node.js dependencies for documentation
cd docs && pnpm install && cd ..

Configuration

Environment Variables

Create a .env file in the project root:

# Database (connection string is built from these; DATABASE_URL is not used)
DB_NAME=iota_sdk_dev
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=your_password
 
# Application
GO_APP_ENV=development
PORT=3200
 
# Session (DB-backed; cookie name)
SID_COOKIE_KEY=iota_sid
 
# Optional: Test endpoints
ENABLE_TEST_ENDPOINTS=true
 
# Optional: Spotlight search (global search + quick links; auto-enabled when MEILI_URL is set)
MEILI_URL=http://localhost:7700
MEILI_API_KEY=

Spotlight provides in-app global search (keyboard shortcut) and quick links. Initialization is automatic:

  • If MEILI_URL is set, Spotlight uses Meilisearch: the service is initialized and health-checked at startup. MEILI_API_KEY is optional (leave empty for local dev; set it when Meilisearch requires authentication).
  • If MEILI_URL is not set, Spotlight is disabled (no search backend); quick links are still registered but search will not return Meilisearch-backed results.

For full details (quick link API, translation keys), see Spotlight.

Configuration Files

The SDK uses a configuration system located in pkg/configuration/. Key configuration areas:

  • Database - Connection pools and query timeouts
  • Server - Port, TLS settings, timeouts
  • Session - Cookie settings and secrets
  • Localization - Supported languages and default locale

Build and Run

Database Migrations

Apply database schema:

just db migrate up

Build CSS

Generate the application stylesheet before starting the server:

just css

Run this command again after changing styles or templates. For automatic updates during development, run just css --watch in a separate terminal.

Start the Server

# Standard server
go run cmd/server/main.go
 
# Or using air (hot reload)
air

The server will start on http://localhost:3200 by default.

Verify Installation

Visit these URLs to verify:

  • http://localhost:3200 - Main application
  • http://localhost:3200/health - Liveness endpoint (returns JSON {"status":"healthy"}; checks DB and Spotlight)

Next Steps

Now that your environment is set up, continue to the Quick Start guide to understand the SDK’s core concepts and build your first feature.

Last updated on
Introduction DBCTL Operations