Installation¶

Required software¶

You will need the following software installed in order to get started with setting up development environment:

System requirements¶

• Operating System: Windows (PowerShell), macOS, Linux
• Memory: 4GB+ RAM (for processing large datasets)
• Storage: 1GB+ free space (for project data and virtual environment)

Checking dependencies¶

If you're not sure which packages you already have installed on your system, the following commands can be used to figure what packages you already installed:

which <program_name_here (python|git)>

where.exe <program_name_here (python|git)> 

Setting up development environment¶

1. Clone repository¶

First clone the remote repository:

git clone https://github.com/civictechdc/cib-mango-tree.git  # creates cib-mango-tree folder in the current directory
cd cib-mango-tree  # navigate to the folder with cloned repository

2. Create virtual environment & install dependencies¶

Choose your preferred method for setting up your development environment:

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

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

pip install uv

# Create virtual environment
# this creates a hidden `.venv` folder
uv venv

# Activate virtual environment (macOS/Linux)
source .venv/bin/activate

# OR: if using Windows and PowerShell
# .venv\Scripts\activate

# Install development dependencies
uv sync --group dev

# Create virtual environment
python -m venv venv

# Activate virtual environment (macOS/Linux)
source venv/bin/activate
# OR: if using Windows and PowerShell
# venv\Scripts\activate

# Install dependencies
pip install -r requirements-dev.txt

python --version  # Should show Python 3.12.x

3. Set up pre-commit hooks¶

Pre-commit hooks (in pre-commit-config.yaml) automatically format your code with Black and isort before each commit.

In the root of the cloned repository install pre-commit:

# Install pre-commit hooks
pre-commit install

uv run pre-commit run --all-files

4. Verify installation¶

cibmt --noop

If all went well, you should see:

No-op flag detected. All runtime imports loaded successfully.

Starting the Application¶

Basic Usage¶

Once you have activated the environment and installed dependencies, run the application using cibmt command:

# Start the application
cibmt

Alternatively, use the long-version command:

cibmangotree

The application opens in a standalone window on macOS, or in your default browser on Windows.

Project storage¶

Application Data Directory¶

The application automatically creates data directories:

Database Initialization¶

No manual database setup required.

Executable Building¶

# Build standalone executable
pyinstaller pyinstaller.spec

Output (cibmangotree.app or cibmangotree.exe) will be in dist directory.

Build Requirements¶

• Included in requirements-dev.txt
• Used primarily for release distribution
• Not required for development

Troubleshooting¶

Common Dependency Issues¶

One common issue when installing the dependencies for python is the installation failing due to compatibility issues with the python package pyarrow. The compatibility issues are due to a version mismatch between pyarrow and python itself. To resolve this issue, you must be on version 3.12 for python. Refer to commands above to switch to the correct version.

Next Steps¶

Once you have everything installed and running without any problems, the next step is to check out the GitHub Contributor Workflow for contributing changes.