Hello World DAO

Appearance

Environment Variables ​

This document lists all environment variables used across the Hello World Co-Op DAO platform.

Frontend (React + Vite) ​

Located in frontend/app/www/:

  • .env - Base configuration
  • .env.local - Local overrides (gitignored)
  • .env.staging - Staging environment
  • .env.production - Production environment

Canister Configuration ​

VariableDescriptionExample
VITE_USER_SERVICE_CANISTER_IDUser service canister principalj4rvr-3aaaa-aaaao-qkvfq-cai
VITE_AUTH_SERVICE_CANISTER_IDAuth service canister principallqy7q-dh777-77777-aaaaq-cai
VITE_INTERNET_IDENTITY_CANISTER_IDInternet Identity canisterrdmx6-jaaaa-aaaaa-aaadq-cai
VITE_NETWORKTarget network (local | ic)ic

OAuth Configuration ​

VariableDescriptionWhere to Get
VITE_GOOGLE_CLIENT_IDGoogle OAuth client IDGoogle Cloud Console
VITE_GITHUB_CLIENT_IDGitHub OAuth client IDGitHub Developer Settings
VITE_GITHUB_CLIENT_SECRETGitHub OAuth client secretGitHub Developer Settings

Security Notes:

  • Client IDs are safe to expose (public)
  • Client Secrets in VITE_ variables are bundled into the app
  • Rotate credentials every 90 days
  • Use different credentials per environment

Oracle Bridge ​

VariableDescriptionDefault
VITE_ORACLE_BRIDGE_URLOracle bridge service URLhttp://localhost:8787
VITE_ORACLE_BRIDGE_API_TOKENAPI authentication token(empty for local)

Environment Values:

EnvironmentURL
Localhttp://localhost:8787
Staginghttps://staging-oracle.helloworlddao.com
Productionhttps://oracle.helloworlddao.com

Analytics ​

VariableDescriptionDefault
VITE_POSTHOG_API_KEYPostHog project key-
VITE_POSTHOG_API_HOSTPostHog API hosthttps://us.i.posthog.com

Cross-App Navigation (FOS-1.2.7) ​

VariableDescriptionDefault
VITE_FOUNDERY_OS_URLURL for "Open FounderyOS" navigationhttp://127.0.0.1:5174

Environment Values:

EnvironmentFounderyOS URL
Localhttp://127.0.0.1:5174
Staginghttps://staging-foundery.helloworlddao.com (TBD)
Productionhttps://foundery.helloworlddao.com (TBD)

UI Configuration ​

VariableDescriptionOptions
VITE_DESIGN_VARIANTTheme variantsunrise, sunset, ocean, forest

Example .env.local ​

bash
# Local Development
VITE_USER_SERVICE_CANISTER_ID=uxrrr-q7777-77774-qaaaq-cai
VITE_AUTH_SERVICE_CANISTER_ID=lqy7q-dh777-77777-aaaaq-cai
VITE_INTERNET_IDENTITY_CANISTER_ID=rdmx6-jaaaa-aaaaa-aaadq-cai
VITE_NETWORK=local
VITE_ORACLE_BRIDGE_URL=http://localhost:8787
VITE_DESIGN_VARIANT=sunrise

foundery-os-suite (React + Vite) ​

The productivity suite application (foundery-os-suite/) shares authentication with the main DAO frontend via the same auth-service canister.

Located in foundery-os-suite/:

  • .env.local.example - Template with documentation
  • .env.local - Local overrides (gitignored)

Canister Configuration ​

VariableDescriptionExample
VITE_IC_HOSTIC replica URLhttp://127.0.0.1:4943
VITE_FOUNDERY_OS_CORE_CANISTER_IDProductivity data canisteruxrrr-q7777-77774-qaaaq-cai
VITE_AUTH_SERVICE_CANISTER_IDShared auth service canisterlqy7q-dh777-77777-aaaaq-cai

Cross-App Navigation (FOS-1.2.7) ​

VariableDescriptionDefault
VITE_DAO_FRONTEND_URLURL for "Back to DAO" navigationhttp://127.0.0.1:5173

