Skip to content

Installation

Jump to bottom
Siyâvash edited this page Dec 16, 2025 · 1 revision

Installation

This page provides detailed installation instructions for ExpoScholar.

System Requirements

Required Software

  • Operating System: GNU/Linux or macOS (Windows users can use WSL or a virtual machine)
  • Python: 3.11 or later
  • Flutter SDK: 3.38.3 or later
  • Java: 17 (for Android builds)
  • Android SDK: 36
  • Android NDK: 27.0.12077973
  • Git: Version control system
  • GNU Make: Build automation tool

Optional Software

  • QEMU: For running an Android virtual machine during development
  • Xcode: macOS users need Xcode for iOS builds
  • Texinfo tools: For building documentation (makeinfo or texi2any)

Getting the Source Code

Clone the repository:

git clone git@github.com:mkhellat/exposcholar.git
cd exposcholar

Verification

Before installing, verify your system meets the requirements:

python3 --version    # Should be 3.11 or later
flutter --version    # Should be 3.38.3 or later
java -version        # Should be 17
git --version
make --version

Installation Methods

Method 1: Automated Setup Script (Recommended)

The setup script provides a guided installation process:

cd exposcholar
./setup install

This command:

  • Validates system requirements
  • Installs Python dependencies
  • Sets up Flutter dependencies
  • Configures development environment
  • Creates necessary directories

Method 2: Component-Specific Installation

Install components individually:

./setup server    # Install server dependencies only
./setup mobile    # Install mobile dependencies only

Method 3: Using Makefile

For users familiar with GNU Make:

make setup        # Full installation
make setup-server # Server only
make setup-mobile # Mobile only

Method 4: Manual Installation

Server Setup

cd server
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
python manage.py migrate
python manage.py createsuperuser

Mobile Setup

cd mobile
flutter pub get
flutter doctor

Post-Installation

Verify Installation

Run the system check:

./setup check

This validates:

  • Python version and installation
  • Flutter SDK availability
  • Java version
  • Android SDK and NDK installation
  • QEMU and KVM support (if available)
  • Required system tools

Create Superuser (Server)

If you installed manually, create an admin user:

cd server
python manage.py createsuperuser

Android VM Setup (Optional)

For Android development and testing:

./setup start-mobile

This automatically creates and boots a QEMU-based Android virtual machine.

Troubleshooting Installation

Python Issues

Problem: Python version mismatch
Solution: Ensure Python 3.11+ is installed and active. Use python3 explicitly if both Python 2 and 3 are installed.

Problem: pip not found
Solution: Install pip: python3 -m ensurepip --upgrade

Flutter Issues

Problem: Flutter not found
Solution: Add Flutter to your PATH or use the full path to the Flutter binary.

Problem: Flutter doctor shows issues
Solution: Follow the recommendations from flutter doctor. Install missing components (Android SDK, Xcode, etc.).

Android SDK Issues

Problem: Android SDK not found
Solution: Set the ANDROID_HOME environment variable:

export ANDROID_HOME=/path/to/android/sdk

Problem: Android NDK not found
Solution: Install NDK 27.0.12077973 via Android Studio's SDK Manager or command-line sdkmanager tool.

Java Issues

Problem: Wrong Java version
Solution: Install OpenJDK 17:

# Debian/Ubuntu
sudo apt install openjdk-17-jdk

# macOS (with Homebrew)
brew install openjdk@17

Next Steps

After successful installation:

  1. Start Development Servers: See Development for details
  2. Run Tests: Verify installation with ./setup test
  3. Read Documentation: Build docs with ./setup docs
  4. Explore Codebase: See Architecture for system overview

Related Pages

Clone this wiki locally