# Project Setup

## Setting up a Virtual Environment

1. **Create a virtual environment:**

   ### For Linux/macOS:
   ```bash
   python3 -m venv .venv
   ```

   ### For Windows:
   ```bash
   ## 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)
   ```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
   ```bash
   python main.py
   ```

   Windows (PowerShell)
   ```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)
   ```powershell
   # 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
   ```powershell
   # 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
   ```powershell
   # 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):

   ```powershell
   # 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):

   ```powershell
   # 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:

   ```powershell
   # 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.