### Install and Start Kafka on macOS

Source: https://github.com/dimagi/commcare-hq/blob/master/corehq/apps/change_feed/README.md

Use Homebrew to install Kafka and start the required Zookeeper and Kafka services.

```bash
brew install kafka
brew services start zookeeper
brew services start kafka
```

--------------------------------

### Start Nginx Server

Source: https://github.com/dimagi/commcare-hq/blob/master/corehq/apps/builds/README.rst

Start the Nginx web server after installing and configuring it. This command may vary depending on your operating system.

```bash
sudo nginx
```

--------------------------------

### Install sdkman and initialize

Source: https://github.com/dimagi/commcare-hq/blob/master/DEV_SETUP_MAC.md

Installs sdkman, a tool for managing SDKs, and initializes it in the current Zsh session. This is part of the recommended Java setup.

```sh
# Run the installer with Zsh-compatible pattern matching
curl -s "https://get.sdkman.io" | zsh -o NO_NOMATCH

# Initialize SDKMAN! in your current session
source "$HOME/.sdkman/bin/sdkman-init.sh"
```

--------------------------------

### Install coverage.py

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/test_coverage.rst

Install the coverage.py library using uv.

```bash
$ uv pip install coverage
```

--------------------------------

### Configure Placeholders and Help Text

Source: https://github.com/dimagi/commcare-hq/blob/master/corehq/apps/styleguide/templates/styleguide/bootstrap5/organisms/forms.html

Examples for adding placeholders and help text to form fields to guide user input.

```html
{% include 'styleguide/bootstrap5/code_example.html' with content=examples.placeholder_help_text %}
```

```html
{% include 'styleguide/bootstrap5/form_example.html' with content=examples.crispy_placeholder_help_text %}
```

--------------------------------

### Sample API Request

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/api/download-report-data.rst

An example of a GET request URL with offset, limit, and filter parameters applied.

```text
https://www.commcarehq.org/a/[PROJECT]/api/configurablereportdata/v1/9aab0eeb88555a7b4568676883e7379a/?offset=20&limit=10&state=vermont&gender=male
```

--------------------------------

### Install PostgreSQL client and binaries

Source: https://github.com/dimagi/commcare-hq/blob/master/DEV_SETUP.md

Install PostgreSQL client tools or binaries for database interaction.

```sh
sudo apt install postgresql-client
```

```sh
brew install postgresql
```

--------------------------------

### Sample Fixture Data Request and Response

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/api/fixture.rst

Example of a GET request for a specific fixture item and the corresponding JSON response structure.

```text
https://www.commcarehq.org/a/demo/api/fixture/v1/1J9NF7B4FTH73435PYJJSL5SJ/
```

```json
{
    "fields": {
        "name": "Boston",
        "population": 617594,
        "state": "Massachusetts"
    },
    "fixture_type": "city",
    "resource_uri": "",
    "id": "1J9NF7B4FTH73435PYJJSL5SJ"
}
```

--------------------------------

### Start HAPI FHIR Docker Container

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/fhir/fhir_repeater.rst

Use this command to start a local HAPI FHIR Docker container for testing. Ensure Docker is installed and running.

```bash
$ docker run -it -p 8425:8080 smartonfhir/hapi-5:r4-synthea
```

--------------------------------

### Install Git

Source: https://github.com/dimagi/commcare-hq/blob/master/DEV_SETUP.md

Install the Git version control system on Ubuntu-based Linux systems.

```sh
sudo apt install git
```

--------------------------------

### Handle architecture-specific installation issues

Source: https://github.com/dimagi/commcare-hq/blob/master/DEV_SETUP.md

Workarounds for ARM64 architecture and compiler errors during dependency installation.

```sh
CFLAGS="-Wno-error=implicit-function-declaration" uv sync --compile-bytecode
```

```sh
CC=gcc LDFLAGS="-L`python -c'import sys; print(sys.base_prefix)'`/lib" uv sync --compile-bytecode
```

--------------------------------

### Install Java JDK 17

Source: https://github.com/dimagi/commcare-hq/blob/master/DEV_SETUP.md

Install the OpenJDK 17 runtime environment on Linux.

```sh
sudo apt install openjdk-17-jre
```

--------------------------------

### Install Podman and Configure Environment Variables

Source: https://github.com/dimagi/commcare-hq/blob/master/docker/README.rst

Installs the podman package and sets the necessary environment variables for socket communication.

```bash
sudo apt install podman podman-docker

echo 'export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock' >> ~/.bashrc
echo 'export DOCKER_SOCK=$XDG_RUNTIME_DIR/podman/podman.sock' >> ~/.bashrc
```

