139 lines
4.1 KiB
Markdown
139 lines
4.1 KiB
Markdown
# 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.
|