Skip to main content

Gotchas: semantic-doc-segmenter

Package-specific non-obvious patterns and pitfalls. Loaded on demand when working on this package.

  • Needs docker-compose.local.yml overlay: The service's own docker-compose.yaml bundles a MySQL service and test service. The overlay (generated by generate-env.sh) disables them and adds the platform-local network. The CMD in .env.local must use -f docker-compose.yaml -f docker-compose.local.yml.
  • Alembic migration base was broken: Base migration (47cd9e9e0aa6) had upgrade() as pass (tables commented out) — fixed 2026-03-12 by uncommenting in alembic/versions/47cd9e9e0aa6_base.py. Migration file is baked into the Docker image — after fixing the source, the image must be rebuilt. If the broken base already ran, wipe alembic_version so migrations re-run from scratch: docker exec platform-mysql-<user> mysql -u appuser -ppassword doc_segmenter -e "DROP TABLE IF EXISTS alembic_version;" then aq-local-dev.sh restart semantic-doc-segmenter.