--------------------------------

### Install and Configure Docker on Linux

Source: https://github.com/dimagi/commcare-hq/blob/master/DEV_SETUP.md

Commands to install Docker, ensure the service is running, and add the current user to the docker group.

```sh
# install docker
sudo apt install docker.io

# ensure docker is running
systemctl is-active docker || sudo systemctl start docker
# add your user to the `docker` group
sudo adduser $USER docker
# log in as yourself again to activate membership of the "docker" group
su - $USER

# re-activate your virtualenv (presuming uv)
source .venv/bin/activate
```

--------------------------------

### Install Nginx

Source: https://github.com/dimagi/commcare-hq/blob/master/corehq/apps/builds/README.rst

Install the Nginx web server using a package manager. This is required for the advanced syncing method.

```bash
sudo apt-get install nginx
```

```bash
brew install nginx
```

--------------------------------

### Start CommCare HQ with runserver_plus

Source: https://github.com/dimagi/commcare-hq/blob/master/DEV_SETUP.md

Use runserver_plus to start the development server as required for Formplayer functionality.

```sh
./manage.py runserver_plus localhost:8000
```

--------------------------------

### List Extension Points Command

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/extensions.rst

Run this management command to list existing extension points and their implementations. No setup is required beyond having CommCare HQ installed.

```bash
python manage.py list_extension_points
```

--------------------------------

### Include HTML Form Example

Source: https://github.com/dimagi/commcare-hq/blob/master/corehq/apps/styleguide/templates/styleguide/bootstrap3/_includes/organisms/forms.html

Uses the styleguide include tag to render a simple HTML form example.

```django
{% include 'styleguide/bootstrap3/example_html.html' with slug='html_form' title='Simple HTML form' content=examples.html_form %}
```

--------------------------------

### Start Docker Services

Source: https://github.com/dimagi/commcare-hq/blob/master/docker/README.rst

Build and start specified Docker services in the background. Omit '-d' to run in the foreground. Use './scripts/docker ps' to check status.

```bash
$ scripts/docker up -d postgres couch redis elasticsearch6 zookeeper kafka minio
```

--------------------------------

### Build and Install pghashlib

Source: https://github.com/dimagi/commcare-hq/blob/master/corehq/sql_proxy_accessors/README.md

Builds and installs the pghashlib PostgreSQL extension from source. Requires setting the PG_CONFIG environment variable to point to your PostgreSQL installation's pg_config executable.

```bash
  $ PG_CONFIG=/usr/lib/postgresql/9.X/bin/pg_config make
  $ sudo PG_CONFIG=/usr/lib/postgresql/9.X/bin/pg_config make install
```

--------------------------------

### Info Button Row Example

Source: https://github.com/dimagi/commcare-hq/blob/master/corehq/apps/styleguide/templates/styleguide/bootstrap3/_includes/molecules/buttons.html

Example of an info button, used for secondary download actions or as a primary action on dark backgrounds.

```html
{% include 'styleguide/bootstrap3/_includes/molecules/buttons/button_row.html' with css_class='info' icon='fa fa-cloud-download' description='Secondary doownload action  
Primary action for dark backgrounds' %}
```

--------------------------------

### Install Docker Compose Plugin

Source: https://github.com/dimagi/commcare-hq/blob/master/DEV_SETUP.md

Command to install the docker-compose plugin on Linux systems.

```sh
sudo apt install docker-compose-plugin
```

--------------------------------

### Install Node.js on Ubuntu

Source: https://github.com/dimagi/commcare-hq/blob/master/DEV_SETUP.md

Commands to install Node.js v24 on Ubuntu 22.04 LTS.

```bash
curl -sL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
```

--------------------------------

### Install uv dependency manager

Source: https://github.com/dimagi/commcare-hq/blob/master/DEV_SETUP.md

Install the uv Python package manager using system-specific package managers.

```sh
sudo snap install astral-uv
```

```sh
brew install uv
```

--------------------------------

### Install PL/Proxy Extension

Source: https://github.com/dimagi/commcare-hq/blob/master/corehq/sql_proxy_accessors/README.md

Installs the PL/Proxy PostgreSQL extension using apt-get. Ensure you use the correct PostgreSQL version (e.g., 9.X).

```bash
  $ sudo apt-get install postgresql-9.X-plproxy
```

--------------------------------

### Install Grunt globally

Source: https://github.com/dimagi/commcare-hq/blob/master/DEV_SETUP.md

Install grunt and grunt-cli globally using yarn to enable command-line usage.

```sh
yarn global add grunt
yarn global add grunt-cli
```

