Project Setup

Setting up a Virtual Environment

1. Create a virtual environment:

   For Linux/macOS:

   python3 -m venv .venv
   

   For Windows:

   ## ACH-server-import-media
   
   This repository contains a script to import media files from an S3-compatible bucket into a database. It supports both local execution (virtual environment) and Docker-based deployment via `docker-compose`.
   
   Contents
   - `main.py` - main import script
   - `docker-compose.yml` - docker-compose service for running the importer in a container
   - `requirements.txt` - Python dependencies
   - `config.py`, `.env` - configuration and environment variables
   
   Prerequisites
   - Docker & Docker Compose (or Docker Desktop)
   - Python 3.8+
   - Git (optional)
   
   Quick local setup (virtual environment)
   
   Linux / macOS
   ```bash
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
   

   Windows (PowerShell)

   python -m venv .venv
   . .venv\Scripts\Activate.ps1
   pip install -r requirements.txt
   

   Running locally

   1. Ensure your configuration is available (see config.py or provide a .env file with the environment variables used by the project).
   2. Run the script (from the project root):

   Linux / macOS

   python main.py
   

   Windows (PowerShell)

   & .venv\Scripts\python.exe main.py
   

   Docker Compose

   This project includes a docker-compose.yml with a service named app (container name ACH_server_media_importer). The compose file reads environment variables from .env and mounts a logs named volume.

   Build and run (detached)

   # Docker Compose v2 syntax (recommended)
   # From the repository root
   
   docker compose up -d --build
   
   # OR if your environment uses the v1 binary
   # docker-compose up -d --build
   

   Show logs

   # Follow logs for the 'app' service
   docker compose logs -f app
   
   # Or use the container name
   docker logs -f ACH_server_media_importer
   

   Stop / start / down

   # Stop containers
   docker compose stop
   
   # Start again
   docker compose start
   
   # Take down containers and network
   docker compose down
   

   Rebuild when already running

   There are two safe, common ways to rebuild a service when the containers are already running:

   1. Rebuild in-place and recreate changed containers (recommended for most changes):

   # Rebuild images and recreate services in the background
   docker compose up -d --build
   

   This tells Compose to rebuild the image(s) and recreate containers for services whose image or configuration changed.

   2. Full clean rebuild (use when you need to remove volumes or ensure a clean state):

   # Stop and remove containers, networks, and optionally volumes & images, then rebuild
   docker compose down --volumes --rmi local
   docker compose up -d --build
   

   Notes

   • docker compose up -d --build will recreate containers for services that need updating; it does not destroy named volumes unless you pass --volumes to down.
   • If you need to execute a shell inside the running container:

   # run a shell inside the 'app' service
   docker compose exec app /bin/sh
   # or (if bash is available)
   docker compose exec app /bin/bash
   

   Environment and configuration

   • Provide sensitive values via a .env file (the docker-compose.yml already references .env).
   • Typical variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, BUCKET_NAME, DB_HOST, DB_NAME, DB_USER, SMTP_SERVER, etc.

   Troubleshooting

   • If Compose fails to pick up code changes, ensure your local Dockerfile COPY commands include the source files and that docker compose up -d --build is run from the repository root.
   • Use docker compose logs -f app to inspect runtime errors.

   If you'd like, I can add a short Makefile or a PowerShell script to wrap the common Docker Compose commands (build, rebuild, logs) for convenience.

   ---

   Edited to add clear docker-compose rebuild and run instructions.