Local banzai setup for running at site

[timbeccue]

Changes in service of #422

This PR introduces the local setup we'll use for site deployments of banzai, sans calibration caching which will be added in a subsequent PR.

Local Banzai Notes

To run:

docker compose -f docker-compose-site.yml --env-file .site-banzai-env up -d --build

This requires an env file called .site-banzai-env that should look like this:

# .site-banzai-env

# Database Configuration
DB_ADDRESS=sqlite:////data/banzai.db    # Path for the docker container, not the host.
CAL_DB_ADDRESS=""                       # This should be the address to the AWS banzai database where we get calibrations
SITE_ID=

# API Configuration
API_ROOT=https://archive-api.lco.global/
AUTH_TOKEN=

# Data Paths
HOST_DATA_DIR=./site_banzai # this maps to /data in the container, and should contain unprocessed data in a subdirectory `raw`
HOST_PROCESSED_DIR=./site_banzai/output # path where processed data will be saved on the host

# Container Networking
FITS_BROKER=rabbitmq
FITS_BROKER_URL=amqp://rabbitmq:5672
FITS_EXCHANGE=fits_files
TASK_HOST=redis://redis:6379/0

# Celery Configuration
CELERY_TASK_QUEUE_NAME=e2e_task_queue
CELERY_LARGE_TASK_QUEUE_NAME=e2e_large_task_queue

# Worker Configuration
BANZAI_WORKER_LOGLEVEL=debug
OMP_NUM_THREADS=2
OPENTSDB_PYTHON_METRICS_TEST_MODE=1

In order to send images to be processed, run:

python queue_images.py <host_data_dir>/raw

The data to be processed should be in the directory ${HOST_DATA_DIR}/raw. The output will be saved in ./${HOST_PROCESSED_DIR}.

[timbeccue]

Is the prior docker-compose.yml file important to preserve? If not, I'll replace it with my version, currently docker-compose.local.yml

[cmccully]

This feels like it should be in the main.py parse args code rather than the context. The context stuff doesn't really care what we put into the object itself.

[cmccully]

This is where the cal-db-address should be set. default the arg to None and then check for None in this function.

[timbeccue]

I tried your suggestion of removing the cal_db_address fallback from context.py but that caused issues in the e2e tests because some parts of the code (e2e tests and celery workers) don’t use parse_args to set up the context, and were therefore failing to set the cal_db_address fallback to db_address.

Seems like the solution is either

1. add the init logic back to context.py
2. use access patterns like getattr(runtime_context, ‘cal_db_address’, runtime_context.db_address) everywhere cal_db_address is used (messy)
3. require setting cal_db_address explicitly (might break existing banzai setups)
4. get rid of the separate cal_db_address entirely

Any of these fixes is relatively easy to implement but option 4 seems best from an overall complexity standpoint if we are ok with the docker-compose-local.yml setup requiring users to set up their own db from scratch.

[timbeccue]

I've gone ahead with option 1 (adding init logic back to context.py) just to get tests working again

[cmccully]

What is the error trying to check? This feels too specific and like you are trying to solve something else here.

[timbeccue]

I think I encountered some files that were missing the s3 url. Something from when I was working on the old cache setup a while back. Unfortunately I'm fuzzy on the details, but here's an example log with a file that prompted this:

2025-10-22 17:36:36.624 | 2025-10-22 21:36:36.620    ERROR:            sync: Unexpected error downloading lsc0m412-sq35-20240315-bpm-central30x30.fits.fz (frameid: 69366609, type: BPM): 'url' | {"processName": "MainProcess"}
...
2025-10-22 17:36:36.624 |     bytes = buffer.write(requests.get(response.json()['url'], stream=True, timeout=60).content)
2025-10-22 17:36:36.624 | KeyError: 'url'

I don't think the code is hitting this file anymore, and I tried running without this block and there were no issues. So maybe best to remove it?

[cmccully]

This feels redundant with the file utils function. What new things does this add?

[timbeccue]

This uses the file path rather than the frameid with the intended use case of wanting to process a file that exists on the local disk. Maybe it would be cleaner to modify the file utils function to accept a frameid or path?

[timbeccue]

I am leaning towards keeping post_to_processing_queue separate from post_to_archive_queue in file utils because different intended workflows (local disk vs s3), and because this is a small function that's pretty limited in scope and maybe not worth setting up the abstraction elsewhere. Let me know if you disagree.

[cmccully]

Some recommendations for cleanup, but overall looks fine.

[cmccully]

You also need to add a change log message and update the pyproject version number.

[timbeccue]

Added the requested changes. Two of your comments I did not change but replied with details; let me know if there's anything else needed for those to be resolved.