--------------------------------

### Install and Run ESLint Locally

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/js-guide/linting.rst

Install ESLint globally via npm and run it on a specific file to check for code errors and stylistic issues.

```shell
# Install it through npm:
$ npm install -g eslint

# Try it out locally if you like
$ eslint path/to/file.js
```

--------------------------------

### Build Documentation Locally

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/documenting.rst

Commands to set up the documentation environment and generate HTML files for local testing.

```sh
$ cd commcare-hq/
$ uv sync --group=docs --inexact
$ cd docs/
$ make html
```

--------------------------------

### Create Test Application

Source: https://github.com/dimagi/commcare-hq/blob/master/corehq/apps/data_cleaning/README.md

Initializes the 'Plant Care' application within the specified domain.

```bash
./manage.py dc_create_test_app <domain>
```

--------------------------------

### CommCare HQ Dependency Installation Script

Source: https://github.com/dimagi/commcare-hq/wiki/Installing-Dependencies-on-Ubuntu-12.04

This bash script automates the setup of the CommCare HQ environment. Ensure required tarballs and installers are present in the script directory before execution.

```bash
DBNAME="foodb"

# This script installs dependencies for CommCare HQ on Ubuntu 12.04 (Java,
# Jython, couchdb, couchdb-lucene, less, uglifyjs, and various python packages)
# and sets couchdb and couchdb-lucene up to automatically run on startup.  It
# also creates postgres (user 'django', pass 'django') and couchdb databases
# named according to $DBNAME as specified above. 

# Before running, you must download the following files to the script's
# directory: 
#  - the JDK 7 tar.gz from
#    http://www.oracle.com/technetwork/java/javase/downloads/index.html and
#    save it as jdk.tar.gz
# 
#  - jython_installer-2.5.2.jar from http://jython.org/downloads.html
#
#  - apache-couchdb-1.2.0.tar.gz from http://couchdb.apache.org/#download

if [[ ! $(sudo grep -r "chris-lea/node\.js" /etc/apt/) ]]; then
    sudo add-apt-repository -y ppa:chris-lea/node.js
    sudo apt-get update
fi

if [ ! -f couchdb-lucene-0.8.0-dist.zip ]; then
    wget https://github.com/downloads/rnewson/couchdb-lucene/couchdb-lucene-0.8.0-dist.zip -O couchdb-lucene-0.8.0-dist.zip
fi

## Install dependencies ##

sudo apt-get install nodejs npm
sudo npm install less uglify-js -g

sudo apt-get install -y curl python-pip python-dev libevent-1.4-2 libevent-dev python-setuptools build-essential
sudo apt-get install -y postgresql memcached
sudo apt-get build-dep -y python-psycopg2 python-lxml

sudo pip install --upgrade pip
sudo pip install virtualenv virtualenvwrapper

if [[ ! $(grep virtualenvwrapper ~/.bashrc) ]]; then
    echo "source /usr/local/bin/virtualenvwrapper.sh" >> ~/.bashrc
    source ~/.bashrc
fi

## Install Java ##

if [ ! -d /usr/lib/jvm/jdk1.7.0 ]; then
    tar -xvzf jdk.tar.gz
    sudo mkdir /usr/lib/jvm
    sudo rm -r /usr/lib/jvm/jdk1.7.0/
    sudo mv ./jdk1.7.0* /usr/lib/jvm/jdk1.7.0

    sudo update-alternatives --install "/usr/bin/java" "java" "/usr/lib/jvm/jdk1.7.0/bin/java" 1
    sudo update-alternatives --install "/usr/bin/javac" "javac" "/usr/lib/jvm/jdk1.7.0/bin/javac" 1
    sudo update-alternatives --install "/usr/bin/javaws" "javaws" "/usr/lib/jvm/jdk1.7.0/bin/javaws" 1

    sudo update-alternatives --config java
fi

## Install Jython ##

if [ ! -d /usr/local/lib/jython ]; then
    # Set /usr/local/lib/jython as the target directory
    sudo java -jar jython_installer-2.5.2.jar

    wget http://peak.telecommunity.com/dist/ez_setup.py

    sudo jython ez_setup.py

    /usr/local/lib/jython/bin/easy_install django
    /usr/local/lib/jython/bin/easy_install django-jython
fi

## Install couchdb ##
# from http://onabai.wordpress.com/2012/05/10/installing-couchdb-1-2-in-ubuntu-12-04/

if [ ! -f /etc/init.d/couchdb ]; then
    sudo apt-get install g++
    sudo apt-get install erlang-base erlang-dev erlang-eunit erlang-nox
    sudo apt-get install libmozjs185-dev libicu-dev libcurl4-gnutls-dev libtool

    tar xvzf apache-couchdb-1.2.0.tar.gz
    cd apache-couchdb-1.2.0

    ./configure
    make 
    sudo make install

    cd .. && rm -r apache-couchdb-1.2.0

    sudo adduser --disabled-login --disabled-password --no-create-home couchdb
    sudo chown -R couchdb:couchdb /usr/local/var/log/couchdb
    sudo chown -R couchdb:couchdb /usr/local/var/lib/couchdb
    sudo chown -R couchdb:couchdb /usr/local/var/run/couchdb

    sudo ln -s /usr/local/etc/init.d/couchdb /etc/init.d

    sudo update-rc.d couchdb defaults
fi

## Install couchdb-lucene ##

if [ ! -f /etc/init.d/couchdb-lucene ]; then
    unzip couchdb-lucene-0.8.0-dist.zip
    sudo cp couchdb-lucene-0.8.0 /usr/local
    rm -r couchdb-lucene-0.8.0
    sudo cp /usr/local/couchdb-lucene-0.8.0/tools/etc/init.d/couchdb-lucene/couchdb-lucene /etc/init.d/

    sudo sed '/\[httpd_global_handlers\]/ a\_fti = {couch_httpd_proxy, handle_proxy_req, <<"http://127.0.0.1:5985">>}' /usr/local/etc/couchdb/local.ini

    sudo update-rc.d couchdb-lucene defaults
fi

## Configure database ##

sudo -u postgres createdb $DBNAME
echo "CREATE USER django WITH PASSWORD 'django'; ALTER USER django CREATEDB;" | sudo -u postgres psql $DBNAME

curl -X PUT "http://localhost:5984/$DBNAME"
```

