activestorage-ocr 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '06842e85669ce35ba5e03695a92bf5acaccf8519cbfa57d8f4803664757bcccd'
-  data.tar.gz: d513b79b0691862d8f79df97a4fd3da02a61c56b5eacc027723a9a5515218efc
+  metadata.gz: 407f4e4098cfdf7804094b783efa4e9dd6a8ef18ede70a8bf571eae693a17fa7
+  data.tar.gz: 368ec4b42ffa94ca71e6b6df4677d0af87dadd9ab14bf95e57a44aa2904e6a2d
 SHA512:
-  metadata.gz: 7bfd336fccd12c9dfa437671c0e318fedc5ead6bae106ddd91a85d05e72dc2d1efabc00d098614fce7a3791a12a94db6668110f65a32ea7894cf15646f668d7e
-  data.tar.gz: d32683900ac1e7136b5e8ef6b322acd75587dcd3c9a5aa62d08bddb5d45083137d42e19cdb02c6518c25f19cf9d704196c8dd86b0f8a2cbbd1fbd6f52c430bae
+  metadata.gz: 8cf7e677131db26961ca31684f932f4aff67a85c3b16ba1bb460ec49b1e74f172e64bd1be777bd0a0620df8756c62bdc858d9409857e27da48eb166bc0735669
+  data.tar.gz: 25b5ae857880af8f0e3a11e4874f15896f4451685e8cae45a0dce2cf6e1c9a8b5ac15f89f1e80920fa9f2bd3ce8bfcfb9a62ef38d99e57b4c977de5b8d65b30c

data/README.md

