Refactor sprites build

.circleci/config.yml

@@ -7,10 +7,10 @@ jobs:
     steps:
       - checkout
       - run:
-          name: Pull Submodules
+          name: Pull Cries Submodule
           command: |
-            git submodule init
-            git submodule update --remote
+            git submodule init data/v2/cries
+            git submodule update --remote data/v2/cries
       - run:
           name: Install deps
           command: make install
@@ -33,10 +33,10 @@ jobs:
     steps:
       - checkout
       - run:
-          name: Pull Submodules
+          name: Pull Cries Submodule
           command: |
-            git submodule init
-            git submodule update --remote
+            git submodule init data/v2/cries
+            git submodule update --remote data/v2/cries
       - run:
           name: Install deps
           command: make install
@@ -58,10 +58,10 @@ jobs:
     steps:
       - checkout
       - run:
-          name: Pull Submodules
+          name: Pull Cries Submodule
           command: |
-            git submodule init
-            git submodule update --remote
+            git submodule init data/v2/cries
+            git submodule update --remote data/v2/cries
       - run:
           name: Install deps
           command: make install-base
@@ -79,10 +79,10 @@ jobs:
     steps:
       - checkout
       - run:
-          name: Pull Submodules
+          name: Pull Cries Submodule
           command: |
-            git submodule init
-            git submodule update --remote
+            git submodule init data/v2/cries
+            git submodule update --remote data/v2/cries
       - add_ssh_keys:
           fingerprints:
             - "d3:5f:9d:68:ea:12:9a:42:d3:d3:e1:db:b0:6a:fc:d2"

.github/workflows/database.yml

@@ -53,8 +53,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
-        with:
-          submodules: recursive
+      - name: Pull cries submodule
+        run: git submodule update --init data/v2/cries
       - name: Setup uv
         uses: ./.github/actions/setup-uv
         with:
@@ -75,8 +75,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
-        with:
-          submodules: recursive
+      - name: Pull cries submodule
+        run: git submodule update --init data/v2/cries
       - name: Setup uv
         uses: ./.github/actions/setup-uv
       - name: Build and start services

.github/workflows/docker-build-and-push.yml

@@ -21,8 +21,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
-        with:
-          submodules: recursive
+      - name: Pull cries submodule
+        run: git submodule update --init data/v2/cries
       - name: Docker meta
         id: meta
         uses: docker/metadata-action@v5

.github/workflows/docker-k8s.yml

@@ -20,8 +20,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
-        with:
-          submodules: recursive
+      - name: Pull cries submodule
+        run: git submodule update --init data/v2/cries
       - name: Docker meta
         id: meta
         uses: docker/metadata-action@v5
@@ -49,8 +49,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
-        with:
-          submodules: recursive
+      - name: Pull cries submodule
+        run: git submodule update --init data/v2/cries
       - name: Docker meta
         id: meta
         uses: docker/metadata-action@v5

.github/workflows/nix-environment.yml

@@ -20,8 +20,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
-        with:
-          submodules: recursive
+      - name: Pull cries submodule
+        run: git submodule update --init data/v2/cries
 
       - name: Install Nix
         uses: cachix/install-nix-action@v31

.github/workflows/release.yml

@@ -22,8 +22,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
-        with:
-          submodules: recursive
+      - name: Pull cries submodule
+        run: git submodule update --init data/v2/cries
       - name: Start pokeapi (docker)
         run: |
           make docker-dev-up

.gitignore