--------------------------------

### Get Month Start Date

Source: https://github.com/dimagi/commcare-hq/blob/master/corehq/apps/userreports/README.rst

The `month_start_date` function returns the first day of the month for a given date.

```commcare
2015-01-20
->
2015-01-01
```

--------------------------------

### Example Global Mapping Output

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/messaging/sms_backends.rst

Sample output showing the mapping of phone prefixes to specific SQLMobileBackend instances.

```python
('27', <SQLMobileBackend: Global Backend 'GRAPEVINE-ZA'>),
('999', <SQLMobileBackend: Global Backend 'MOBILE_BACKEND_TEST'>),
('1', <SQLMobileBackend: Global Backend 'MOBILE_BACKEND_TWILIO'>),
('258', <SQLMobileBackend: Global Backend 'MOBILE_BACKEND_MOZ'>),
('266', <SQLMobileBackend: Global Backend 'GRAPEVINE-ZA'>),
('265', <SQLMobileBackend: Global Backend 'MOBILE_BACKEND_TWILIO'>),
('268', <SQLMobileBackend: Global Backend 'GRAPEVINE-ZA'>),
('256', <SQLMobileBackend: Global Backend 'MOBILE_BACKEND_YO'>),
('*', <SQLMobileBackend: Global Backend 'MOBILE_BACKEND_MACH'>)
```

--------------------------------

### GET /

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/api/cases-v2.rst

Query a list of cases within the specified domain.

```APIDOC
## GET /a/<domain>/api/case/v2/

### Description
Query a list of cases. Supports filtering and querying by project-specific case properties.

### Method
GET

### Endpoint
/a/<domain>/api/case/v2/
```

--------------------------------

### Include specific fields in case response

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/api/cases-v2.rst

Example request and response for filtering cases by type and restricting the returned fields.

```text
GET /a/<domain>/api/case/v2/?case_type=patient&fields=case_id&fields.properties=edd,age
```

```json
{
    "matching_records": 1,
    "cases": [
        {
            "case_id": "abc123",
            "properties": {
                "edd": "2013-12-09",
                "age": "22"
            }
        }
    ]
}
```

--------------------------------

### Connect to PostgreSQL

Source: https://github.com/dimagi/commcare-hq/blob/master/DEV_SETUP.md

Connect to the PostgreSQL instance to prepare for manual database creation.

```sh
psql -h localhost -p 5432 -U commcarehq
```

--------------------------------

### Python Code Block with Pygments

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/documenting.rst

Example of a Python code block that requires 'pip install pygments' for syntax highlighting in reStructuredText.

```python
# You need to "pip install pygments" to make this work.

for i in range(10):
    like()
```

--------------------------------

### Case Fetch Response Format

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/api/cases-v2.rst

Example JSON response structure for a case fetch request, showing matching and missing records.

