Cross-Platform Setup Guide

This guide covers how to set up and run the Aitana Labs frontend and backend on different operating systems.

Prerequisites

All Platforms

Node.js 18+ - https://nodejs.org/
uv - Python package manager - https://docs.astral.sh/uv/

Platform-Specific Tools

Windows: Git Bash or PowerShell (recommended)
macOS: Terminal or iTerm2
Linux: Any terminal emulator

Installation

1. Install uv (Python Package Manager)

Windows (PowerShell)

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS/Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone Repository

git clone https://github.com/Aitana-Labs/frontend.git
cd frontend

3. Install Dependencies

Frontend Dependencies

npm install

Backend Dependencies

cd backend
uv sync
cd ..

4. Install Aitana CLI

# From the frontend root directory
uv tool install ./aitana --force

Server Management with Aitana CLI

The aitana CLI provides cross-platform server management with platform-specific optimizations:

Universal Commands

All these commands work identically across Windows, macOS, and Linux:

# Server control
aitana server start              # Start with cloud Firebase (default)
aitana server start --mode local # Start with Firebase emulators
aitana server status             # Check server status and PIDs
aitana server stop               # Stop all servers
aitana server restart            # Restart all servers

# Log management
aitana server logs               # View recent logs
aitana server logs -n 100        # View last 100 lines
aitana server logs -s frontend   # View frontend logs only
aitana server analyze            # Analyze logs for errors/warnings
aitana server clean-logs         # Clean all log files

Platform-Specific Behaviors

Windows

PID Detection: Uses netstat -ano instead of lsof
Log Following: Live log following (-f flag) falls back to showing recent logs
Process Management: Full psutil support for stopping/starting services

macOS/Linux

PID Detection: Uses lsof -ti :port as fallback when psutil permissions fail
Log Following: Full tail -f support for live log streaming
Process Management: Native Unix signal handling

Environment Configuration

Create .env.local in the frontend root directory:

NEXT_PUBLIC_FIREBASE_API_KEY=...
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=...
NEXT_PUBLIC_FIREBASE_PROJECT_ID=...
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=...
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=...
NEXT_PUBLIC_FIREBASE_APP_ID=...
NEXT_PUBLIC_ADMIN_EMAIL=...

# Optional
GOOGLE_CLOUD_PROJECT=aitana-multivac-dev
GOOGLE_CLOUD_LOCATION=europe-west1
GOOGLE_GENAI_USE_VERTEXAI=true

Development Workflow

Quick Start

# 1. Start servers
aitana server start

# 2. Check status
aitana server status

# 3. View logs if needed
aitana server logs

# 4. Stop when done
aitana server stop

Alternative Method (Manual)

If you prefer not to use the aitana CLI:

Terminal 1 - Backend

cd backend
uv run app.py

Terminal 2 - Frontend

npm run dev:cloud  # or npm run dev for local Firebase

Platform-Specific Notes

Windows

PowerShell vs Command Prompt: PowerShell is recommended for better Unicode support
Git Bash: Also works well and provides Unix-like commands
Windows Terminal: Modern terminal with better rendering for Rich tables
Permissions: Usually no special permissions needed for development

macOS

Homebrew: Alternative way to install Node.js and other tools
Permissions: May need sudo for global npm packages
Terminal: Built-in Terminal.app works fine, iTerm2 has more features

Linux

Package Managers: Use your distribution’s package manager for Node.js
Permissions: Avoid sudo with uv and npm when possible
Shell: Works with bash, zsh, fish, and other shells

Troubleshooting

Common Issues

“Command not found: aitana”

# Reinstall the CLI
uv tool install ./aitana --force

# Ensure uv tools are in PATH
export PATH="$HOME/.local/bin:$PATH"  # Unix
# or add %USERPROFILE%\.local\bin to PATH on Windows

PID Detection Issues

The CLI automatically handles platform differences, but if you see “-“ for PIDs:

Windows: Ensure you have permissions to run netstat
macOS/Linux: Install lsof if missing: brew install lsof or apt-get install lsof

Port Already in Use

# Check what's using a port
aitana server status

# Stop all servers
aitana server stop

# Or kill specific process manually:
# Windows: taskkill /PID 1234 /F
# Unix: kill 1234

Firebase Emulator Issues

# Install Firebase CLI globally
npm install -g firebase-tools

# Initialize emulators (one-time setup)
firebase init
# Select: Firestore, Storage, Authentication

Performance Tips

Windows

Use Windows Terminal for better performance
Consider WSL2 for Unix-like development experience
Exclude node_modules and .venv from Windows Defender

macOS

Use native Terminal.app or iTerm2
Consider using nvm for Node.js version management

Linux

Most performant platform for development
Use your distribution’s native tools where possible

Testing

All testing commands work identically across platforms:

# Frontend tests
npm run test:run
npm run test:coverage

# Backend tests (from frontend root)
cd backend && uv run pytest tests/ -v

Building and Deployment

Docker builds work consistently across platforms:

# Build with quality checks
docker build -t aitana-frontend .

# Quick development build
docker build --build-arg SKIP_QUALITY_CHECKS=true -t aitana-frontend .

Getting Help

If you encounter platform-specific issues:

Check this guide for known solutions
Run aitana server status to diagnose server issues
Check logs: aitana server logs or aitana server analyze
Create an issue with your platform details and error messages

Platform Support Matrix

Feature	Windows	macOS	Linux	Notes
Server Management	✅	✅	✅	Full support
PID Detection	✅	✅	✅	Different methods used
Live Log Following	⚠️	✅	✅	Windows shows recent logs
Process Control	✅	✅	✅	Full support
Firebase Emulators	✅	✅	✅	Requires firebase-tools
Docker Build	✅	✅	✅	Full support
Development Workflow	✅	✅	✅	Identical experience

✅ Full Support

⚠️ Limited Support

❌ Not Supported