Dockerfile for ChupaText

Install

You can use ChupaText with Docker or Podman.

Common setup

Install Git

For Debian or Ubuntu:

$ sudo -H apt install -y -V git

For RHEL variants:

$ sudo -H dnf install -y git

Clone this repository

$ sudo -H git clone https://github.com/ranguba/chupa-text-docker.git /var/lib/chupa-text

Create log directories

$ sudo -H mkdir -p \
    /var/log/chupa-text/proxy \
    /var/log/chupa-text/rails

Install logrotate configuration

$ sudo -H ln -fs \
    /var/lib/chupa-text/etc/logrotate.d/chupa-text \
                       /etc/logrotate.d/chupa-text

With Docker

Install Docker

Install Docker by following the official documentation:

https://docs.docker.com/engine/install/

Pull Docker images

$ cd /var/lib/chupa-text
$ sudo -H docker compose pull

Change subnet (optional)

If you want to change subnet for internal network from 172.19.0.0/24, copy .env.example to .env and change the content:

$ cd /var/lib/chupa-text
$ sudo -H cp -a .env{.example,}
$ sudo -H editor .env

Install systemd service file

$ sudo -H ln -fs \
    /var/lib/chupa-text/usr/lib/systemd/system/chupa-text.service \
                       /usr/lib/systemd/system/chupa-text.service
$ sudo -H systemctl daemon-reload
$ sudo -H systemctl enable --now chupa-text

With Podman

Install Podman

Install Podman 4.6 or later by following the official documentation:

https://podman.io/docs/installation

Pull container images

$ sudo -H podman image pull ghcr.io/ranguba/chupa-text-docker:proxy
$ sudo -H podman image pull ghcr.io/ranguba/chupa-text-docker:ubuntu-latest

Install Quadlet files

$ sudo -H mkdir -p /etc/containers/systemd
$ sudo -H ln -fs \
    /var/lib/chupa-text/etc/containers/systemd/chupa-text.network \
    /var/lib/chupa-text/etc/containers/systemd/chupa-text-proxy.container \
    /var/lib/chupa-text/etc/containers/systemd/chupa-text.container \
    /etc/containers/systemd/
$ sudo -H systemctl daemon-reload
$ sudo -H systemctl start chupa-text

Services generated by Quadlet can't be enabled by systemctl enable. They are started automatically at boot because the Quadlet files have WantedBy=multi-user.target.

Change configuration (optional)

If you want to change the image or the subnet for internal network, copy sample drop-in files to /etc/containers/systemd/ and change the content. Drop-in files require Podman 5.x or later.

Here are the sample drop-in files in /var/lib/chupa-text/etc/containers/systemd/:

• chupa-text.container.d/image.conf
  • The image for ChupaText.
  • You can use Debian instead of Ubuntu.
• chupa-text-proxy.container.d/image.conf
  • The image for proxy.
• chupa-text.network.d/subnet.conf
  • The subnet for internal network.
  • The default is 172.19.0.0/24.

For example, use the following to use Debian instead of Ubuntu:

$ sudo -H mkdir -p /etc/containers/systemd/chupa-text.container.d
$ sudo -H cp \
    /var/lib/chupa-text/etc/containers/systemd/chupa-text.container.d/image.conf \
    /etc/containers/systemd/chupa-text.container.d/
$ sudo -H editor /etc/containers/systemd/chupa-text.container.d/image.conf

If you change drop-in files after ChupaText is started, run the following to apply them:

$ sudo -H systemctl daemon-reload
$ sudo -H systemctl restart chupa-text

Usage

You can use ChupaText via HTTP or command line.

http://localhost:20080/ provides form to text extraction. You can use this style by your Web browser.

http://localhost:20080/extraction.json is Web API endpoint with the following specification:

• HTTP Method: POST

• Content-Type: multipart/form-data

• Parameters:

  You must to specify at least data or uri. You can specify both data and uri. In the case, uri is used as additional information.

  • data: Data to be extracted. If content-type is specified, it's helpful because ChupaText doesn't need to guess content-type. If ChupaText guesses content-type, ChupaText may detect wrong content-type.

  • uri: URI to be extracted.

Here is a curl command line to extract local PDF file at /tmp/sample.pdf. You can use --form option to use multipart/form-data. data=@PATH means that parameter name is data and parameter value is content of PATH. ;type=application/pdf specifies content-type of the data value:

$ curl \
    --form 'data=@/tmp/sample.pdf;type=application/pdf' \
    http://localhost:20080/extraction.json

This Web API returns the following JSON:

{
  "mime-type": "application/pdf",
  "uri": "file:/home/chupa-text/chupa-text-http-server/sample.pdf",
  "path": "/tmp/sample-36-1ywy0xf.pdf",
  "size": 147159,
  "texts": [
    {
      "mime-type": "text/plain",
      "uri": "file:/home/chupa-text/chupa-text-http-server/sample.txt",
      "path": "/home/chupa-text/chupa-text-http-server/sample.txt",
      "size": 1012,
      "title": "",
      "created_time": "2015-01-22T15:54:11.000Z",
      "source-mime-types": [
        "application/pdf"
      ],
      "creator": "Adobe Illustrator CS3",
      "producer": "Adobe PDF library 8.00",
      "body": "This is sample PDF. ...",
      "screenshot": {
        "mime-type": "image/png",
        "data": "iVBORw...",
        "encoding": "base64"
      }
    }
  ]
}

In most cases, you're interested in texts values. They include extracted text in body and screenshot in screenshot. Screenshot has the following keys:

• mime-type: The MIME type of the data. Normally, this is image/png.

• data: The image data encoded by encoding.

• encoding: This is optional. If data is encoded by base64, this value is "base64". If data isn't encoded, this key doesn't exist. ChupaText needs binary data but JSON doesn't support binary data because JSON is a text format. If data is text data such as SVG, this key doesn't exist.

You can use ChupaText as command line tool by the following command line:

% sudo /usr/bin/docker compose \
    --file /var/lib/chupa-text/compose.yaml \
    exec chupa-text \
      xvfb-run -a chupa-text /tmp/sample.pdf

If your user is a member of docker group, you can omit sudo like the following:

$ /usr/bin/docker compose \
    --file /var/lib/chupa-text/compose.yaml \
    exec chupa-text \
      xvfb-run -a chupa-text /tmp/sample.pdf

If you use Podman, use the following command line:

$ sudo -H podman container exec chupa-text \
    xvfb-run -a chupa-text /tmp/sample.pdf

Command line interface uses the same JSON format as Web API.

Author

• Sutou Kouhei <kou@clear-code.com>

License

LGPL 2.1 or later.

(Sutou Kouhei has a right to change the license including contributed patches.)