```json
{
  "matching_records": 2,
  "missing_records": 2,
  "cases": [
    {"case_id": "30ad22bd-f828-4e3f-8287-a67a180cff4f", "properties": {"dob": "1980-08-20"}},
    {"case_id": "d5e5962a-c5f1-483c-a58a-590167d594a9", "error": "not found"},
    {"external_id": "id1", "error": "not found"},
    {"case_id": "5262c03f-f483-4b36-9a08-cdaf89791e65", "external_id": "id2"},
  ]
}
```

--------------------------------

### Case API Response Format

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/api/cases-v2.rst

Example of the JSON structure returned by the Case API, including case properties and index information.

```json
{
  "matching_records": 1,
  "cases": [
    {
      "domain": "queens-gambit",
      "case_id": "1",
      "case_type": "assignment",
      "case_name": "assignment",
      "external_id": "1",
      "owner_id": "1",
      "date_opened": "2021-01-18T18:24:23.480723Z",
      "last_modified": "2021-01-18T18:24:23.480723Z",
      "server_last_modified": "2021-01-18T19:52:37.516558Z",
      "indexed_on": "2021-01-18T19:55:13.707193Z",
      "closed": false,
      "date_closed": null,
      "properties": {
        "assignment_type": "primary"
      },
      "indices": {
        "parent": {
          "case_id": "1",
          "case_type": "contact",
          "relationship": "extension"
        }
      }
    }
  ]
}
```

--------------------------------

### GET /a/<domain>/api/case/v2/<case_ids>

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/api/cases-v2.rst

Retrieves multiple cases in bulk using a comma-separated list of IDs.

```APIDOC
## GET /a/<domain>/api/case/v2/<case_ids>

### Description
Fetches multiple cases by providing a comma-separated list of IDs. Limited by maximum URL length (approx 100 cases).

### Method
GET

### Endpoint
/a/<domain>/api/case/v2/<case_ids>

### Parameters
#### Path Parameters
- **case_ids** (string) - Required - Comma-separated list of case IDs
```

--------------------------------

### GET /a/<domain>/api/case/v2/<case_id>

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/api/cases-v2.rst

Retrieves an individual case by its ID.

```APIDOC
## GET /a/<domain>/api/case/v2/<case_id>

### Description
Retrieves a single case serialized by its ID.

### Method
GET

### Endpoint
/a/<domain>/api/case/v2/<case_id>

### Parameters
#### Path Parameters
- **domain** (string) - Required - The domain name
- **case_id** (string) - Required - The unique case identifier
```

--------------------------------

### GET /a/<domain>/api/case/v2/ext/<ext_id>/

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/api/cases-v2.rst

Retrieves an individual case by its external ID.

```APIDOC
## GET /a/<domain>/api/case/v2/ext/<ext_id>/

### Description
Retrieves a single case by its external ID. If the ID is not unique, only one case will be returned.

### Method
GET

### Endpoint
/a/<domain>/api/case/v2/ext/<ext_id>/

### Parameters
#### Path Parameters
- **domain** (string) - Required - The domain name
- **ext_id** (string) - Required - The external case identifier
```

--------------------------------

### Sample API Usage

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/api/list-webusers.rst

Example URL for listing web users in a demo domain.

```text
https://www.commcarehq.org/a/demo/api/web-user/v1/
```

--------------------------------

### Previous Breadcrumb Structure

Source: https://github.com/dimagi/commcare-hq/blob/master/corehq/apps/hqwebapp/utils/bootstrap/changes_guide/css-breadcrumb.md

Illustrates the HTML structure of the breadcrumb component before the recent update. No specific setup is required to view this example.

```html
<ol class="breadcrumb">
    <li><a href="#">Home</a></li>
    <li><a href="#">Library</a></li>
    <li class="active">Data</li>
</ol>
```

--------------------------------

### GET /<case_id>

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/api/cases-v2.rst

Retrieve an individual case by its unique ID.

```APIDOC
## GET /a/<domain>/api/case/v2/<case_id>

### Description
Get an individual case by its unique case ID.

### Method
GET

### Endpoint
/a/<domain>/api/case/v2/<case_id>

### Parameters
#### Path Parameters
- **case_id** (string) - Required - The unique identifier of the case.
```

--------------------------------

### Python Code Block Example

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/documenting.rst

Demonstrates a Python function and loop within a reStructuredText code block. Ensure Pygments is installed for syntax highlighting.

```python
def like():
    print("I like Ice Cream")

for i in range(10):
    like()
```

--------------------------------

### GET /a/<domain>/api/case/v2/

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/api/cases-v2.rst

