Local Deploy Guide

This guide explains how to build and deploy OHSHII Launcher canisters to a local dfx replica for testing and hash verification without deploying to mainnet.

Purpose

Local deployment allows you to:

✅ Verify that Docker-built WASM files install correctly
✅ Confirm that WASM hashes are deterministic and reproducible
✅ Test canister functionality locally before mainnet deployment
✅ Validate upgrade hooks and initialization logic
❌ NOT for production use - mainnet deployment requires ./docker-deploy.sh

Prerequisites

Required Software

Docker Desktop - Must be running

docker --version  # Should show Docker version
docker info       # Should not error

dfx (Internet Computer SDK)

dfx --version     # Should show dfx 0.15.0 or later

Bash shell - macOS/Linux terminal or WSL on Windows

Required Files

docker-build.sh - Builds reproducible WASM files
local-deploy.sh - Deploys to local replica (this guide)
Dockerfile - Docker build configuration

Quick Start

# 1. Build WASM files with Docker
./docker-build.sh

# 2. Deploy to local replica
./local-deploy.sh

# 3. Test (optional)
dfx canister call ohshii_launcher_backend get_version

# 4. Stop local replica when done
dfx stop

Detailed Workflow

Step 1: Build with Docker

./docker-build.sh

What this does:

Builds all canisters in Docker container (reproducible environment)
Optimizes WASM files with ic-wasm
Generates TypeScript declarations for sons_governance
Outputs *_docker.wasm files in project root
Saves SHA-256 hashes to WASM_HASHES.txt

Expected output:

ohshii_launcher_backend_docker.wasm
dao_storage_docker.wasm
pool_manager_docker.wasm
ohshii_governance_docker.wasm
sons_governance_docker.wasm

Time: ~5-10 minutes (first build), ~2-3 minutes (subsequent builds with Docker cache)

Step 2: Deploy Locally

./local-deploy.sh

What this does:

Checks if local dfx replica is running (starts it if not)
Creates canisters on local network (if they don’t exist)
Installs Docker-built WASM files with dfx canister install --mode reinstall
Queries each canister’s module hash with dfx canister info
Compares local WASM hash vs deployed module hash
Reports verification results

Expected output:

========================================
OHSHII-LAUNCHER - Local Deploy
========================================

Step 1/5: Checking dfx local replica...
  ✓ Local replica is already running

Step 2/5: Creating canisters (if needed)...
  ✓ Canisters created/verified

Step 3/5: Installing Docker WASM files...

1/4 ohshii_launcher_backend
  Deploying ohshii_launcher_backend...
    ✓ Installed
  Verifying ohshii_launcher_backend hash...
    [OK] Hash verified: abc123...

2/4 dao_storage
  ...

========================================
✓ All canisters deployed successfully!
✓ All hashes verified!
========================================

Time: ~2-3 minutes

Step 3: Test Locally (Optional)

# Get canister IDs
dfx canister id ohshii_launcher_backend

# Call a query method
dfx canister call ohshii_launcher_backend get_version

# Call an update method (example)
dfx canister call dao_storage get_campaign '("campaign-id-here")'

Step 4: Clean Up

# Stop local replica
dfx stop

# Optional: Remove local state (fresh start next time)
rm -rf .dfx

Hash Verification Explained

Why Hash Verification Matters

Hash verification ensures:

Reproducibility - Same source code → same WASM hash
Transparency - Community can verify deployed code matches source
Security - Prevents unauthorized code modifications
DAO Compliance - Required for governance proposals

How It Works

┌─────────────────────────────────────────────────────────────┐
│ 1. Docker Build                                             │
│    Source Code → Docker Container → WASM File               │
│    SHA-256(WASM) = abc123...                                │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. Local Deploy                                             │
│    WASM File → dfx canister install → Canister              │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. Hash Query                                               │
│    dfx canister info → Module Hash = abc123...              │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. Verification                                             │
│    SHA-256(WASM) == Module Hash ? ✓ : ✗                    │
└─────────────────────────────────────────────────────────────┘

Verification Success

[OK] Hash verified: 3a5f8c2e9b1d4a7c6e8f0b2d5a9c1e4f7b0d3a6c9e2f5b8d1a4c7e0f3b6d9a2c

This means:

✅ Local WASM file matches deployed canister
✅ Build is reproducible
✅ No tampering or corruption

Verification Failure

[ERROR] Hash mismatch!
  Expected (local):   3a5f8c2e...
  Actual (deployed):  9f2b4d7a...

This indicates:

❌ WASM file doesn’t match deployed code
❌ Possible causes:
- Wrong WASM file deployed
- Incomplete Docker build
- Corrupted WASM file
- Different source code version

Solution: Re-run ./docker-build.sh and ./local-deploy.sh

Canister Details

Deployed Canisters

