Replace LocalStack with Floci for local S3 emulation

[bencap]

Summary

LocalStack's community edition was archived in March 2026, with core services (including S3) moved behind a $39/month paywall. MaveDB uses LocalStack exclusively to emulate S3 locally for score set CSV upload and download flows. Floci is a MIT-licensed drop-in replacement that emulates AWS APIs on the same port (4566) and is compatible with boto3 and the AWS CLI.

Problem

docker-compose-dev.yml currently pulls localstack/localstack:latest, which now requires a paid auth token to start. Developers running the full dev stack will encounter auth failures on docker compose up as this image no longer works without a license.

Proposed Behavior

Replace the localstack service in docker-compose-dev.yml with an equivalent Floci service. The S3 endpoint URL, bucket name, and init script behavior should remain functionally identical from the application's perspective.

Acceptance Criteria

• docker compose up starts successfully with no LocalStack auth errors
• The Floci service is reachable at http://floci:4566 from within the compose network
• The score-set-csv-uploads-dev bucket is created automatically on container startup
• A score set CSV can be uploaded via the API and subsequently downloaded during variant processing without error
• S3_ENDPOINT_URL in settings/.env.template reflects the updated service hostname (http://floci:4566)

Implementation Notes

api/docker-compose-dev.yml

Replace the localstack service block:

localstack:
  image: localstack/localstack:latest
  ports:
    - "4566:4566"
  env_file:
    - settings/.env.dev
  environment:
    - SERVICES=s3:4566
  volumes:
    - mavedb-localstack-dev:/var/lib/localstack
    - "./bin/localstack-init.sh:/etc/localstack/init/ready.d/localstack-init.sh"

With a Floci equivalent (confirm the exact image name and init hook path from the Floci docs — the volume mount path for init scripts differs from LocalStack's /etc/localstack/init/ready.d/). Also rename the named volume from mavedb-localstack-dev to mavedb-floci-dev and update the volumes: block at the bottom of the file accordingly.

api/bin/localstack-init.sh

The init script currently uses the awslocal wrapper CLI:

awslocal s3 mb s3://score-set-csv-uploads-dev

Floci's latest-compat image bundles the standard AWS CLI. Verify whether awslocal is available in the chosen Floci image; if not, replace the call with:

aws --endpoint-url=http://localhost:4566 s3 mb s3://score-set-csv-uploads-dev

Consider renaming the script to floci-init.sh to match the new service name and update the volume mount path in docker-compose-dev.yml.

api/settings/.env.template

Update the S3 endpoint URL to match the renamed compose service:

S3_ENDPOINT_URL=http://floci:4566

Also update settings/.env.dev (or its generation process) to keep the running dev environment in sync.

No test changes required. Tests mock mavedb.routers.score_sets.s3_client and mavedb.worker.jobs.variant_processing.creation.s3_client directly via unittest.mock and do not start or connect to the emulator.

Known Floci limitation: Floci has a confirmed bug where ListObjects returns results in reverse alphabetical order. MaveDB only calls PutObject, GetObject, and DeleteObjects, so this does not affect any current functionality.

[EstelleDa]

I applied a LocalStack account and added LOCALSTACK_AUTH_TOKEN=XXXXX in .env.dev file to solve this problem. It's free but I'm not sure how long it'll be free.