Retrieves a list of cases for a specific domain, supporting filtering by various case attributes and date ranges, as well as field selection.

```APIDOC
## GET /a/<domain>/api/case/v2/

### Description
Returns a list of cases for the specified domain. Results can be filtered using various query parameters and the response fields can be customized using fields or exclude parameters.

### Method
GET

### Endpoint
/a/<domain>/api/case/v2/

### Parameters
#### Path Parameters
- **domain** (string) - Required - The domain name.

#### Query Parameters
- **limit** (integer) - Optional - Defaults to 20, maximum 5000.
- **external_id** (string) - Optional - Filter by external ID.
- **case_type** (string) - Optional - Filter by case type.
- **owner_id** (string) - Optional - Filter by owner ID.
- **case_name** (string) - Optional - Filter by case name.
- **closed** (boolean) - Optional - Filter by closed status.
- **indices.<name>** (string) - Optional - Filter by parent/host case ID.
- **last_modified.<op>** (date/datetime) - Optional - Filter by last modified date (gt, gte, lt, lte).
- **server_last_modified.<op>** (date/datetime) - Optional - Filter by server last modified date (gt, gte, lt, lte).
- **indexed_on.<op>** (date/datetime) - Optional - Filter by indexed date (gt, gte, lt, lte).
- **date_opened.<op>** (date/datetime) - Optional - Filter by date opened (gt, gte, lt, lte).
- **date_closed.<op>** (date/datetime) - Optional - Filter by date closed (gt, gte, lt, lte).
- **properties.<property>** (string) - Optional - Filter by exact match of user-defined case properties.
- **fields** (string) - Optional - Comma-separated list of fields to include.
- **exclude** (string) - Optional - Comma-separated list of fields to exclude.

### Response
#### Success Response (200)
- **matching_records** (integer) - Number of matching records.
- **cases** (array) - List of case objects.

#### Response Example
{
    "matching_records": 1,
    "cases": [
        {
            "case_id": "abc123",
            "properties": {
                "edd": "2013-12-09",
                "age": "22"
            }
        }
    ]
}
```

--------------------------------

### Initialize Formplayer database

Source: https://github.com/dimagi/commcare-hq/blob/master/DEV_SETUP.md

Create the formplayer database using the commcarehq user credentials.

```sh
createdb formplayer -U commcarehq -h localhost
```

--------------------------------

### Decorating View Methods with hq_hx_action

Source: https://github.com/dimagi/commcare-hq/blob/master/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/ko_migration/prompt_start.md

Example of decorating a view method to be callable via the HqHtmxActionMixin. The decorator specifies the HTTP method (e.g., 'get') that the action method will respond to.

```python
@hq_hx_action("get")
def my_hx_get_action(self, request):
    # Handle GET request for this HTMX action
    pass

```

--------------------------------

### Calling HTMX Actions from Templates

Source: https://github.com/dimagi/commcare-hq/blob/master/corehq/apps/styleguide/templates/styleguide/bootstrap5/examples/ko_migration/prompt_start.md

How to trigger a custom HTMX action from an HTML template using `hq-hx-action` in conjunction with standard HTMX attributes like `hx-get` or `hx-post`. This example shows triggering a 'get' action named 'my_hx_get_action'.

```html
<button hx-get="/some/url/" hx-trigger="click" hq-hx-action="my_hx_get_action">Click Me</button>

```

--------------------------------

### Create Data Source from Repeat Element

Source: https://github.com/dimagi/commcare-hq/blob/master/corehq/apps/userreports/README.rst

Configure a data source to save multiple rows per case/form by specifying a base item expression that describes how to get repeat data. This example creates a table from a repeat element called 'time_logs'.

```json
{
       "domain": "user-reports",
       "doc_type": "DataSourceConfiguration",
       "referenced_doc_type": "XFormInstance",
       "table_id": "sample-repeat",
       "display_name": "Time Logged",
       "base_item_expression": {
           "type": "property_path",
           "property_path": ["form", "time_logs"]
       },
       "configured_filter": {
       },
       "configured_indicators": [
           {
               "type": "expression",
               "expression": {
                   "type": "property_name",
                   "property_name": "start_time"
               },
               "column_id": "start_time",
               "datatype": "datetime",
               "display_name": "start time"
           },
           {
               "type": "expression",
               "expression": {
                   "type": "property_name",
                   "property_name": "end_time"
               },
               "column_id": "end_time",
               "datatype": "datetime",
               "display_name": "end time"
           },
           {
               "type": "expression",
               "expression": {
                   "type": "property_name",
                   "property_name": "person"
               },
               "column_id": "person",
               "datatype": "string",
               "display_name": "person"
           },
           {
               "type": "expression",
               "expression": {
                   "type": "root_doc",
                   "expression": {
                       "type": "property_name",
                       "property_name": "name"
                   }
               },
               "column_id": "name",
               "datatype": "string",
               "display_name": "name of ticket"
           }
       ]
   }
```