@@ -11,3 +11,4 @@ node_modules
 Resources/nginx/ssl/*
 !Resources/nginx/ssl/*.sample.*
 .idea*
+data/v2/manifest.json*

Makefile

@@ -170,7 +170,7 @@ k8s-delete:  # (k8s) Delete pokeapi namespace
 
 start-graphql-prod:
 	git pull origin master
-	git submodule update --init
+	git submodule update --init data/v2/cries
 	docker compose -f docker-compose.yml -f Resources/compose/docker-compose-prod-graphql.yml up -d
 	docker compose stop app cache
 
@@ -184,7 +184,7 @@ down-graphql-prod:
 update-graphql-data-prod-old:
 	docker compose ${gql_compose_config} stop
 	git pull origin master
-	git submodule update --remote --merge
+	git submodule update --remote --merge data/v2/cries
 	docker compose ${gql_compose_config_deprecated} up --pull always -d app cache db
 	sync; echo 3 > /proc/sys/vm/drop_caches
 	make docker-migrate
@@ -200,7 +200,7 @@ update-graphql-data-prod-old:
 
 update-graphql-data-prod:
 	git pull origin master
-	git submodule update --remote --merge
+	git submodule update --remote --merge data/v2/cries
 	curl -Ss -L -O https://github.com/PokeAPI/pokeapi/releases/download/master-branch/pokeapi.pgdump
 	docker compose ${gql_compose_config} stop web graphql-engine app cache
 	docker compose ${gql_compose_config} down -v db

README.md

@@ -34,7 +34,17 @@ A RESTful API for Pokémon - [pokeapi.co](https://pokeapi.co)
 
 ## Setup <a id="setup"></a> &nbsp; [![pyVersion313](https://img.shields.io/badge/python-3.13-blue.svg)](https://www.python.org/downloads/release/python-3137/)
 
-- Download this source code into a working directory, be sure to use the flag `--recurse-submodules` to clone also our submodules.
+- Download this source code into a working directory and initialize the cries submodule:
+
+    ```sh
+    git clone https://github.com/PokeAPI/pokeapi.git
+    cd pokeapi
+    git submodule update --init data/v2/cries
+    ```
+
+> [!NOTE]  
+> The `data/v2/cries` submodule (~25 MB) is required to build cry sound URLs.
+> The `sprites` submodule (10+ GB) is **optional**, the database build automatically downloads the lightweight sprite manifest when building data. If you wish to clone all submodules locally, you can pass `--recurse-submodules`.
 
 - Install [uv](https://docs.astral.sh/uv/getting-started/installation/) for Python environment management.
 
@@ -51,8 +61,8 @@ A RESTful API for Pokémon - [pokeapi.co](https://pokeapi.co)
     make pre-commit-install
     ```
 
-    > [!NOTE]
-    > Pre-commit hooks are optional but recommended for maintaining code quality and consistency. If you do not want it to automatically run on every commit, you can run it manually with `make pre-commit` before committing and pushing your changes.
+> [!NOTE]
+> Pre-commit hooks are optional but recommended for maintaining code quality and consistency. If you do not want it to automatically run on every commit, you can run it manually with `make pre-commit` before committing and pushing your changes.
 
 - Lint, format, and typecheck your code changes:
 
@@ -87,7 +97,18 @@ make build-db
 
 Visit [localhost:8000/api/v2/](http://localhost:8000/api/v2/) to see the running API!
 
-Each time the `build-db` script is run, it will iterate over each table in the database, wipe it, and rewrite each row using the data found in data/v2/csv.
+Each time the `build-db` script is run, it will iterate over each table in the database, wipe it, and rewrite each row using the data found in `data/v2/csv`.
+
+### Environment Variables
+
+The database build supports several optional environment variables:
+
+| Variable                       | Default                                                             | Description                                                                                                                    |
+| ------------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `POKEAPI_SPRITES_PREFIX`       | `https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/` | Base URL prefix used for sprite URLs in API responses.                                                                         |
+| `POKEAPI_CRIES_PREFIX`         | `https://raw.githubusercontent.com/PokeAPI/cries/main/cries/`       | Base URL prefix used for Pokémon cry sound file URLs.                                                                          |
+| `POKEAPI_SPRITES_MANIFEST_URL` | `https://pokeapi.github.io/sprites/manifest.json.gz`                | Custom URL for downloading the sprite `manifest.json.gz`.                                                                      |
+| `POKEAPI_USE_LOCAL_SPRITES`    | `0`                                                                 | Set to `1` to force scanning local cloned sprites submodule (`data/v2/sprites/sprites/`) instead of using the remote manifest. |
 
 If you ever need to wipe the database use this command:
 
@@ -179,31 +200,31 @@ This k8s setup creates all k8s resources inside the _Namespace_ `pokeapi`, run `
 
 ## Wrappers
 
-| Official wrapper | Repository | Features |
-| --- | --- | --- |
-| Node server-side | [PokeAPI/pokedex-promise-v2](https://github.com/PokeAPI/pokedex-promise-v2) | _Auto caching_ |
+| Official wrapper    | Repository                                                                  | Features                        |
+| ------------------- | --------------------------------------------------------------------------- | ------------------------------- |
+| Node server-side    | [PokeAPI/pokedex-promise-v2](https://github.com/PokeAPI/pokedex-promise-v2) | _Auto caching_                  |
 | Browser client-side | [PokeAPI/pokeapi-js-wrapper](https://github.com/PokeAPI/pokeapi-js-wrapper) | _Auto caching_, _Image caching_ |
-| Java/Kotlin | [PokeAPI/pokekotlin](https://github.com/PokeAPI/pokekotlin) | |
-| Python 2/3 | [PokeAPI/pokepy](https://github.com/PokeAPI/pokepy) | _Auto caching_ |
-| Python 3 | [PokeAPI/pokebase](https://github.com/PokeAPI/pokebase) | _Auto caching_, _Image caching_ |
-
-|Wrapper|Repository|Features|
-|---|---|---|
-|.Net Standard |[mtrdp642/PokeApiNet](https://github.com/mtrdp642/PokeApiNet)|Auto caching |
-|Dart|[prathanbomb/pokedart](https://github.com/prathanbomb/pokedart)| |
-|Go|[mtslzr/pokeapi-go](https://github.com/mtslzr/pokeapi-go)|Auto caching |
-|Go|[JoshGuarino/PokeGo](https://github.com/JoshGuarino/PokeGo) |Auto caching |
-|Godot|[UbeJelly/PokeDot](https://github.com/UbeJelly/PokeDot) | |
-|Haxe|[KinoCreatesGames/poke-api](https://github.com/KinoCreatesGames/poke-api) |Auto caching |
-|PHP |[lmerotta/phpokeapi](https://github.com/lmerotta/phpokeapi)|Auto caching, lazy loading |
-|PowerShell|[Celerium/PokeAPI-PowerShellWrapper](https://github.com/Celerium/PokeAPI-PowerShellWrapper)| |
-|Python|[beastmatser/aiopokeapi](https://github.com/beastmatser/aiopokeapi)|Auto caching, asynchronous |
-|Ruby|[rdavid1099/poke-api-v2](https://github.com/rdavid1099/poke-api-v2)| |
-|Rust|[lunik1/pokerust](https://gitlab.com/lunik1/pokerust)|Auto caching |
-|Scala |[juliano/pokeapi-scala](https://github.com/juliano/pokeapi-scala)|Auto caching |
-|Spring Boot |[dlfigueira/spring-pokeapi](https://github.com/dlfigueira/spring-pokeapi)|Auto caching |
-|Swift |[kinkofer/PokemonAPI](https://github.com/kinkofer/PokemonAPI)| |
-|Typescript server-side/client-side|[Gabb-c/Pokenode-ts](https://github.com/Gabb-c/pokenode-ts)|Auto caching |
+| Java/Kotlin         | [PokeAPI/pokekotlin](https://github.com/PokeAPI/pokekotlin)                 |                                 |
+| Python 2/3          | [PokeAPI/pokepy](https://github.com/PokeAPI/pokepy)                         | _Auto caching_                  |
+| Python 3            | [PokeAPI/pokebase](https://github.com/PokeAPI/pokebase)                     | _Auto caching_, _Image caching_ |
+
+| Wrapper                            | Repository                                                                                  | Features                   |
+| ---------------------------------- | ------------------------------------------------------------------------------------------- | -------------------------- |
+| .Net Standard                      | [mtrdp642/PokeApiNet](https://github.com/mtrdp642/PokeApiNet)                               | Auto caching               |
+| Dart                               | [prathanbomb/pokedart](https://github.com/prathanbomb/pokedart)                             |                            |
+| Go                                 | [mtslzr/pokeapi-go](https://github.com/mtslzr/pokeapi-go)                                   | Auto caching               |
+| Go                                 | [JoshGuarino/PokeGo](https://github.com/JoshGuarino/PokeGo)                                 | Auto caching               |
+| Godot                              | [UbeJelly/PokeDot](https://github.com/UbeJelly/PokeDot)                                     |                            |
+| Haxe                               | [KinoCreatesGames/poke-api](https://github.com/KinoCreatesGames/poke-api)                   | Auto caching               |
+| PHP                                | [lmerotta/phpokeapi](https://github.com/lmerotta/phpokeapi)                                 | Auto caching, lazy loading |
+| PowerShell                         | [Celerium/PokeAPI-PowerShellWrapper](https://github.com/Celerium/PokeAPI-PowerShellWrapper) |                            |
+| Python                             | [beastmatser/aiopokeapi](https://github.com/beastmatser/aiopokeapi)                         | Auto caching, asynchronous |
+| Ruby                               | [rdavid1099/poke-api-v2](https://github.com/rdavid1099/poke-api-v2)                         |                            |
+| Rust                               | [lunik1/pokerust](https://gitlab.com/lunik1/pokerust)                                       | Auto caching               |
+| Scala                              | [juliano/pokeapi-scala](https://github.com/juliano/pokeapi-scala)                           | Auto caching               |
+| Spring Boot                        | [dlfigueira/spring-pokeapi](https://github.com/dlfigueira/spring-pokeapi)                   | Auto caching               |
+| Swift                              | [kinkofer/PokemonAPI](https://github.com/kinkofer/PokemonAPI)                               |                            |
+| Typescript server-side/client-side | [Gabb-c/Pokenode-ts](https://github.com/Gabb-c/pokenode-ts)                                 | Auto caching               |
 
 ## Donations
 

Resources/k8s/kustomize/base/deployments/pokeapi-deployment.yaml

@@ -28,7 +28,8 @@ spec:
           command: ['sh', '-c']
           args:
             - apk add --update git &&
-              git clone --depth=1 --single-branch --branch=master --recurse-submodules --shallow-submodules https://github.com/PokeAPI/pokeapi.git &&
+              git clone --depth=1 --single-branch --branch=master https://github.com/PokeAPI/pokeapi.git &&
+              (cd pokeapi && git submodule update --init data/v2/cries) &&
               mv /code/pokeapi/data/v2/* /tmp/
           workingDir: /code
           volumeMounts: