SUDIGITAL

Appearance

Installation ​

This guide provides detailed installation instructions for the SUDIGITAL platform.

System Requirements ​

Minimum Requirements ​

  • Operating System: macOS, Linux, or Windows (with WSL2)
  • RAM: 8GB minimum, 16GB recommended
  • Storage: 5GB free space
  • Internet: Stable connection for package downloads

Software Requirements ​

  • Bun v1.0.0 or later
  • Node.js v18.0.0 or later
  • Git v2.30.0 or later
  • PostgreSQL (if running locally) or Azure PostgreSQL access

Installing Prerequisites ​

1. Install Bun ​

Bun is our primary package manager and runtime.

macOS/Linux ​

bash
curl -fsSL https://bun.sh/install | bash

Windows ​

bash
powershell -c "irm bun.sh/install.ps1 | iex"

Verify installation:

bash
bun --version

2. Install Node.js ​

Although we use Bun, Node.js is still required for some tooling.

bash
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install and use Node.js 18
nvm install 18
nvm use 18

Direct Installation ​

Download from nodejs.org and install the LTS version.

3. Install Git ​

macOS ​

bash
# Using Homebrew
brew install git

# Or download from git-scm.com

Linux (Ubuntu/Debian) ​

bash
sudo apt update
sudo apt install git

Windows ​

Download from git-scm.com

Platform Installation ​

1. Clone the Repository ​

bash
git clone https://github.com/sudigital/platform.git
cd platform

2. Install Dependencies ​

bash
# Install all workspace dependencies
bun install

This will install dependencies for all packages in the monorepo.

3. Environment Setup ​

Copy Environment Template ​

bash
cp .env.example .env

Configure Environment Variables ​

Edit the .env file with your specific configuration:

properties
# Database Configuration
DB_HOST=sudigitalpostgresqldev.postgres.database.azure.com
DB_PORT=5432
DB_USERNAME=your-database-username
DB_PASSWORD=your-database-password
DB_NAME=postgres
DB_SSL=true

# API Configuration
API_PORT=3001
API_ENVIRONMENT=development
API_CORS_ORIGINS=http://localhost:3000,http://localhost:5173

# Web Configuration
WEB_PORT=3000
WEB_API_URL=http://localhost:3001

# Documentation Configuration
DOCS_PORT=5173

4. Database Setup ​

  1. Create an Azure PostgreSQL instance
  2. Configure firewall rules to allow your IP
  3. Update the .env file with your connection details

Using Local PostgreSQL ​

bash
# Install PostgreSQL (macOS)
brew install postgresql
brew services start postgresql

# Install PostgreSQL (Ubuntu/Linux)
sudo apt update
sudo apt install postgresql postgresql-contrib
sudo systemctl start postgresql

# Create database
psql -c "CREATE DATABASE sudigital;"

5. Initialize Database ​

bash
# Run database initialization
bun run --filter='@sudigital/api' db:init

6. Build Packages ​

bash
# Build all packages
bun run build

Verification ​

1. Start Development Servers ​

bash
bun run dev

2. Check Services ​

API Server ​

bash
curl http://localhost:3001/api/health

Expected response:

json
{
  "status": "healthy",
  "timestamp": "2025-08-17T10:30:00.000Z",
  "version": "0.1.0"
}

Web Application ​

Visit http://localhost:3000

Documentation ​

Visit http://localhost:5173

API Documentation ​

Visit http://localhost:3001/docs

Optional Tools ​

Development Tools ​

Visual Studio Code Extensions ​

bash
# Install recommended extensions
code --install-extension ms-vscode.vscode-typescript-next
code --install-extension bradlc.vscode-tailwindcss
code --install-extension esbenp.prettier-vscode
code --install-extension ms-vscode.vscode-json

Database Tools ​

  • pgAdmin - PostgreSQL administration
  • DBeaver - Universal database tool
  • Azure Data Studio - For Azure PostgreSQL

Performance Tools ​

Bun Performance ​

bash
# Check Bun performance
bun --print-config

Node.js Performance ​

bash
# Check Node.js version and performance
node --version
node --v8-options | grep performance

Troubleshooting Installation ​

Common Issues ​

1. Permission Errors ​

bash
# Fix npm permissions (if needed)
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

2. Port Conflicts ​

bash
# Find processes using ports
lsof -i :3001
lsof -i :3000
lsof -i :5173

# Kill processes if needed
kill -9 <PID>

3. Database Connection ​

bash
# Test PostgreSQL connection
psql -h your-host -p 5432 -U your-username -d your-database

4. Memory Issues ​

If you encounter memory issues during installation:

bash
# Increase Node.js memory limit
export NODE_OPTIONS="--max-old-space-size=4096"
bun install

Environment-Specific Issues ​

Windows WSL2 ​

bash
# Enable WSL2 features
wsl --install
wsl --set-default-version 2

# Install Ubuntu
wsl --install -d Ubuntu

macOS M1/M2 ​

bash
# Install Rosetta if needed
softwareupdate --install-rosetta

Advanced Configuration ​

Custom Ports ​

Edit your .env file to use different ports:

properties
API_PORT=4001
WEB_PORT=4000
DOCS_PORT=4173

SSL Configuration ​

For production or custom SSL:

properties
# Enable SSL
SSL_ENABLED=true
SSL_CERT_PATH=/path/to/cert.pem
SSL_KEY_PATH=/path/to/key.pem

Docker Installation (Alternative) ​

bash
# Build and run with Docker
docker-compose up --build

Next Steps ​

After successful installation:

  1. Follow the Quick Start guide
  2. Explore the API documentation
  3. Learn about the Design System
  4. Check out Scalar Integration

Getting Help ​

If you encounter issues during installation:

  1. Check the troubleshooting section
  2. Review the API troubleshooting guide
  3. Open an issue on GitHub with:
    • Your operating system and version
    • Bun and Node.js versions
    • Complete error messages
    • Steps to reproduce the issue

Updating ​

Keep your installation up to date:

bash
# Update Bun
curl -fsSL https://bun.sh/install | bash

# Update dependencies
bun update

# Rebuild packages
bun run build