Image → Story Generator

Flask app with PostgreSQL, Docker Compose, and Ollama

This project allows a user to upload an image, send it to a local Ollama model, and receive a generated story.
Each story is stored in a PostgreSQL database, using the image filename as an identifier.
If the same image is uploaded again, the app returns the previously saved story instead of generating a new one.

---

🚀 Features

• Upload an image through the Flask API
• Generate a story from the image using an Ollama model
• Save stories in PostgreSQL (image name = identifier)
• Return existing story if the image was already processed
• Fully containerized using Docker Compose
• Ability to map a local Ollama model into the container so you don’t have to re-pull it every time

---

📦 Project Setup

1. Clone the Repository

git clone <your-repo-url>
cd <project-folder>

2. 🧠 Setting Up Ollama (Linux)

To avoid pulling the model every time the container is rebuilt, we will map the local Ollama model directory into the Docker container.

1. Install Ollama according to the official instructions:

   curl -fsSL https://ollama.com/install.sh | sh

2. Start the Ollama server

   ollama serve

3. In another terminal, pull the model you want to use:

   ollama pull llava-llama3

   Make sure the pulled model name matches the model used inside your Flask app.

3. 🔍 Finding the Model Directory (Host & Container)

1. On your host machine:

   sudo find / -name models | grep "ollama"

   This typically outputs something like:

   /usr/share/ollama/models
   /home/<user>/.ollama/models

   Use the directory that contains your pulled model(s).
2. You need to know the location of the model path inside the container to map it correctly. Start the container once:

   docker compose up --build

   In another terminal, find the container ID:

   docker ps

   And open a shell inside the container:

   docker exec -it <container_id> /bin/bash

   Find the internal model directory:

   find / -name models | grep "ollama"

   This will get you a path such as:

   /root/.ollama/models

4. 🔗 Mapping the Model Volume

In your docker-compose.yml, map the local models folder into the container:

volumes:
  - /path/to/local/ollama/models:/root/.ollama/models

This ensures:

• The container uses your local model files
• You do not need to pull large models again when rebuilding the container
• The model remains persistent across rebuilds

5. 📄 Create a .env

Copy the .env.example file and rename it:

cp .env.example .env

Update the variables if needed (database credentials, model name, etc.).

You can configure optional downscaling settings in your .env file to reduce image size before sending it to the vision model.
This can speed up processing, especially for very large uploads.

However, note that many vision models internally downscale images anyway, so the performance gain may be limited depending on the model you use.

6. ▶️ Run the Full Stack

docker compose up --build

Once running:

• Open the Flask app in your browser at: http://localhost:5000

• Open Adminer (database UI) at: http://localhost:8080

You are now ready to upload images and generate stories!