python-pdf2txt/README.md

# python-pdf2txt

`python-pdf2txt` is a Dockerized Python application designed to convert PDF files into editable Word documents. The application utilizes Flask to expose a web service that handles PDF file uploads through HTTP requests and returns the converted DOCX files using OCR technology.

## Features

- **PDF to Word Conversion**: Transforms PDF documents into DOCX format using advanced OCR capabilities.
- **Dockerized Application**: Facilitates easy deployment and consistent performance across various environments.
- **REST API**: Simple API for straightforward integration, supporting PDF uploads and DOCX retrievals.

## Getting Started

### Step 1: Clone the Repository

Clone the repository to your local machine to get started:

```bash
git clone https://github.com/your-username/python-pdf2txt.git
cd python-pdf2txt
```

### Step 2: Build and Run the Docker Container

Use Docker Compose to build and run your container:

```bash
docker-compose up --build -d
```

This command constructs the Docker image if it hasn't been built previously and runs the container in detached mode. The service will be available at localhost on port 4000.

### Step 3: Convert a PDF to Word

Convert a PDF to a Word document by executing the following curl command:

```bash
curl -X POST -F "file=@path_to_your_pdf_file.pdf" http://localhost:4000/upload-pdf --output converted.docx
```

Make sure to replace `path_to_your_pdf_file.pdf` with the actual path to the PDF you intend to convert. The output will be saved as `converted.docx`.

### Step 4: View Application Logs

To track the application's processes in real-time, you can view the logs:

```bash
tail -f ./logs/*
```

This command tails the log files, offering a live view into the application’s operational logs.

## Configuration Details

### Environment Variables

The application uses several environment variables to configure its behavior:

- `FLASK_ENV`: Sets the environment for the Flask application. In this case, `development` for enabling debug features.
- `FLASK_APP`: Points to the entry file of the Flask application. Here, it's set to `app.py`.
- `TESSDATA_PREFIX`: Specifies the directory where the Tesseract OCR data is stored, which is crucial for OCR functionality.

### Port Configuration

The Docker container is configured to expose the Flask application on port `4000` of the host machine, mapping it to port 5000 inside the container. This mapping is defined in the `docker-compose.yml` file, allowing the application to be accessible via `http://localhost:4000`.

### Volume Management

- **Uploads Folder**: The `./uploads` folder on the host is mapped to `/app/uploads` inside the Docker container. This is where uploaded PDF files are stored temporarily during processing.
- **Outputs Folder**: Similarly, the `./outputs` folder on the host is mapped to `/app/outputs` inside the container. This folder stores the converted Word documents, making them accessible outside the container.
- **Logs Folder**: The `./logs` folder is used to store log files generated by the application, providing insights into its operations and any errors.

This setup ensures that data persists across container restarts and is easily accessible for both inputs and outputs.