Prerequisites
Required tools and setup for Almafrica development.
Required Software
.NET SDK 10.0
Backend development requires .NET 10 SDK.
macOS (Homebrew):
brew install dotnet@10
Windows: Download from dotnet.microsoft.com
Linux:
wget https://dot.net/v1/dotnet-install.sh -O dotnet-install.sh
chmod +x dotnet-install.sh
./dotnet-install.sh --channel 10.0
Verify:
dotnet --version # Should show 10.0.x
Node.js 20.x LTS
macOS (Homebrew):
brew install node@20
Windows: Download from nodejs.org
Linux (nvm):
nvm install 20
nvm use 20
Verify:
node --version # Should show v20.x.x
pnpm 9.x
Package manager for the web project.
npm install -g pnpm
Verify:
pnpm --version # Should show 9.x.x
Flutter 3.x
Mobile development requires Flutter 3.x with Dart 3.x.
All platforms: Download from flutter.dev
Verify:
flutter --version # Should show 3.x.x
flutter doctor # Check all dependencies
Docker
Used for local PostgreSQL and other services.
macOS:
brew install --cask docker
Windows/Linux: Download from docker.com
Verify:
docker --version
docker-compose --version
PostgreSQL 15.x (Optional)
Only needed if not using Docker for database.
macOS (Homebrew):
brew install postgresql@15
brew services start postgresql@15
Windows: Download from postgresql.org
Linux:
sudo apt install postgresql-15
Git 2.x
# macOS
brew install git
# Windows - download from git-scm.com
# Linux - sudo apt install git
IDE Setup
VS Code (Recommended)
- Install VS Code from code.visualstudio.com
- Install recommended extensions:
Backend (.NET):
- C# Dev Kit
- C#
- .NET Extension Pack
Web (Next.js):
- ESLint
- Prettier
- Tailwind CSS IntelliSense
Mobile (Flutter):
- Flutter
- Dart
General:
- GitLens
- EditorConfig
- Docker
JetBrains Rider (Alternative for Backend)
- Download from jetbrains.com/rider
- Install .NET Core plugin (usually included)
Visual Studio (Windows)
- Install Visual Studio 2022
- Select ".NET desktop development" workload
- Select "ASP.NET and web development" workload
Environment Variables
Each project has its own environment configuration:
# Root
cp .env.production.example .env
# Backend
cp backend/.env.example backend/.env
# Web
cp web/almafrica-web/.env.example web/almafrica-web/.env.local
# Mobile (configure in lib/core/config/)
Key Variables
| Variable | Purpose |
|---|---|
DATABASE_URL | PostgreSQL connection string |
JWT_SECRET | JWT signing key |
ASPNETCORE_ENVIRONMENT | Development/Staging/Production |
NEXT_PUBLIC_API_URL | Backend API URL for web |
Database Setup
Using Docker (Recommended)
docker-compose -f docker-compose.local.yml up -d postgres
Manual Setup
- Create database:
createdb almafrica
- Run migrations:
cd backend
dotnet ef database update
Troubleshooting
"dotnet command not found"
Add .NET to your PATH. The installer usually does this, but you may need to restart your terminal.
"pnpm: command not found"
Ensure pnpm is installed globally and npm global bin is in your PATH.
Flutter doctor shows issues
Run flutter doctor -v for detailed output and follow the suggestions.
Docker not starting
Ensure Docker Desktop is running. On macOS, check if the Docker icon appears in the menu bar.
Next Steps
Continue to Quick Start to run the project.