Skip to content

Latest commit

 

History

History
202 lines (136 loc) · 6.35 KB

DEV_SETUP_MAC.md

File metadata and controls

202 lines (136 loc) · 6.35 KB
Raw

Supplementary Guide for Developers Running CommCare HQ on MacOS

Prerequisites

  • You will need brew aka Homebrew for package management.

    Big Sur: see notes on running brew with Rosetta, aka ibrew below.

  • It is highly recommended that you install a python environment manager. Two options are:

    • pyenv (recommended) and pyenv-virtualenv

      brew install pyenv pyenv-virtualenv

      To create a new HQ virtual environment running Python 3.9.11, you can do the following:

      pyenv virtualenv 3.9.11 hq

      Then to enter the environment:

      pyenv activate hq

    • virtualenvwrapper

      Please note that if you use virtualenvwrapper, you also need to install pip

      To install pip:

      sudo python get-pip.py

      Then install virtualenvwrapper with pip:

      sudo python3 -m pip install virtualenvwrapper

  • Java (JDK 8)

    We recommend using sdkman as a Java environment manager. jenv is also an option, though more involved.

    • Example setup using sdkman:

      1. Install sdkman

      2. List available java versions to file one that matches Java (JDK 8)

        sdk list java

        Look for Java 8 in the list and install, eg:

        sdk install java 8.0.322-zulu

    • Example setup using jenv:

      1. Download and install Java SE Development Kit 8 from oracle.com downloads page. (requires signing in with an Oracle account to download).

      2. Install jenv

        brew install jenv

      3. Configure your shell (Bash folks use ~/.bashrc instead of ~/.zshrc below):

        echo 'export PATH="$HOME/.jenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(jenv init -)"' >> ~/.zshrc

      4. Add JDK 8 to jenv:

        jenv add $(/usr/libexec/java_home -v 1.8)

      5. Verify jenv config:

        jenv doctor

Prerequisites: Notes for MacOs 11.x (Big Sur)

  • It is recommended that you install Rosetta:

    softwareupdate --install-rosetta

    This allows you to install and run Brew services in x86 fashion. "Rosetta 2 is an emulator designed to bridge the transition between Intel and Apple processors. In short, it translates apps built for Intel so they will run on Apple Silicon." Link. While reading through this document, be careful to watch out for specific recommendations regarding your architecture.

  • If brew cannot successfully build packages on your system, you can run brew with Rosetta under the alias ibrew using the method below. However, please try installing the latest version of brew first, as this might also be fixed for MacOS 11.x

    arch -x86_64 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

    And let's call this Rosetta-enabled Homebrew ibrew for short by adding this to ~/.zshrc:

    alias ibrew="arch -x86_64 /usr/local/bin/brew"

    Note: 12.x Monterey seems to be handling brew just fine when following the official install guide.

Issues Installing requirements/requirements.txt

  • psycopg2 will complain

    As of Mac OS 11.x Big Sur, the solution for this is:

    brew install libpq --build-from-source
export LDFLAGS="-L/opt/homebrew/opt/libpq/lib"
pip install psycopg2-binary

Docker

Docker images that will not run on Mac OS (Intel or M1):

Docker images that will not run on Mac OS (as of 11.x Big Sur and above):

  • elasticsearch2
  • elasticsearch5

M1 (OS 11.x and above) Recommended Docker Up Command

./scripts/docker up -d postgres couch redis zookeeper kafka minio

Note: kafka will be very cranky on start up. You might have to restart it if you see kafka errors.

./scripts/docker restart kafka

Installing and running Elasticsearch 2.4.6 outside of Docker

First, ensure that you have Java 8 running. java -version should output something like openjdk version "1.8.0_322". Use sdkman or jenv to manage your local java versions.

Download the tar file for elasticsearch 2.4.6

Un-tar and put the folder somewhere you can find it. Take note of tha path (pwd) and add the following to your ~/.zshrc:

export PATH="/path/to/elasticsearch-2.4.6/bin:$PATH"

NOTE: Make sure that /path/to is replaced with the actual path!

After this you can open a new terminal window and run elasticsearch with elasticsearch.

Fixing ImportError with libmagic

If you are sure that the following brew install libmagic ran successfully, but you are still seeing the error below, then this section is for you!

ImportError: failed to find libmagic.  Check your installation

As of Mac OS 12.x, brew now installs itself in /opt/homebrew/, and it looks like our version of the python package that requires libmagic has not caught up.

To fix:

cd /usr/local/lib/
ln -s /opt/homebrew/Cellar/libmagic/5.41/lib/libmagic.dylib libmagic.dylib

Refreshing data in elasticsearch manually (alternative to run_ptop)

FYI, be sure to check out the FAQ on elasticsearch.

To refresh specific indices in elasticsearch you can do the following...

First make sure everything is up-to-date

./manage.py ptop_preindex --reset
./manage.py ptop_es_manage --flip_all_aliases

./manage.py preindex_everything

Force a re-index of forms and cases:

./manage.py ptop_reindexer_v2 sql-case --reset
./manage.py ptop_reindexer_v2 sql-form --reset

For other indices see ./manage.py ptop_reindexer_v2 --help