@@ -13,7 +13,7 @@ OCR for Rails Active Storage attachments, powered by Rust and [ocrs](https://git
 - **Pure Rust** - No Tesseract or system dependencies required
 - **Self-contained** - Models download automatically on first run (~50MB)
 - **Fast** - Processes images in ~150ms
-- **HTTP/JSON API** - Easy to debug and integrate
+- **Automatic** - OCR runs automatically when files are uploaded via Active Storage
 
 **Supported Formats:**
 - Images: PNG, JPEG, TIFF, WebP, GIF, BMP
@@ -32,53 +32,95 @@ OCR for Rails Active Storage attachments, powered by Rust and [ocrs](https://git
 
 ## Installation
 
-Add to your Gemfile:
+**1. Add to your Gemfile:**
 
 ```ruby
 gem "activestorage-ocr"
 ```
 
-Then install the OCR server binary:
+**2. Install the gem and OCR server binary:**
 
 ```bash
 bundle install
-bundle exec rake activestorage_ocr:install
+bin/rails activestorage_ocr:install
 ```
 
-## Quick Start
+**3. Add the OCR server to your `Procfile.dev`:**
 
-1. **Start the OCR server:**
+```procfile
+web: bin/rails server
+ocr: activestorage-ocr-server --host 127.0.0.1 --port 9292
+```
+
+Now when you run `bin/dev`, the OCR server starts automatically alongside Rails.
+
+> **Note:** If you don't have a `Procfile.dev`, create one. Rails 7+ apps typically use `bin/dev` with [foreman](https://github.com/ddollar/foreman) or [overmind](https://github.com/DarthSim/overmind) to manage multiple processes.
+
+## Usage
+
+Once installed, OCR happens **automatically** when you upload images or PDFs through Active Storage. The extracted text is stored in the blob's metadata.
+
+### Accessing OCR Results
+
+```ruby
+# After uploading a file
+document.file.analyze  # Triggers OCR (usually happens automatically)
+
+# Access the results from metadata
+document.file.metadata["ocr_text"]         # => "Extracted text..."
+document.file.metadata["ocr_confidence"]   # => 0.85
+document.file.metadata["ocr_processed_at"] # => "2024-12-24T12:00:00Z"
+```
+
+### Helper Methods (Optional)
+
+Add convenience methods to your model:
+
+```ruby
+class Document < ApplicationRecord
+  has_one_attached :file
+
+  def ocr_text
+    file.metadata["ocr_text"]
+  end
+
+  def ocr_confidence
+    file.metadata["ocr_confidence"]
+  end
+
+  def ocr_processed?
+    file.metadata["ocr_processed_at"].present?
+  end
+end
+```
 
-   ```bash
-   bundle exec rake activestorage_ocr:start
-   ```
+### Using the Client Directly
 
-2. **Use the client in your Rails app:**
+You can also use the client directly for more control:
 
-   ```ruby
-   # In rails console or your code
-   client = ActiveStorage::Ocr::Client.new
+```ruby
+client = ActiveStorage::Ocr::Client.new
 
-   # Check server health
-   client.healthy?  # => true
+# Check server health
+client.healthy?  # => true
 
-   # Extract text from a file
-   result = client.extract_text_from_path("/path/to/image.png", content_type: "image/png")
-   result.text        # => "Extracted text..."
-   result.confidence  # => 0.95
+# Extract text from a file path
+result = client.extract_text_from_path("/path/to/image.png")
+result.text        # => "Extracted text..."
+result.confidence  # => 0.95
 
-   # Extract text from an Active Storage attachment
-   result = client.extract_text(document.file)
-   ```
+# Extract text from an Active Storage attachment
+result = client.extract_text(document.file)
+```
 
 ## Configuration
 
 ```ruby
 # config/initializers/activestorage_ocr.rb
 ActiveStorage::Ocr.configure do |config|
-  config.server_host = "127.0.0.1"
-  config.server_port = 9292
-  config.timeout = 60
+  config.server_url = ENV.fetch("ACTIVESTORAGE_OCR_SERVER_URL", "http://127.0.0.1:9292")
+  config.timeout = 60        # Request timeout in seconds
+  config.open_timeout = 10   # Connection timeout in seconds
 end
 ```
 
@@ -86,23 +128,147 @@ end
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `ACTIVESTORAGE_OCR_HOST` | `127.0.0.1` | Server host |
-| `ACTIVESTORAGE_OCR_PORT` | `9292` | Server port |
+| `ACTIVESTORAGE_OCR_SERVER_URL` | `http://127.0.0.1:9292` | Full URL to the OCR server |
+
+## Production Deployment
+
+For production deployments, the OCR server binary needs to be installed in your app's `bin/` directory (not the gem directory) so it can be referenced from your Procfile.
+
+### Setup for Production
+
+**1. Run the install generator:**
+
+```bash
+rails generate activestorage_ocr:install
+```
+
+This creates:
+- `bin/activestorage-ocr-server` - A wrapper script that runs the OCR server
+- `bin/dist/activestorage-ocr-server` - The actual binary (gitignored)
+
+**2. Add to your Procfile:**
+
+```procfile
+web: bundle exec puma -C config/puma.rb
+ocr: bin/activestorage-ocr-server --host 127.0.0.1 --port 9292
+```
+
+### Docker Deployment
+
+In your `Dockerfile`, run the generator during the build to install the binary:
+
+```dockerfile
+# Install gems
+RUN bundle install
+
+# Install OCR server binary to bin/dist/
+RUN bundle exec rails activestorage_ocr:install path=./bin/dist
+
+# Alternatively, run the full generator:
+# RUN bundle exec rails generate activestorage_ocr:install
+```
+
+Use foreman to manage both processes:
+
+```dockerfile
+# Procfile
+CMD ["bundle", "exec", "foreman", "start"]
+```
+
+### Fly.io Deployment
+
+**fly.toml configuration:**
+
+```toml
+app = "your-app-name"
+primary_region = "iad"
+
+[deploy]
+  # Note: Don't use release_command for SQLite with volumes
+  # Migrations run in docker-entrypoint instead
+
+[env]
+  RAILS_ENV = "production"
+  ACTIVESTORAGE_OCR_SERVER_URL = "http://127.0.0.1:9292"
+
+[http_service]
+  internal_port = 8080
+  force_https = true
+
+[[mounts]]
+  source = "data"
+  destination = "/rails/storage"
+
+[[vm]]
+  memory = "1024mb"
+  cpu_kind = "shared"
+  cpus = 2
+```
+
+**Procfile for Fly.io:**
+
+```procfile
+web: bundle exec puma -C config/puma.rb
+ocr: bin/activestorage-ocr-server --host 127.0.0.1 --port 9292
+```
+
+**Important notes for Fly.io:**
+- Use `foreman` as the entrypoint to run both processes
+- The OCR server binds to `127.0.0.1` (internal only)
+- Set `ACTIVESTORAGE_OCR_SERVER_URL` env var to `http://127.0.0.1:9292`
+- For SQLite with volumes, run migrations in `docker-entrypoint` not `release_command`
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ACTIVESTORAGE_OCR_SERVER_URL` | `http://127.0.0.1:9292` | URL where the OCR server is running |
+| `ACTIVESTORAGE_OCR_TIMEOUT` | `30` | Request timeout in seconds |
+| `ACTIVESTORAGE_OCR_OPEN_TIMEOUT` | `5` | Connection timeout in seconds |
+
+### Troubleshooting
+
+**Binary not found:**
+```
+Error: bin/activestorage-ocr-server: No such file or directory
+```
+Solution: Run `rails generate activestorage_ocr:install` or `rails activestorage_ocr:install path=./bin/dist`
+
+**Connection refused:**
+```
+Faraday::ConnectionFailed: Connection refused
+```
+Solution: Ensure the OCR server is running and `ACTIVESTORAGE_OCR_SERVER_URL` is correctly configured.
+
+**Timeout errors:**
+```
+Faraday::TimeoutError
+```
+Solution: Increase timeout values in the initializer or reduce image/PDF sizes.
+
+**Health check:**
+```bash
+# Verify the OCR server is responding
+curl http://localhost:9292/health
+
+# Or via rake task
+bin/rails activestorage_ocr:health
+```
 
 ## Rake Tasks
 
 ```bash
 # Install the OCR server binary for your platform
-bundle exec rake activestorage_ocr:install
+bin/rails activestorage_ocr:install
 
-# Start the OCR server
-bundle exec rake activestorage_ocr:start
+# Start the OCR server (for manual testing)
+bin/rails activestorage_ocr:start
 
 # Check server health
-bundle exec rake activestorage_ocr:health
+bin/rails activestorage_ocr:health
 
 # Show binary info (platform, path, version)
-bundle exec rake activestorage_ocr:info
+bin/rails activestorage_ocr:info
 ```
 
 ## API Endpoints

data/lib/activestorage/ocr/binary.rb

@@ -120,11 +120,12 @@ module ActiveStorage
 
         # Downloads and installs the binary.
         #
-        # Downloads from GitHub releases and extracts to the gem's bin directory.
+        # Downloads from GitHub releases and extracts to the specified directory.
         #
         # ==== Parameters
         #
         # * +force+ - If true, reinstalls even if already installed
+        # * +path+ - Custom installation directory (defaults to gem's bin directory)
         #
         # ==== Returns
         #
@@ -133,8 +134,16 @@ module ActiveStorage
         # ==== Raises
         #
         # RuntimeError if the download fails.
-        def install!(force: false)
-          return binary_path if installed? && !force
+        def install!(force: false, path: nil)
+          target_dir = path || install_dir
+          target_path = File.join(target_dir, BINARY_NAME)
+
+          if !force && File.executable?(target_path)
+            puts "Binary already installed at #{target_path}"
+            return target_path
+          end
+
+          FileUtils.mkdir_p(target_dir)
 
           puts "Downloading activestorage-ocr-server for #{platform}..."
 
@@ -147,9 +156,9 @@ module ActiveStorage
                   "You may need to build from source: cd rust && cargo build --release"
           end
 
-          extract_binary(response.body)
-          puts "Installed to #{binary_path}"
-          binary_path
+          extract_binary(response.body, target_path)
+          puts "Installed to #{target_path}"
+          target_path
         end
 
         private
@@ -174,17 +183,17 @@ module ActiveStorage
         end
 
         # Extracts the binary from a gzipped tarball.
-        def extract_binary(tarball_data)
+        def extract_binary(tarball_data, target_path)
           gz = Zlib::GzipReader.new(StringIO.new(tarball_data))
           tar = Gem::Package::TarReader.new(gz)
 
           tar.each do |entry|
             next unless entry.file? && entry.full_name == BINARY_NAME
 
-            File.open(binary_path, "wb") do |f|
+            File.open(target_path, "wb") do |f|
               f.write(entry.read)
             end
-            File.chmod(0o755, binary_path)
+            File.chmod(0o755, target_path)
             return
           end
 

data/lib/activestorage/ocr/railtie.rb

@@ -16,21 +16,23 @@ module ActiveStorage
     #
     class Railtie < Rails::Railtie
       # Registers the OCR analyzer with Active Storage.
-      initializer "activestorage-ocr.add_analyzer" do
-        config.after_initialize do
-          # Prepend our analyzer so it runs before other analyzers
-          if defined?(ActiveStorage) && ActiveStorage.respond_to?(:analyzers)
-            ActiveStorage.analyzers.prepend(ActiveStorage::Ocr::Analyzer)
-          end
-        end
+      #
+      # We use an initializer that runs after Active Storage's engine is loaded
+      # to prepend our analyzer to the configuration's analyzers list.
+      # This ensures our analyzer runs before the default image analyzers.
+      initializer "activestorage-ocr.add_analyzer", after: "active_storage.configs" do |app|
+        # Prepend to the config's analyzers list, which ActiveStorage::Engine
+        # later copies to ActiveStorage.analyzers in its after_initialize
+        app.config.active_storage.analyzers.prepend(ActiveStorage::Ocr::Analyzer)
       end
 
       # Defines rake tasks for server management.
       rake_tasks do
         namespace :activestorage_ocr do
-          desc "Install the OCR server binary"
+          desc "Install the OCR server binary (optional: path=./bin/dist)"
           task :install do
-            ActiveStorage::Ocr::Binary.install!
+            path = ENV["path"]
+            ActiveStorage::Ocr::Binary.install!(path: path)
           end
 
           desc "Check OCR server health"
@@ -56,8 +58,9 @@ module ActiveStorage
             end
 
             config = ActiveStorage::Ocr.configuration
-            host = config.server_host.gsub(%r{https?://}, "")
-            port = config.server_port
+            uri = URI.parse(config.server_url)
+            host = uri.host || "127.0.0.1"
+            port = uri.port || 9292
 
             puts "Starting OCR server on #{host}:#{port}..."
             exec(binary, "--host", host, "--port", port.to_s)

data/lib/activestorage/ocr/version.rb

@@ -2,6 +2,6 @@
 
 module ActiveStorage
   module Ocr
-    VERSION = "0.1.0"
+    VERSION = "0.1.2"
   end
 end

data/lib/generators/activestorage_ocr/install/USAGE

@@ -0,0 +1,12 @@
+Description:
+    Installs the OCR server binary and creates a wrapper script.
+
+Example:
+    rails generate activestorage_ocr:install
+
+    This will create:
+        bin/activestorage-ocr-server - Wrapper script that runs the OCR server
+        bin/dist/activestorage-ocr-server - The actual binary (gitignored)
+
+    And update:
+        .gitignore - Adds /bin/dist/ to ignore the binary

data/lib/generators/activestorage_ocr/install/install_generator.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module ActivestorageOcr
+  module Generators
+    # Installs the OCR server binary and creates a binstub.
+    #
+    # This generator creates a bin/activestorage-ocr-server script that
+    # automatically downloads the binary if needed and runs it.
+    #
+    # == Usage
+    #
+    #   rails generate activestorage_ocr:install
+    #
+    # == What it does
+    #
+    # 1. Creates bin/activestorage-ocr-server (wrapper script)
+    # 2. Downloads binary to bin/dist/activestorage-ocr-server
+    # 3. Adds bin/dist/ to .gitignore
+    #
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Installs the OCR server binary and creates a binstub"
+
+      def create_binstub
+        template "bin/activestorage-ocr-server", "bin/activestorage-ocr-server"
+        chmod "bin/activestorage-ocr-server", 0o755
+      end
+
+      def update_gitignore
+        gitignore_path = Rails.root.join(".gitignore")
+        return unless File.exist?(gitignore_path)
+
+        gitignore_content = File.read(gitignore_path)
+        return if gitignore_content.include?("/bin/dist")
+
+        append_to_file ".gitignore", "\n# OCR server binary\n/bin/dist/\n"
+      end
+
+      def download_binary
+        say "Downloading OCR server binary...", :green
+        require "activestorage/ocr/binary"
+        dist_dir = Rails.root.join("bin", "dist")
+        ActiveStorage::Ocr::Binary.install!(path: dist_dir.to_s)
+      end
+
+      def show_instructions
+        say ""
+        say "OCR server installed successfully!", :green
+        say ""
+        say "Add to your Procfile:", :yellow
+        say "  ocr: bin/activestorage-ocr-server --host 127.0.0.1 --port 9292"
+        say ""
+        say "Configure the server URL in config/initializers/activestorage_ocr.rb:", :yellow
+        say "  ActiveStorage::Ocr.configure do |config|"
+        say "    config.server_url = ENV.fetch('ACTIVESTORAGE_OCR_SERVER_URL', 'http://127.0.0.1:9292')"
+        say "  end"
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/activestorage_ocr/install/templates/bin/activestorage-ocr-server

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+set -e
+
+# Navigate to app root
+cd "$(dirname "$0")/.."
+
+BINARY_PATH="./bin/dist/activestorage-ocr-server"
+
+# Download binary if not present
+if [ ! -f "$BINARY_PATH" ]; then
+  echo "OCR server binary not found. Downloading..."
+  ./bin/rails activestorage_ocr:install path=./bin/dist
+fi
+
+# Execute the binary with all passed arguments
+exec "$BINARY_PATH" "$@"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activestorage-ocr
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Michael Rispoli
@@ -112,6 +112,9 @@ files:
 - lib/activestorage/ocr/railtie.rb
 - lib/activestorage/ocr/result.rb
 - lib/activestorage/ocr/version.rb
+- lib/generators/activestorage_ocr/install/USAGE
+- lib/generators/activestorage_ocr/install/install_generator.rb
+- lib/generators/activestorage_ocr/install/templates/bin/activestorage-ocr-server
 homepage: https://github.com/Cause-of-a-Kind/activestorage-ocr
 licenses:
 - MIT