Workspace Setup

This guide walks you through setting up the Hello World DAO LLC development environment from scratch.

Prerequisites

Required Tools

Tool	Version	Purpose	Install Command
Rust	1.70+	Backend canisters	curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Node.js	18.x or 20.x LTS	Frontend, tooling	Use nvm or fnm
dfx	Latest stable	IC SDK	sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"
Git	2.x+	Version control	Package manager (apt, brew, etc.)

Rust Target

Add the WebAssembly compilation target:

rustup target add wasm32-unknown-unknown

PocketIC (Optional but Recommended)

PocketIC is required for running integration tests locally:

# Download PocketIC binary (check for latest version)
curl -L https://download.dfinity.systems/pocketic/pocket-ic-linux-x86_64.tar.gz | tar xz
chmod +x pocket-ic
sudo mv pocket-ic /usr/local/bin/

Clone All Repositories

The active fleet is 12 backend canisters + 6 frontend asset canister suites + oracle-bridge + notification-service + payment-gateway + supporting infra repos. Use this script to clone them all into your chosen <repo-root>:

#!/bin/bash
# Save as clone-all.sh and run with: bash clone-all.sh
# Set REPO_ROOT to wherever you want the repos checked out (default: ~/git)

GITHUB_ORG="Hello-World-Co-Op"
REPO_ROOT="${REPO_ROOT:-$HOME/git}"
mkdir -p "$REPO_ROOT"
cd "$REPO_ROOT"

# Repository list
REPOS=(
  # Workspace + docs + infra
  "hello-world-workspace"
  "docs"
  "ops-infra"

  # Off-chain services
  "oracle-bridge"
  "notification-service"
  "payment-gateway"

  # 12 backend canisters (Rust)
  "dom-token"
  "membership"
  "governance"
  "treasury"
  "otter-camp"
  "marketplace"
  "proof-nfts"
  "education"
  "identity-gateway"
  "user-service"
  "airdrop"
  "auth-service"      # DEPRECATED 2026-04-11 — clone for reference only

  # 6 frontend asset canister suites (React + Vite)
  "marketing-suite"
  "dao-suite"
  "dao-admin-suite"
  "governance-suite"
  "otter-camp-suite"
  "think-tank-suite"
)

# Clone each repository
for repo in "${REPOS[@]}"; do
  if [ -d "$repo" ]; then
    echo "Updating $repo..."
    (cd "$repo" && git pull)
  else
    echo "Cloning $repo..."
    git clone "https://github.com/${GITHUB_ORG}/${repo}.git"
  fi
done

echo "Done! All repositories are in $REPO_ROOT"

<repo-root> convention: Throughout this docs site, <repo-root> refers to whatever directory you cloned the repos into (e.g. ~/git, ~/code/hello-world, /workspace). Substitute your own path when copying commands. The clone script above respects $REPO_ROOT if exported.

Alternative: SSH Clone

If you have SSH keys configured:

git clone git@github.com:Hello-World-Co-Op/${repo}.git

Directory Structure

After cloning, your <repo-root> directory should look like:

<repo-root>/
├── hello-world-workspace/   # VS Code workspace + planning artifacts
├── docs/                    # Documentation (this site)
├── ops-infra/               # Build scripts, CI/CD, k8s manifests, dfx config

├── oracle-bridge/           # Off-chain Node.js service (port 8787 staging / 8788 prod)
├── notification-service/    # Transactional email microservice (port 3100, AX42-U)
├── payment-gateway/         # Unified payment microservice (port 3200, AX42-U)

├── dom-token/               # ICRC-1/2 token ledger canister
├── membership/              # ICRC-7 SBT credentials canister
├── governance/              # Proposal system canister
├── treasury/                # Role-gated payouts canister
├── otter-camp/              # Crowdfunding canister
├── marketplace/             # Vendor registry canister
├── proof-nfts/              # Deployment / contributor reward NFTs canister
├── education/               # Educator registry / achievement badges canister
├── identity-gateway/        # Internet Identity integration canister
├── user-service/            # User registration / profile canister
├── airdrop/                 # Token airdrop distribution canister
├── auth-service/            # DEPRECATED 2026-04-11 — clone for reference only

├── marketing-suite/         # www.helloworlddao.com (asset canister)
├── dao-suite/               # portal.helloworlddao.com (asset canister)
├── dao-admin-suite/         # admin.helloworlddao.com (asset canister)
├── governance-suite/        # governance.helloworlddao.com (asset canister)
├── otter-camp-suite/        # ottercamp.helloworlddao.com (asset canister)
└── think-tank-suite/        # think-tank.helloworlddao.com (asset canister)

Build All Canisters

Use the centralized build script to compile all Rust canisters:

cd <repo-root>/ops-infra/scripts
./build-wasm.sh

This script:

1. Iterates through all canister repositories
2. Runs cargo build --release --target wasm32-unknown-unknown
3. Copies WASM files to <repo>/wasm/<crate>.wasm

Build Output

Successful build produces WASM files:

Wrote <repo-root>/dom-token/wasm/dom_token.wasm
Wrote <repo-root>/membership/wasm/membership.wasm
Wrote <repo-root>/governance/wasm/governance.wasm
Wrote <repo-root>/treasury/wasm/treasury.wasm
...

Build a Single Canister

To build one canister manually:

cd <repo-root>/<canister-name>
cargo build --release --target wasm32-unknown-unknown

Install Frontend Suite Dependencies

Each suite is a standalone repo. Pick the one you're working in:

cd <repo-root>/<suite-name>     # e.g. dao-suite, marketing-suite, ...
npm install

Frontend suites depend on private packages from GitHub Packages — see FAS Local Setup Guide for the ~/.npmrc configuration step.

Environment Configuration

Suite Environment

Each suite has its own .env.example. Copy and edit per suite you're running:

cd <repo-root>/<suite-name>
cp .env.example .env.local

Edit .env.local with your canister IDs and oracle-bridge URL:

VITE_USER_SERVICE_CANISTER_ID=<your-user-service-canister-id>
VITE_MEMBERSHIP_CANISTER_ID=<your-membership-canister-id>
VITE_ORACLE_BRIDGE_URL=http://localhost:8787
# ... other canister IDs

Oracle Bridge Environment

cd <repo-root>/oracle-bridge
cp .env.example .env

notification-service Environment

cd <repo-root>/notification-service
cp .env.example .env
# Required: SERVICE_TOKEN (any string for local dev)
# Optional: RESEND_API_KEY (without it, runs in stub mode — no real email sent)

Run with: npm run dev (serves on http://localhost:3100).

payment-gateway Environment

cd <repo-root>/payment-gateway
cp .env.example .env
# Required for dev: SERVICE_TOKEN, DATABASE_URL (Neon Postgres)
# Tests run with no env vars (npm test)

Run with: npm run dev (serves on http://localhost:3200).

See Environment Variables for complete reference.

Verification Checklist

Run through this checklist to verify your setup:

Check	Command	Expected Result
Rust version	rustc --version	1.70.0 or higher
WASM target	rustup target list | grep wasm32	wasm32-unknown-unknown (installed)
Node.js version	node --version	v18.x.x or v20.x.x
dfx version	dfx --version	0.20.x or higher
Git version	git --version	2.x.x
PocketIC	pocket-ic --version	Version info displayed
Build script	./build-wasm.sh	All canisters build successfully
Frontend	cd frontend/app/www && npm run dev	Vite dev server starts

Quick Verification Script

#!/bin/bash
# Save as verify-setup.sh

echo "=== Checking Prerequisites ==="

echo -n "Rust: "
rustc --version || echo "NOT INSTALLED"

echo -n "WASM target: "
rustup target list | grep -q "wasm32-unknown-unknown (installed)" && echo "OK" || echo "MISSING"

echo -n "Node.js: "
node --version || echo "NOT INSTALLED"

echo -n "dfx: "
dfx --version || echo "NOT INSTALLED"

echo -n "Git: "
git --version || echo "NOT INSTALLED"

echo ""
echo "=== Checking Repositories ==="
REPO_ROOT="${REPO_ROOT:-$HOME/git}"
REPOS=("docs" "ops-infra" "oracle-bridge" "notification-service" "payment-gateway" "membership" "dom-token" "governance" "treasury" "dao-suite")
for repo in "${REPOS[@]}"; do
  if [ -d "$REPO_ROOT/$repo" ]; then
    echo "OK $repo"
  else
    echo "MISSING $repo"
  fi
done

echo ""
echo "=== Setup Complete ==="

Troubleshooting

Common Issues

1. WASM Target Not Found

Error: error[E0463]: can't find crate for 'std'

Solution:

rustup target add wasm32-unknown-unknown

2. dfx Not Found After Install

Error: command not found: dfx

Solution:

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.local/share/dfx/bin:$PATH"
source ~/.bashrc  # or source ~/.zshrc

3. Node.js Version Mismatch

Error: Various npm errors about incompatible versions

Solution:

# Using nvm
nvm install 20
nvm use 20

# Or using fnm
fnm install 20
fnm use 20

4. Permission Denied on build-wasm.sh

Error: Permission denied

Solution:

chmod +x <repo-root>/ops-infra/scripts/build-wasm.sh

5. Cargo Build Fails with Warnings

Error: Build fails due to warnings (RUSTFLAGS = "-D warnings")

Solution: Fix all warnings in the code before building. The project treats warnings as errors to maintain code quality.

6. PocketIC Tests Fail

Error: error: linking with 'cc' failed or socket errors

Solution:

• Ensure PocketIC binary is in PATH
• Set POCKET_IC_BIN environment variable if needed:

  export POCKET_IC_BIN=/usr/local/bin/pocket-ic

Getting Help

If you encounter issues not covered here:

1. Check the Error Catalog for error codes
2. Search existing GitHub issues
3. Ask in the team's communication channel
4. Email support@helloworlddao.com for urgent issues

Next Steps

Once your environment is set up:

1. Read the Architecture Overview to understand the system
2. Check the API Reference for canister interfaces
3. Review Contributing Guidelines before making changes
4. Pick a story from the sprint backlog and start coding!