Environment Values:

EnvironmentDAO Frontend URL
Localhttp://127.0.0.1:5173
Staginghttps://staging.helloworlddao.com
Productionhttps://www.helloworlddao.com

Example .env.local ​

bash
# Local Development
VITE_IC_HOST=http://127.0.0.1:4943
VITE_FOUNDERY_OS_CORE_CANISTER_ID=your-canister-id-here
VITE_AUTH_SERVICE_CANISTER_ID=your-auth-service-canister-id-here
VITE_DAO_FRONTEND_URL=http://127.0.0.1:5173

Shared Authentication ​

foundery-os-suite uses the same auth-service canister as the main frontend. When users authenticate:

  1. Login credentials are sent to auth-service.login_email_password()
  2. auth-service validates and returns session tokens
  3. Tokens are stored in localStorage (separate per origin)
  4. ProtectedRoute component validates tokens on navigation
  5. Expired access tokens trigger auth-service.refresh_tokens()

Important: Since foundery-os-suite and frontend are separate asset canisters (different origins), users must log in to each application separately. The same credentials work for both, but sessions are independent.

Oracle Bridge (Node.js) ​

Located in oracle-bridge/:

  • .env.example - Template with documentation
  • .env - Actual configuration (gitignored)

Server Configuration ​

VariableDescriptionDefault
NODE_ENVEnvironment modeproduction
PORTHTTP server port8787

SMTP Configuration (Email) ​

VariableDescriptionExample
SMTP_HOSTSMTP server host127.0.0.1
SMTP_PORTSMTP server port1025
SMTP_USERSMTP usernameemail@domain.com
SMTP_PASSSMTP password(Proton Bridge password)
SMTP_FROM_NOREPLYNo-reply sender addressnoreply@domain.com
SMTP_FROM_CONTACTContact sender addresscontact@domain.com

Security Configuration ​

VariableDescriptionNotes
SIGNING_PRIVATE_KEY_BASE64Ed25519 signing keyBase64 encoded
API_KEYAPI authentication keyGenerate securely
CANISTER_PUBLIC_KEYSCanister signature verificationJSON map

Canister Public Keys Format:

json
{
  "rrkah-fqaaa-aaaaa-aaaaq-cai": "Ylx8BF+FVY7nZxE8TN3nPvLF8NJCz3qPxNBBmVMj2g0=",
  "user-service-id": "pubkey2",
  "membership-id": "pubkey3"
}

External API Keys ​

VariableDescriptionService
PERSONA_API_KEYKYC verificationPersona
COMPLYADVANTAGE_API_KEYAML screeningComplyAdvantage
CIRCLE_API_KEYPayment processingCircle

Rate Limiting ​

VariableDescriptionDefault
TEMP_KEY_RATE_LIMITMax temp key requests per 24h5

Recommended Values:

EnvironmentValue
Local/Dev100
Staging10
Production5

Example .env ​

bash
# Server
NODE_ENV=production
PORT=8787

# SMTP (Proton Mail Bridge)
SMTP_HOST=127.0.0.1
SMTP_PORT=1025
SMTP_USER=email@helloworlddao.com
SMTP_PASS=bridge-password-here
SMTP_FROM_NOREPLY=noreply@helloworlddao.com
SMTP_FROM_CONTACT=contact@helloworlddao.com

# Security
SIGNING_PRIVATE_KEY_BASE64=your-base64-private-key
API_KEY=your-secure-api-key

# Canister Auth
CANISTER_PUBLIC_KEYS={"user-service-id":"pubkey1"}

# External APIs
PERSONA_API_KEY=persona_live_xxx
COMPLYADVANTAGE_API_KEY=xxx
CIRCLE_API_KEY=xxx

# Rate Limiting
TEMP_KEY_RATE_LIMIT=5

GitHub Actions Secrets ​

Configure these in repository Settings → Secrets and variables → Actions:

Deployment Secrets ​

SecretDescriptionUsed By
DFX_IDENTITY_PEMdfx identity private keyAll canister deploys
DFX_IDENTITY_PRINCIPALdfx identity principalDeployment workflows
CYCLES_WALLET_IDCycles wallet canister IDCycles top-up

