Owner: Engineering Team | Last Updated: 2026-01-30 | Status: Current
Prerequisites: Complete the Prerequisites checklist before starting this guide.
This guide walks you through setting up a complete WWAI (Walter AI) development environment from scratch. By the end, you will have all the tools, runtimes, and configurations needed to build, run, and test every component of the WWAI platform: the Next.js web app, Django backend, Flutter mobile app, browser/CMS plugins, and the containerized infrastructure layer.
Estimated time: 2-3 hours for a full setup.
Before starting, ensure you have:
wwai organization (request from your team lead)Required: Windows 10 (build 19041+) or Windows 11.
Enable WSL 2 (strongly recommended for backend and Docker work):
# Run PowerShell as Administrator
wsl --install
# Restart your machine when prompted
# After restart, set WSL 2 as default
wsl --set-default-version 2
Install Ubuntu 22.04 LTS from the Microsoft Store as your WSL distribution.
Install Windows Terminal from the Microsoft Store for a unified terminal experience.
Install essential build tools:
# Install Chocolatey (package manager)
Set-ExecutionPolicy Bypass -Scope Process -Force
[System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072
iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
# Install common tools
choco install make cmake git -y
Enable long file paths (required for node_modules):
# Run as Administrator
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
-Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
Note: For backend (Django) development, we strongly recommend running inside WSL 2 Ubuntu. Docker Desktop integrates with WSL 2 natively, and many Python packages build more reliably on Linux.
Required: macOS 13 (Ventura) or newer.
Install Xcode Command Line Tools:
xcode-select --install
Install Homebrew:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Install essential packages:
brew install git curl wget openssl readline sqlite3 xz zlib
brew install --cask iterm2 # recommended terminal
Apple Silicon (M1/M2/M3/M4) considerations:
softwareupdate --install-rosetta/opt/homebrew on ARM. Ensure your PATH includes it:echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
source ~/.zprofile
Required: Ubuntu 22.04 LTS or newer.
Update system packages:
sudo apt update && sudo apt upgrade -y
Install essential build tools:
sudo apt install -y build-essential curl wget git unzip zip \
libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev \
llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev \
libffi-dev liblzma-dev python3-openssl ca-certificates \
gnupg lsb-release software-properties-common
We standardize on Node.js 20.9.0 LTS across all JavaScript/TypeScript projects. Using nvm ensures everyone runs the exact same version.
macOS / Linux / WSL:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Reload shell configuration
source ~/.bashrc # or ~/.zshrc on macOS
Windows (native, not WSL):
Use nvm-windows:
# Download and run the installer from:
# https://github.com/coreybutler/nvm-windows/releases
# Choose the "nvm-setup.exe" installer
# After installation, open a new terminal and verify:
nvm version
nvm install 20.9.0
nvm use 20.9.0
nvm alias default 20.9.0
# Verify
node --version # Should output: v20.9.0
npm --version # Should output: 10.x.x
# pnpm is our preferred package manager for the web app
npm install -g pnpm@9
# Additional global tools
npm install -g typescript@5 turbo eslint prettier
Each repository includes an .nvmrc file. When you cd into a project directory:
# Automatically switches to the correct Node version
nvm use
Tip: Add the following to your
~/.bashrcor~/.zshrcto auto-switch oncd:autoload -U add-zsh-hook load-nvmrc() { local nvmrc_path="$(nvm_find_nvmrc)" if [ -n "$nvmrc_path" ]; then local nvmrc_node_version=$(nvm version "$(cat "${nvmrc_path}")") if [ "$nvmrc_node_version" = "N/A" ]; then nvm install elif [ "$nvmrc_node_version" != "$(nvm version)" ]; then nvm use fi fi } add-zsh-hook chpwd load-nvmrc load-nvmrc
The Django backend requires Python 3.11.x. We use pyenv for version management and venv for virtual environments.
macOS / Linux / WSL:
curl https://pyenv.run | bash
# Add to shell configuration (~/.bashrc or ~/.zshrc)
echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc
echo 'command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc
echo 'eval "$(pyenv init -)"' >> ~/.bashrc
source ~/.bashrc
Windows (native):
Use pyenv-win:
choco install pyenv-win -y
# Restart terminal, then verify:
pyenv --version
pyenv install 3.11.8
pyenv global 3.11.8
# Verify
python --version # Should output: Python 3.11.8
pip --version # Should output: pip 24.x
# Navigate to the backend repository
cd ~/projects/wwai-backend
# Create virtual environment
python -m venv .venv
# Activate the virtual environment
# macOS/Linux/WSL:
source .venv/bin/activate
# Windows (PowerShell):
.\.venv\Scripts\Activate.ps1
# Windows (Command Prompt):
.\.venv\Scripts\activate.bat
# Install dependencies
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt
pip install -r requirements-dev.txt
Create or update ~/.pip/pip.conf (or %APPDATA%\pip\pip.ini on Windows):
[global]
timeout = 60
index-url = https://pypi.org/simple/
extra-index-url = https://pypi.wwai.internal/simple/
[install]
trusted-host =
pypi.org
pypi.wwai.internal
Note: The internal PyPI mirror (
pypi.wwai.internal) hosts proprietary packages. You must be connected to the VPN to access it.
The WWAI mobile app is built with Flutter 3.24.x and Dart 3.5.x.
macOS:
brew install --cask flutter
# Or manual install:
git clone https://github.com/flutter/flutter.git -b stable ~/flutter
echo 'export PATH="$HOME/flutter/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
Linux / WSL:
sudo snap install flutter --classic
# Or manual install:
git clone https://github.com/flutter/flutter.git -b stable ~/flutter
echo 'export PATH="$HOME/flutter/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Windows:
choco install flutter -y
# Or download from https://docs.flutter.dev/get-started/install/windows
# Verify installation and identify missing dependencies
flutter doctor -v
# Accept Android licenses
flutter doctor --android-licenses
# Enable required platforms
flutter config --enable-web
flutter config --enable-android
flutter config --enable-ios # macOS only
flutter config --enable-macos-desktop # macOS only
| Platform | Requirement | Installation |
|---|---|---|
| Android | Android Studio + SDK 34 | brew install --cask android-studio or download from developer.android.com |
| iOS | Xcode 15+ (macOS only) | Install from Mac App Store |
| Web | Chrome | Already covered by OS setup |
cd ~/projects/wwai-mobile
flutter pub get
flutter run -d chrome # Quick test with web target
All services run in Docker containers for local development and production deployments on AWS ECS.
macOS:
brew install --cask docker
Windows:
choco install docker-desktop -y
After installation, open Docker Desktop and enable the WSL 2 backend in Settings > General.
Linux:
# Install Docker Engine (not Desktop)
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
# Add your user to the docker group
sudo usermod -aG docker $USER
newgrp docker
# Install Docker Compose v2
sudo apt install docker-compose-plugin -y
Adjust Docker Desktop resource limits for WWAI development:
| Resource | Minimum | Recommended |
|---|---|---|
| CPUs | 4 | 6+ |
| Memory | 6 GB | 8-10 GB |
| Disk | 40 GB | 60 GB |
docker --version # Docker 24.x or newer
docker compose version # Docker Compose v2.x
docker run hello-world # Should pull and run successfully
The backend repository includes a docker-compose.yml for spinning up the full local environment:
cd ~/projects/wwai-backend
docker compose up -d
# Services started:
# - wwai-api (Django REST API) → http://localhost:8000
# - wwai-db (PostgreSQL 15) → localhost:5432
# - wwai-redis (Redis 7) → localhost:6379
# - wwai-celery (Celery worker)
# - wwai-mailhog (Email testing) → http://localhost:8025
# Install AWS CLI v2
# macOS:
brew install awscli
# Linux:
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip && sudo ./aws/install
# Configure credentials (get from your team lead)
aws configure
# Authenticate with ECR
aws ecr get-login-password --region us-east-1 | \
docker login --username AWS --password-stdin \
<ACCOUNT_ID>.dkr.ecr.us-east-1.amazonaws.com
# Set identity (use your company email)
git config --global user.name "Your Full Name"
git config --global user.email "you@wwai.com"
# Set default branch name
git config --global init.defaultBranch main
# Set pull strategy
git config --global pull.rebase true
# Enable credential caching
git config --global credential.helper cache --timeout=3600
# Set default editor
git config --global core.editor "code --wait" # VS Code
# git config --global core.editor "vim" # Vim
# Line ending normalization
# Windows:
git config --global core.autocrlf true
# macOS/Linux:
git config --global core.autocrlf input
git config --global alias.co checkout
git config --global alias.br branch
git config --global alias.ci commit
git config --global alias.st status
git config --global alias.lg "log --oneline --graph --decorate --all"
git config --global alias.unstage "reset HEAD --"
git config --global alias.last "log -1 HEAD"
git config --global alias.sync "!git fetch origin && git rebase origin/main"
We recommend signing commits with GPG keys for verified commits on GitHub:
# Install GPG
# macOS:
brew install gnupg
# Linux:
sudo apt install gnupg -y
# Generate a GPG key
gpg --full-generate-key
# Choose: RSA and RSA, 4096 bits, no expiration
# List keys
gpg --list-secret-keys --keyid-format=long
# Configure Git to use your key
git config --global user.signingkey <YOUR_KEY_ID>
git config --global commit.gpgsign true
# Export public key and add to GitHub
gpg --armor --export <YOUR_KEY_ID>
# Copy output to GitHub > Settings > SSH and GPG Keys > New GPG Key
# Generate Ed25519 key (preferred)
ssh-keygen -t ed25519 -C "you@wwai.com" -f ~/.ssh/id_ed25519_github
# If your system doesn't support Ed25519, use RSA:
# ssh-keygen -t rsa -b 4096 -C "you@wwai.com" -f ~/.ssh/id_rsa_github
When prompted for a passphrase, set a strong passphrase. This is required by our security policy.
macOS:
# Start the agent
eval "$(ssh-agent -s)"
# Add to macOS keychain
ssh-add --apple-use-keychain ~/.ssh/id_ed25519_github
# Configure SSH to use the keychain
cat >> ~/.ssh/config << 'EOF'
Host github.com
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519_github
AddKeysToAgent yes
UseKeychain yes
EOF
Linux / WSL:
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519_github
# Configure SSH
cat >> ~/.ssh/config << 'EOF'
Host github.com
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519_github
AddKeysToAgent yes
EOF
Windows (PowerShell):
# Start SSH agent service
Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent
ssh-add "$env:USERPROFILE\.ssh\id_ed25519_github"
# Copy the public key to clipboard
# macOS:
pbcopy < ~/.ssh/id_ed25519_github.pub
# Linux:
xclip -selection clipboard < ~/.ssh/id_ed25519_github.pub
# Windows:
clip < ~/.ssh/id_ed25519_github.pub
Then navigate to GitHub > Settings > SSH and GPG keys > New SSH key, paste the key, and save.
ssh -T git@github.com
# Expected output: "Hi <username>! You've successfully authenticated..."
VS Code is our recommended editor for all WWAI development. Install it from code.visualstudio.com.
Required extensions:
| Extension | ID | Purpose |
|---|---|---|
| ESLint | dbaeumer.vscode-eslint |
JavaScript/TypeScript linting |
| Prettier | esbenp.prettier-vscode |
Code formatting |
| Tailwind CSS IntelliSense | bradlc.vscode-tailwindcss |
Tailwind autocomplete |
| Python | ms-python.python |
Python language support |
| Pylance | ms-python.vscode-pylance |
Python type checking |
| Django | batisteo.vscode-django |
Django template support |
| Flutter | Dart-Code.flutter |
Flutter/Dart support |
| Dart | Dart-Code.dart-code |
Dart language support |
| Docker | ms-azuretools.vscode-docker |
Dockerfile/Compose support |
| GitLens | eamodio.gitlens |
Enhanced Git integration |
| Thunder Client | rangav.vscode-thunder-client |
API testing |
| EditorConfig | editorconfig.editorconfig |
Consistent editor settings |
| Error Lens | usernamehw.errorlens |
Inline error display |
Install all required extensions at once:
code --install-extension dbaeumer.vscode-eslint \
--install-extension esbenp.prettier-vscode \
--install-extension bradlc.vscode-tailwindcss \
--install-extension ms-python.python \
--install-extension ms-python.vscode-pylance \
--install-extension batisteo.vscode-django \
--install-extension Dart-Code.flutter \
--install-extension Dart-Code.dart-code \
--install-extension ms-azuretools.vscode-docker \
--install-extension eamodio.gitlens \
--install-extension rangav.vscode-thunder-client \
--install-extension editorconfig.editorconfig \
--install-extension usernamehw.errorlens
Workspace settings (.vscode/settings.json is included in each repository, but ensure your user settings include):
{
"editor.formatOnSave": true,
"editor.defaultFormatter": "esbenp.prettier-vscode",
"editor.codeActionsOnSave": {
"source.fixAll.eslint": "explicit",
"source.organizeImports": "explicit"
},
"[python]": {
"editor.defaultFormatter": "ms-python.python",
"editor.formatOnSave": true
},
"[dart]": {
"editor.defaultFormatter": "Dart-Code.dart-code",
"editor.formatOnSave": true
},
"typescript.tsdk": "node_modules/typescript/lib",
"files.trimTrailingWhitespace": true,
"files.insertFinalNewline": true,
"files.trimFinalNewlines": true
}
If you prefer JetBrains, the following are supported:
| IDE | Use For |
|---|---|
| WebStorm | Next.js web app, Chrome/Shopify/WordPress plugins |
| PyCharm Professional | Django backend |
| Android Studio | Flutter mobile app (also includes Flutter plugin) |
Note: JetBrains IDEs require a paid license. Check with your manager about the team license pool.
For terminal-based development, we maintain a shared Neovim configuration:
git clone git@github.com:wwai/dotfiles.git ~/wwai-dotfiles
ln -s ~/wwai-dotfiles/nvim ~/.config/nvim
Each project requires its own .env file. Template files (.env.example) are included in every repository.
# For the web app
cd ~/projects/wwai-app-main
cp .env.example .env.local
# For the backend
cd ~/projects/wwai-backend
cp .env.example .env
Critical environment variables you must configure:
| Variable | Project | Description | Where to Get It |
|---|---|---|---|
NEXT_PUBLIC_API_URL |
Web App | Backend API base URL | Use http://localhost:8000 locally |
NEXT_PUBLIC_STRIPE_KEY |
Web App | Stripe publishable key | 1Password Vault: "Stripe Dev" |
DATABASE_URL |
Backend | PostgreSQL connection string | Use postgresql://wwai:wwai@localhost:5432/wwai locally |
REDIS_URL |
Backend | Redis connection string | Use redis://localhost:6379/0 locally |
SECRET_KEY |
Backend | Django secret key | Generate: python -c "from django.core.management.utils import get_random_secret_key; print(get_random_secret_key())" |
AWS_ACCESS_KEY_ID |
Backend | AWS credentials | 1Password Vault: "AWS Dev" |
AWS_SECRET_ACCESS_KEY |
Backend | AWS credentials | 1Password Vault: "AWS Dev" |
AI_MODEL_ENDPOINT |
Backend | Inference endpoint URL | Use http://localhost:8080/predict locally or staging endpoint |
Security: Never commit
.envfiles. They are already in.gitignore. Shared secrets are stored in 1Password under the "Engineering" vault.
Run these commands to verify your setup is complete:
# Node.js
node --version # v20.9.0
npm --version # 10.x.x
pnpm --version # 9.x.x
# Python
python --version # Python 3.11.8
pip --version # pip 24.x
# Flutter
flutter --version # Flutter 3.24.x
dart --version # Dart 3.5.x
# Docker
docker --version # Docker 24.x+
docker compose version # v2.x
# Git
git --version # git 2.40+
ssh -T git@github.com # Authentication success
# AWS CLI
aws --version # aws-cli/2.x
If any check fails, refer to the relevant section above or ask in #dev-help on Slack.
| Problem | Cause | Solution |
|---|---|---|
nvm: command not found |
Shell not reloaded | Run source ~/.bashrc or source ~/.zshrc and ensure nvm init lines are present |
node_modules installation fails on Windows |
Long path names | Enable long paths (see Windows section) and use WSL 2 |
| Docker permission denied on Linux | User not in docker group | Run sudo usermod -aG docker $USER and log out/back in |
flutter doctor shows issues |
Missing platform tools | Follow the specific instructions flutter doctor provides |
| Python build errors on macOS | Missing Xcode tools | Run xcode-select --install |
| SSH connection refused | Key not added to agent | Run ssh-add ~/.ssh/id_ed25519_github |
| ECR login fails | AWS CLI not configured | Run aws configure and enter credentials from 1Password |
| Port conflicts (8000, 5432, etc.) | Other services running | Stop conflicting services or change ports in docker-compose.override.yml |
pip install fails with SSL errors |
Corporate proxy/VPN | Configure pip with --trusted-host pypi.org --trusted-host files.pythonhosted.org |
#dev-help for general questions, #infra for Docker/AWS issues| Date | Author | Change |
|---|---|---|
| 2026-01-30 | Admin | Initial creation |
Prev: Prerequisites | Next: Repository Map | Up: General