[ENG-11345] improve docs and dev setup

[aaxelb]

• fix link to search api docs in how-to/use-the-api.md
• recommend running setup commands in indexer container instead of worker
• local docker-compose setup: loosen permissions on es8 certs shared among containers, allow celery user to read without copy/chown shenanigans

[coveralls]

coverage: 84.501%. remained the same — aaxelb:docs/clarifications-2026 into CenterForOpenScience:develop

[cslzchen]

Thanks for the quick update. I removed SHARE images/volumes and verified that everything works as expected with this updated doc. I was concerned if indexer will start without migration applied (unlike worker) and confirmed it works.

One minor thing as I mentioned in my documentation review ticket, need to docker compose down everything before docker compose up -d worker if we run into the following error with elastic8_setup.

 ✘ Container share-elastic8_setup-1 Error dependency elastic8_setup failed to start                                                                                              1.1s
dependency failed to start: container share-elastic8_setup-1 exited (0)

[cslzchen]

Verified locally, no more issues when starting worker.

(share-3.12) ➜  share git:(docs/clarifications-2026) dcup worker
WARN[0000] /Users/longze/Projects/share/docker-compose.yml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion
[+] up 7/7
 ✔ Container share-elastic8_setup-1 Exited                                                                                                                                                                                                                                                                                                                              2.9s
 ✔ Container share-postgres-1       Started                                                                                                                                                                                                                                                                                                                             0.3s
 ✔ Container share-rabbitmq-1       Started                                                                                                                                                                                                                                                                                                                             0.3s
 ✔ Container share-elastic8-1       Started                                                                                                                                                                                                                                                                                                                             2.9s
 ✔ Container share-indexer-1        Started                                                                                                                                                                                                                                                                                                                             3.0s
 ✔ Container share-web-1            Started                                                                                                                                                                                                                                                                                                                             2.9s
 ✔ Container share-worker-1         Started                                                                                                                                                                                                                                                                                                                             3.0s

What's next:
    Filter, search, and stream logs from all your Compose services
    in one place with Docker Desktop's Logs view. docker-desktop://dashboard/logs
(share-3.12) ➜  share git:(docs/clarifications-2026) dclg 100 elastic8_setup
WARN[0000] /Users/longze/Projects/share/docker-compose.yml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion
elastic8_setup-1  | Setting cert file permissions (give read permission to all users -- may not be suitable for production)
elastic8_setup-1  | All done!

...

(share-3.12) ➜  share git:(docs/clarifications-2026) dcup worker
WARN[0000] /Users/longze/Projects/share/docker-compose.yml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion
[+] up 7/7
 ✔ Container share-rabbitmq-1       Running                                                                                                                                                                                                                                                                                                                             0.0s
 ✔ Container share-postgres-1       Running                                                                                                                                                                                                                                                                                                                             0.0s
 ✔ Container share-elastic8-1       Running                                                                                                                                                                                                                                                                                                                             0.0s
 ✔ Container share-web-1            Running                                                                                                                                                                                                                                                                                                                             0.0s
 ✔ Container share-indexer-1        Running                                                                                                                                                                                                                                                                                                                             0.0s
 ✔ Container share-worker-1         Running                                                                                                                                                                                                                                                                                                                             0.0s
 ✔ Container share-elastic8_setup-1 Exited                                                                                                                                                                                                                                                                                                                              0.6s

What's next:
    Filter, search, and stream logs from all your Compose services
    in one place with Docker Desktop's Logs view. docker-desktop://dashboard/logs
(share-3.12) ➜  share git:(docs/clarifications-2026) dclg 100 elastic8_setup
WARN[0000] /Users/longze/Projects/share/docker-compose.yml: the attribute `version` is obsolete, it will be ignored, please remove it to avoid potential confusion
elastic8_setup-1  | Setting cert file permissions (give read permission to all users -- may not be suitable for production)
elastic8_setup-1  | All done!
elastic8_setup-1  | Setting cert file permissions (give read permission to all users -- may not be suitable for production)
elastic8_setup-1  | All done!

...