--------------------------------

### Install Puppeteer browser

Source: https://github.com/dimagi/commcare-hq/blob/master/DEV_SETUP.md

Manually install the Chrome browser required for tests, as repo-wide settings prevent automatic installation.

```sh
npx puppeteer browsers install chrome
```

--------------------------------

### Install Phonetic Analysis Plugin

Source: https://github.com/dimagi/commcare-hq/blob/master/DEV_SETUP_MAC.md

Installs the analysis-phonetic plugin for Elasticsearch.

```sh
elasticsearch-plugin install analysis-phonetic
```

--------------------------------

### Cursor Pagination Example

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/api/messaging-events.rst

Demonstrates the flow of fetching paginated results using the meta.next URL.

```text
# First request
https://www.commcarehq.org/a/[domain]/api/messaging-event/v1/?content_type=sms

{"objects": [{}, {}, {}...], "meta": {"limit": 20, "next": "https://www.commcarehq.org/a/[domain]/api/messaging-event/v1/?cursor=XYZ"}}

# Request for next page
https://www.commcarehq.org/a/[domain]/api/messaging-event/v1/?cursor=XYZ

{"objects": [{}, {}, {}...], "meta": {"limit": 20, "next": "https://www.commcarehq.org/a/[domain]/api/messaging-event/v1/?cursor=ABC"}}

# Request for next page
https://www.commcarehq.org/a/[domain]/api/messaging-event/v1/?cursor=ABC

{"objects": [{}, {}, {}...], "meta": {"limit": 20, "next": null}}

# "meta.next" is null so there is no more data.
```

--------------------------------

### Install ESLint Dependency

Source: https://github.com/dimagi/commcare-hq/blob/master/eslint/README.md

Install ESLint as a development dependency using Yarn.

```bash
yarn add eslint --save-dev
```

--------------------------------

### Initialize Kafka Topics

Source: https://github.com/dimagi/commcare-hq/blob/master/corehq/apps/change_feed/README.md

Run the management command to initialize Kafka topics after the service is running.

```bash
./manage.py create_kafka_topics
```

--------------------------------

### Verify Plugin Installation

Source: https://github.com/dimagi/commcare-hq/blob/master/DEV_SETUP_MAC.md

Queries the Elasticsearch API to list installed plugins.

```sh
curl "localhost:9200/_cat/plugins?s=component&h=component,version"
> analysis-phonetic 6.8.23
```

--------------------------------

### Define Application Menus in XML

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/apps/advanced_app_features.rst

Example XML structure for defining application menus and their associated commands.

```xml
<menu id="m0">
        <text>
            <locale id="modules.m0"/>
        </text>
        <command id="m0-f0"/>
    </menu>
    <menu root="m0" id="m1">
        <text>
            <locale id="modules.m1"/>
        </text>
        <command id="m1-f0"/>
    </menu>
    <menu root="m2" id="m1.m2">                                                                                                     <text>
            <locale id="modules.m1"/>
        </text>                                                                                                                     <command id="m1-f0"/>
    </menu>
    <menu id="m2">                                                                                                                  <text>
            <locale id="modules.m2"/>
        </text>                                                                                                                     <command id="m2-f0"/>
    </menu>
```

--------------------------------

### Install ESLint Dimagi Plugin

Source: https://github.com/dimagi/commcare-hq/blob/master/eslint/README.md

Install the eslint-plugin-eslint-dimagi as a development dependency using Yarn.

```bash
yarn add eslint-plugin-eslint-dimagi --save-dev
```

--------------------------------

### Start Django Development Server

Source: https://github.com/dimagi/commcare-hq/blob/master/DEV_SETUP.md

Launch the Django server to access CommCare HQ in a browser at localhost:8000.

```sh
./manage.py runserver localhost:8000
```

--------------------------------

### Populate Databases and Configure Proxy

Source: https://github.com/dimagi/commcare-hq/blob/master/DEV_SETUP.md

Commands to sync CouchDB views, create Kafka topics, and run database migrations.

```sh
./manage.py sync_couch_views
./manage.py create_kafka_topics
env CCHQ_IS_FRESH_INSTALL=1 ./manage.py migrate --noinput
```

```sh
env CCHQ_IS_FRESH_INSTALL=1 ./manage.py migrate_multi --noinput
./manage.py configure_pl_proxy_cluster --create_only
```