Canister	Purpose	WASM File
`ohshii_launcher_backend`	Core business logic	`ohshii_launcher_backend_docker.wasm`
`dao_storage`	Data persistence	`dao_storage_docker.wasm`
`pool_manager`	Liquidity pool management	`pool_manager_docker.wasm`
`ohshii_governance`	Governance proposals	`ohshii_governance_docker.wasm`

NOT Deployed Locally

ohshii_launcher_frontend - Not needed for hash verification
External canisters (ICP ledger, cycles_ledger, etc.) - Not available locally

Differences: Local vs Mainnet

Aspect	Local Deployment	Mainnet Deployment
Script	`./local-deploy.sh`	`./docker-deploy.sh`
Network	Local dfx replica	Internet Computer mainnet
Canister IDs	Auto-generated (temporary)	Fixed production IDs
Password	Not required	Required (from `.env.deploy`)
External canisters	Not available	Fully functional
Frontend	Not deployed	Deployed to asset canister
Cost	Free (local cycles)	Real cycles consumed
Purpose	Testing & verification	Production deployment

Troubleshooting

Error: “Docker is not running”

Cause: Docker Desktop is not started

Solution:

# macOS: Open Docker Desktop app
open -a Docker

# Wait for Docker to start, then retry
./docker-build.sh

Error: “WASM files not found”

Cause: docker-build.sh was not run or failed

Solution:

# Run Docker build first
./docker-build.sh

# Then deploy
./local-deploy.sh

Error: “Local replica not responding”

Cause: dfx replica crashed or hung

Solution:

# Stop and clean
dfx stop
rm -rf .dfx

# Restart
dfx start --background --clean

# Retry deployment
./local-deploy.sh

Error: “Hash verification failed”

Cause: WASM file doesn’t match deployed canister

Solution:

# Rebuild from scratch
./docker-build.sh

# Redeploy with fresh WASMs
./local-deploy.sh

Warning: “Could not retrieve module hash”

Cause: Canister info query failed or output format changed

Solution:

# Manually check hash
dfx canister info ohshii_launcher_backend

# Compare with local WASM
shasum -a 256 ohshii_launcher_backend_docker.wasm

Advanced Usage

Deploy Specific Canister Only

# Create canister
dfx canister create ohshii_launcher_backend

# Install WASM
dfx canister install ohshii_launcher_backend \
  --wasm ./ohshii_launcher_backend_docker.wasm \
  --mode reinstall \
  --yes

# Verify hash
dfx canister info ohshii_launcher_backend
shasum -a 256 ohshii_launcher_backend_docker.wasm

Fresh Start (Clean State)

# Stop replica
dfx stop

# Remove all local state
rm -rf .dfx

# Start fresh
dfx start --background --clean

# Redeploy
./local-deploy.sh

Keep Replica Running Between Deployments

# First deployment
./local-deploy.sh

# Make code changes, rebuild
./docker-build.sh

# Redeploy (replica stays running)
./local-deploy.sh

Next Steps

After Successful Local Deployment

Test locally - Verify canister methods work as expected
Review logs - Check for any warnings or errors
Stop replica - dfx stop when done testing

Before Mainnet Deployment

Verify all hashes - Ensure local deployment succeeded
Review changes - Confirm code changes are correct
Backup data - Export important state if needed
Create .env.deploy - Add password for mainnet deployment
Run mainnet deploy - ./docker-deploy.sh

DOCKER_DEPLOY_GUIDE.md - Mainnet deployment guide
README.md - Project overview and setup
Architecture - Canister layout and governance scope

Best Practices

✅ Always build with Docker - Ensures reproducibility
✅ Verify hashes locally first - Catch issues before mainnet
✅ Test upgrade hooks - Ensure post_upgrade works correctly
✅ Stop replica when done - Frees system resources
❌ Never use local for production - Always use mainnet for real users

Summary

# Complete workflow
./docker-build.sh      # Build reproducible WASMs
./local-deploy.sh      # Deploy & verify locally
dfx stop               # Clean up when done

# For mainnet deployment
./docker-deploy.sh     # Deploy to production (requires password)

Remember: Local deployment is for testing and verification only. Always use ./docker-deploy.sh for mainnet deployments.

Local Deploy Guide

Purpose

Prerequisites

Required Software

Required Files

Quick Start

Detailed Workflow

Step 1: Build with Docker

Step 2: Deploy Locally

Step 3: Test Locally (Optional)

Step 4: Clean Up

Hash Verification Explained

Why Hash Verification Matters

How It Works

Verification Success

Verification Failure

Canister Details

Deployed Canisters

NOT Deployed Locally

Differences: Local vs Mainnet

Troubleshooting

Error: “Docker is not running”

Error: “WASM files not found”

Error: “Local replica not responding”

Error: “Hash verification failed”

Warning: “Could not retrieve module hash”

Advanced Usage

Deploy Specific Canister Only

Fresh Start (Clean State)

Keep Replica Running Between Deployments

Next Steps

After Successful Local Deployment

Before Mainnet Deployment

Related Documentation

Best Practices

Summary