justfile

set dotenv-load := false

COLOR := "\\033[0;34m"
NO_COLOR := "\\033[0m"

# Show all available recipes
@_default:
    printf "\n{{ COLOR }}# API (path: \`api/\`)\n"
    printf "===================={{ NO_COLOR }}\n"
    just --list --unsorted


###########
# Version #
###########

# These commands use standard GNU tools instead of `pdm` because we do not
# require PDM on the host machine for API development.
export API_PDM_HASH := `grep 'content_hash' pdm.lock | awk -F'[:"]' '{print $3}' | cut -c1-8`
export API_PY_VERSION := `grep 'requires-python' pyproject.toml | awk -F'"' '{print $2}' | sed 's/^==//g; s/\.\*$//g'`
export PGCLI_VERSION := `grep -A 1 'name = "pgcli"' pdm.lock | grep 'version' | awk -F'"' '{print $2}'`

# Print the PDM content hash as a unique identifier for the current set of packages
@pdm-hash:
    echo $API_PDM_HASH

# Print the Python version specified in `pyproject.toml`
@py-version:
    echo $API_PY_VERSION

# Print the pinned `pgcli` version from the PDM lockfile
@pgcli-version:
    echo $PGCLI_VERSION

###########
# Install #
###########

# Install dependencies
install *args:
    pdm install {{ args }}

######
# Up #
######

# Bring up services specific to the API profile
[positional-arguments]
up *flags:
    env COMPOSE_PROFILES="api" just ../up "$@"

# Bring up services specific to the API profile, in addition to the API server
[positional-arguments]
up-extra *flags:
    env COMPOSE_PROFILES="api,api_extra" just ../up "$@"

# Wait for all profile services to be up
wait-up: up
    just ../ingestion_server/wait # API profile includes ingestion server
    just wait # API waits for ES in entrypoint

# Load sample data into API via ingestion server
init: wait-up
    cd .. && ./load_sample_data.sh

recreate:
    just ../down -v
    just up "--force-recreate --build"
    just init

##########
# Health #
##########

# Check the health of the service
@health host="localhost:50280":
    -curl -s -o /dev/null -w '%{http_code}' 'http://{{ host }}/healthcheck/'

# Wait for the service to be healthy
@wait host="localhost:50280":
    # The just command on the second line is executed in the context of the
    # parent directory and so must be prefixed with `api/`.
    just ../_loop \
    '"$(just api/health {{ host }})" != "200"' \
    "Waiting for the API to be healthy..."

########
# cURL #
########

# Make a cURL GET request to service at the given path
@_curl-get path origin="http://localhost:50280":
    curl "{{ origin }}/v1/{{ path }}"

# Make a test cURL GET request to the API
@stats media="images" origin="http://localhost:50280":
    just _curl-get "{{ media }}/stats/" {{ origin }}

# Launch a `pgcli` shell in the web container
pgcli db_user_pass="deploy" db_name="openledger": up
    env DC_USER="opener" just ../_pgcli web {{ db_user_pass }} {{ db_name }} db

#########################
# Django administration #
#########################

# Run Django administrative commands locally
[positional-arguments]
dj-local *args:
    pdm run python manage.py "$@"

# Run Django administrative commands inside the Docker container
[positional-arguments]
dj *args: wait-up
    env DC_USER="{{ env_var_or_default("DC_USER", "opener") }}" just ../exec web python manage.py "$@"

# Get IPython shell inside the Docker container
ipython:
    just dj shell

# Get DB shell inside the Docker container
dbshell:
    just dj dbshell

# Generate the specified kind of documentation
generate-docs doc="media-props" fail_on_diff="true":
    #!/bin/bash
    set -e
    if [ "{{ doc }}" == "media-props" ]; then
        FINAL_FILE="documentation/meta/media_properties/api.md"
        NAME="Media properties"
        just dj documentmedia
        mv media_properties.md ../$FINAL_FILE
        # Take ownership of media properties file.
        if [ "$(ls -l ../$FINAL_FILE | awk '{print $3}')" != "$(whoami)" ]; then
          sudo chown $(whoami) ../$FINAL_FILE
        fi
    else
        echo "Invalid documentation type specified, use \`media-props\`. Exiting."
        exit 1
    fi
    echo -n "Running linting..."
    just ../lint prettier $FINAL_FILE &>/dev/null || true
    echo "Done!"
    if {{ fail_on_diff }}; then
      set +e
      git diff --exit-code ../$FINAL_FILE
      if [ $? -ne 0 ]; then
          printf "\n\n\e[31m!! Changes found in $NAME documentation, please run 'just api/generate-docs {{ doc }}' locally and commit difference !!\n\n"
          exit 1
      fi
    fi

#########
# Tests #
#########

# Run API tests inside the Docker container
[positional-arguments]
test *args: wait-up
    env DC_USER="opener" just ../exec web pytest "$@"

# Run API tests locally
[positional-arguments]
test-local *args:
    pdm run pytest "$@"

# Run smoke test for the API docs
doc-test: wait-up
    curl \
      -H 'Accept: application/vnd.oai.openapi+json' \
      --fail \
      'http://localhost:50280/v1/schema/' > openapi.json

#########
# NGINX #
#########

# Build and run the NGINX image locally
nginx upstream_url='api.openverse.org':
    # upstream_url can also be set to 172.17.0.1:50280 for local testing
    docker build --target nginx . -t openverse-api_nginx:latest
    @echo "--> NGINX server will be run at http://localhost:9090, upstream at {{ upstream_url }}"
    @echo "--> Try a static URL like http://localhost:9090/static/admin/css/base.css to test"
    docker run --rm -p 9090:8080 -it \
      -e DJANGO_NGINX_UPSTREAM_URL="{{ upstream_url }}" \
      -e DJANGO_NGINX_GIT_REVISION="$(git rev-parse HEAD)" \
      openverse-api_nginx:latest