--------------------------------

### Install Grunt Globally

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/js-guide/testing.rst

Required global installation of Grunt and its CLI for running test tasks.

```bash
$ npm install -g grunt
$ npm install -g grunt-cli
```

--------------------------------

### Sample API Request

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/api/list-mobile-workers.rst

Example URL for requesting a list of users in XML format with a limit of 5.

```text
https://www.commcarehq.org/a/demo/api/user/v1/?format=xml&limit=5
```

--------------------------------

### Install Dart Sass globally

Source: https://github.com/dimagi/commcare-hq/blob/master/DEV_SETUP.md

Install the Dart Sass compiler globally using npm.

```bash
npm install -g sass
```

--------------------------------

### Example cURL Request

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/api/ota-api-restore.rst

Demonstrates how to programmatically request the restore data using HTTP basic authentication.

```bash
curl --basic -u jason@DEMO_DOMAIN.commcarehq.org:1988 \
https://www.commcarehq.org/a/DEMO_DOMAIN/phone/restore/?version=2.0
```

--------------------------------

### Configure local settings and shared directory

Source: https://github.com/dimagi/commcare-hq/blob/master/DEV_SETUP.md

Initializes local configuration and the required shared files directory.

```sh
cp localsettings.example.py localsettings.py
```

```sh
mkdir sharedfiles
```

--------------------------------

### Example Success Response XML

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/api/form-submission.rst

An example of a successful form submission response from the OpenRosa API.

```xml
<OpenRosaResponse xmlns="http://openrosa.org/http/response">
        <message nature="submit_success">   √   </message>
    </OpenRosaResponse>
```

--------------------------------

### Create Databases in PostgreSQL

Source: https://github.com/dimagi/commcare-hq/blob/master/DEV_SETUP.md

SQL commands to create the necessary proxy and partitioned databases for the application.

```sql
commcarehq=# CREATE DATABASE commcarehq_proxy;
CREATE DATABASE
commcarehq=# CREATE DATABASE commcarehq_p1;
CREATE DATABASE
commcarehq=# CREATE DATABASE commcarehq_p2;
CREATE DATABASE
commcarehq=# \q
```

```sql
commcarehq=# CREATE DATABASE formplayer;
CREATE DATABASE
```

--------------------------------

### Primary Button Row Example

Source: https://github.com/dimagi/commcare-hq/blob/master/corehq/apps/styleguide/templates/styleguide/bootstrap3/_includes/molecules/buttons.html

Example of a primary button, representing the most important action on a page.

```html
{% include 'styleguide/bootstrap3/_includes/molecules/buttons/button_row.html' with css_class='primary' icon='' description='The most important action on a page' %}
```

--------------------------------

### Initialize NotificationsService Unit Test Suite

Source: https://github.com/dimagi/commcare-hq/blob/master/corehq/apps/hqwebapp/tests/data/bootstrap5_diffs/javascript/notifications/spec/NotificationsService.spec.mo.js.diff.txt

Sets up the test environment with necessary dependencies including jQuery, Sinon, and the NotificationsService module.

```javascript
import $ from "jquery";
import sinon from "sinon";
import notifications from "notifications/js/bootstrap5/notifications_service";

describe('NotificationsService Unit Tests', function () {
    var fakeRMIUrl = '/fake/rmi',

```

--------------------------------

### Install CommCare HQ Dependencies

Source: https://github.com/dimagi/commcare-hq/wiki/Getting-Started-with-CommCareHQ-1.0

Install the required Python packages for CommCare HQ using pip.

```bash
pip install -r requirements.txt
```

--------------------------------

### Run CommCare HQ Development Server

Source: https://github.com/dimagi/commcare-hq/blob/master/docker/README.rst

Builds required images, runs all service containers, migrates the DB, syncs Couch views, bootstraps a superuser and domain if needed, and starts the Django dev server. For Mac users, replace 'localhost' with the output of 'docker-machine ip'.

```bash
$ scripts/docker runserver
```

--------------------------------

### Define Child Module Menu Structure in XML

Source: https://github.com/dimagi/commcare-hq/blob/master/docs/apps/advanced_app_features.rst

Example of configuring a child module 'm1' under parent 'm0' by setting the root attribute in the suite.xml file.

```xml
<menu id="m0">
    <text>
        <locale id="modules.m0"/>
    </text>
    <command id="m0-f0"/>
</menu>
<menu id="m1" root="m0">
    <text>
        <locale id="modules.m1"/>
    </text>
    <command id="m1-f0"/>
</menu>
```