Workspace Setup

This guide walks you through setting up the Hello World Co-Op DAO 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 project consists of 15 repositories. Use this script to clone them all:

#!/bin/bash
# Save as clone-all.sh and run with: bash clone-all.sh

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

# Repository list
REPOS=(
  "hello-world-workspace"
  "docs"
  "frontend"
  "oracle-bridge"
  "ops-infra"
  "auth-service"
  "user-service"
  "membership"
  "dom-token"
  "governance"
  "treasury"
  "identity-gateway"
  "otter-camp"
  "marketplace"
  "proof-nfts"
  "education"
)

# 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 $BASE_DIR"

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 directory should look like:

~/git/
├── hello-world-workspace/   # VS Code workspace file
├── docs/                    # Documentation
├── frontend/                # React frontend
├── oracle-bridge/           # Off-chain service
├── ops-infra/               # Build scripts, CI/CD
├── auth-service/            # Session management canister
├── user-service/            # User registration canister
├── membership/              # ICRC-7 SBT canister
├── dom-token/               # ICRC-1/2 token canister
├── governance/              # Proposal system canister
├── treasury/                # Treasury management canister
├── identity-gateway/        # Internet Identity canister
├── otter-camp/              # Crowdfunding canister
├── marketplace/             # Vendor registry canister
├── proof-nfts/              # Reward NFTs canister
└── education/               # Education badges canister

Build All Canisters

Use the centralized build script to compile all Rust canisters:

cd ~/git/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 ~/git/auth-service/wasm/auth_service.wasm
✅ Wrote ~/git/user-service/wasm/user_service.wasm
✅ Wrote ~/git/membership/wasm/membership.wasm
...

Build a Single Canister

To build one canister manually:

cd ~/git/<canister-name>
cargo build --release --target wasm32-unknown-unknown

Install Frontend Dependencies

cd ~/git/frontend
npm install

cd app/www
npm install

Environment Configuration

Frontend Environment

Copy the example environment file:

cd ~/git/frontend/app/www
cp .env.example .env.local

Edit .env.local with your canister IDs:

VITE_AUTH_CANISTER_ID=<your-auth-canister-id>
VITE_USER_CANISTER_ID=<your-user-canister-id>
VITE_MEMBERSHIP_CANISTER_ID=<your-membership-canister-id>
# ... other canister IDs

Oracle Bridge Environment

cd ~/git/oracle-bridge
cp .env.example .env

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 ==="
BASE_DIR="${HOME}/git"
REPOS=("docs" "frontend" "auth-service" "membership" "dom-token" "governance")
for repo in "${REPOS[@]}"; do
  if [ -d "$BASE_DIR/$repo" ]; then
    echo "✅ $repo"
  else
    echo "❌ $repo (missing)"
  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 ~/git/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!