OAuth Secrets ​

SecretDescriptionFrontend Name
OAUTH_GOOGLE_CLIENT_IDGoogle OAuth IDVITE_GOOGLE_CLIENT_ID
OAUTH_GITHUB_CLIENT_IDGitHub OAuth IDVITE_GITHUB_CLIENT_ID
OAUTH_GITHUB_CLIENT_SECRETGitHub OAuth secretVITE_GITHUB_CLIENT_SECRET

Note: GitHub doesn't allow secrets starting with GITHUB_, so OAuth secrets use OAUTH_ prefix.

Oracle Bridge Secrets ​

SecretDescription
ORACLE_SIGNING_KEYEd25519 private key (base64)
ORACLE_API_KEYAPI authentication key
PERSONA_API_KEYPersona KYC API key

Analytics Secrets ​

SecretDescription
POSTHOG_API_KEYPostHog project key

dfx Configuration ​

Network settings are in ops-infra/dfx.networks.json:

json
{
  "local": {
    "bind": "127.0.0.1:4943",
    "type": "ephemeral"
  },
  "testnet": {
    "providers": ["https://ic0.app"]
  },
  "mainnet": {
    "providers": ["https://ic0.app"]
  }
}

Most canister repos symlink to this shared config.

Local Development Setup ​

1. Frontend Setup ​

bash
cd frontend/app/www

# Copy example files
cp .env.example .env
cp .env.local.example .env.local

# Edit with your local canister IDs
nano .env.local

2. Oracle Bridge Setup ​

bash
cd oracle-bridge

# Copy example file
cp .env.example .env

# Configure for local development
nano .env

Minimum local config:

bash
NODE_ENV=development
PORT=8787
TEMP_KEY_RATE_LIMIT=100
# Leave other fields empty for local dev

3. foundery-os-suite Setup ​

bash
cd foundery-os-suite

# Copy example file
cp .env.local.example .env.local

# Edit with your local canister IDs
nano .env.local

4. Get Local Canister IDs ​

After deploying canisters locally:

bash
# Get user-service canister ID
cd ~/git/user-service
dfx canister id user_service --network local

# Get auth-service canister ID
cd ~/git/auth-service
dfx canister id auth_service --network local

# Get foundery-os-core canister ID (when available)
cd ~/git/foundery-os-core
dfx canister id foundery_os_core --network local

Update .env.local files with these IDs:

  • frontend/app/www/.env.local - For DAO Dashboard
  • foundery-os-suite/.env.local - For Productivity Suite

Environment-Specific Values ​

Local Development ​

bash
VITE_NETWORK=local
VITE_ORACLE_BRIDGE_URL=http://localhost:8787
TEMP_KEY_RATE_LIMIT=100

Staging ​

bash
VITE_NETWORK=ic
VITE_ORACLE_BRIDGE_URL=https://staging-oracle.helloworlddao.com
TEMP_KEY_RATE_LIMIT=10

Production ​

bash
VITE_NETWORK=ic
VITE_ORACLE_BRIDGE_URL=https://oracle.helloworlddao.com
TEMP_KEY_RATE_LIMIT=5

Security Best Practices ​

  1. Never commit secrets - All .env files (except .example) are gitignored
  2. Use GitHub Secrets - Store production secrets in repository settings
  3. Rotate regularly - OAuth credentials every 90 days
  4. Environment separation - Different credentials per environment
  5. Minimal exposure - Only include secrets needed for each service

Troubleshooting ​

"Canister ID not found" ​

Ensure you've deployed canisters and updated .env.local:

bash
dfx canister id user_service --network local

"Network error" connecting to Oracle Bridge ​

  1. Verify oracle-bridge is running: npm run dev
  2. Check VITE_ORACLE_BRIDGE_URL matches the running port
  3. Ensure no firewall blocking localhost:8787

"OAuth login failed" ​

  1. Verify OAuth credentials in .env
  2. Check OAuth app redirect URIs match your development URL
  3. For GitHub, ensure correct scopes are configured

Hello World Co-Op DAO

Copyright 2024-present