Sign inSign up
uag-documents logo

formio/uag-documents

Verified Publisher

By Form.io

•Updated about 3 hours ago

The AI Document add-on for formio/uag, the Form.io UAG. Runs beside it; not the UAG.

Image
0

790

formio/uag-documents repository overview

⁠formio/uag-documents

The AI Document add-on for the Form.io Universal Agent Gateway⁠ (formio/uag). AI Document is a form component that turns uploaded files and a form designer's instructions into AI-generated content: exact extractions checked against the documents' text, summaries and assessments, and translations.

This image is not the UAG. It runs beside formio/uag: at each start, it copies a plugins folder into a volume and exits. The UAG mounts that volume and loads it.

PluginWhat it does
module:ai-documentThe AI Document component (uagdocument), served in uag.use.js and the portal script, its process route, and the document plugin type.
document:extractThe parts of the documents the instructions ask for, in their exact wording, checked against the documents' text.
document:analyzeContent about the documents: summaries, assessments, comparisons.
document:translateThe documents in the language the form designer picks, keeping their structure.
converter:office-textWord files as Markdown, Excel files as CSV.

The UAG's built-in converters (PDF text, text files, images as PDF) work beside these. All of them come from @formio/uag-extras⁠.

⁠Tags

The tags follow @formio/uag-extras, whose major version is the UAG's:

TagFor
latest, 2, 2.x.yformio/uag 2.x (2.0.0 or later). :2 moves to each 2.x release, and :latest to the newest release, so formio/uag:latest and formio/uag-documents:latest are a pair. Pin 2.x.y to upgrade when you choose.
1, 1.0.0The formio/uag 2.0.0 release candidates only. Not updated.

Minor and patch versions are the add-on's own and do not follow the UAG's. Images are built for linux/amd64 and linux/arm64. Each image is tested against the formio/uag release it requires (its io.form.uag.requires label) before it is pushed.

⁠Deploy it

The deployment kit is a Compose file and an .env template that run formio/uag with this add-on, and optionally MongoDB. It ships in the @formio/uag-extras package, and jsDelivr serves it. You need Docker Engine with Compose 2.24 or later.

mkdir formio-uag && cd formio-uag
curl -fsSLO https://cdn.jsdelivr.net/npm/@formio/uag-extras@2/deploy/docker-compose.yml
curl -fsSL -o .env https://cdn.jsdelivr.net/npm/@formio/uag-extras@2/deploy/.env.example
chmod 600 .env
# fill in .env (it explains each setting), then:
docker compose pull && docker compose up -d
docker compose ps        # formio-uag: running (healthy); uag-documents: exited (0)

@2 is the newest 2.x. Name an exact version, such as @formio/[email protected], to get a known kit. The kit's full guide is deploy/README.md in the same package.

  • What runs. uag-documents copies its files into a volume and exits. Then formio-uag (formio/uag:latest) starts, loads them from /app/plugins/documents and logs Plugins and modules loaded from /app/plugins/documents/index.mjs. Compose refuses to start without a .env, PROJECT or JWT_SECRET.
  • The project. PROJECT is the project's API endpoint. On Form.io's hosted service (https://myproject.form.io) or self-hosted Enterprise, the credential is a project API key in PROJECT_KEY. Self-hosted Enterprise also needs a LICENSE_KEY that includes the UAG. On Open Source, the credential is ADMIN_KEY.
  • Engines. AI Document needs an agent engine in UAG_ENGINES (claude, openai, grok or gemini) with its key, such as CLAUDE_API_KEY.
  • TLS. The UAG serves plain HTTP. The kit publishes it on 127.0.0.1:3200, for a reverse proxy on the same host; PUBLISH=3200 opens it to a load balancer elsewhere. Set TRUST_PROXY to the number of proxies, and CORS to your applications' origins. Responses stream, so turn off proxy buffering.
  • Database (optional). COMPOSE_PROFILES=database and MONGO=mongodb://mongo:27017 start MongoDB 7 for run records and remote MCP sign-in. This needs a license that includes the UAG. MongoDB 8 refuses to start on Linux kernels 6.19.0 through 7.0.13, which current Docker Desktop releases run.
  • Upgrade. docker compose pull && docker compose up -d. The kit runs latest of both images, so this brings the newest UAG and the newest add-on, which replaces its volume's contents, and Compose restarts the UAG on them. Pin both in .env (IMAGE_UAG, IMAGE_UAG_DOCUMENTS) to upgrade when you choose. A UAG release needs no add-on release: formio/uag-documents:2 works with every formio/uag 2.x.
  • Turn parts off. MODULES_DISABLED=ai-document turns off the module; PLUGINS_DISABLED=document:translate turns off a plugin.
⁠The minimum
services:
  uag-documents:
    image: formio/uag-documents:latest
    volumes:
      - uag-documents:/out

  formio-uag:
    image: formio/uag:latest
    depends_on:
      uag-documents:
        condition: service_completed_successfully
        restart: true
    volumes:
      - uag-documents:/app/plugins/documents:ro
    env_file: .env    # PROJECT, PROJECT_KEY or ADMIN_KEY, JWT_SECRET, UAG_ENGINES and the engine's key

volumes:
  uag-documents:

Leave the add-on service without a restart policy: it runs once at each up and exits.

Without Compose:

docker volume create uag-documents
docker run --rm -v uag-documents:/out formio/uag-documents:latest
docker run -d -p 3200:3200 --env-file .env -v uag-documents:/app/plugins/documents:ro formio/uag:latest

On Kubernetes, run the add-on as an init container that writes to an emptyDir at /out, and mount that emptyDir read-only at /app/plugins/documents in the UAG's container.

⁠Your own plugins

Each add-on, and each plugins folder of your own, goes in a folder of its own under /app/plugins, so they run side by side:

  formio-uag:
    volumes:
      - uag-documents:/app/plugins/documents:ro
      - ./my-plugins:/app/plugins/my-plugins:ro

my-plugins/index.mjs is an ES module whose default export lists your plugins. A document plugin uses the document plugin type that this add-on's module defines, so you do not list the module again. A plugin's npm dependencies go in its folder's node_modules; @formio/uag and zod resolve to the UAG's.

To ship your plugins as an add-on, use an image whose command copies them to /out:

FROM alpine:3
COPY my-plugins /plugins
CMD ["sh", "-c", "find /out -mindepth 1 -delete && cp -a /plugins/. /out/"]

A plugin that needs system packages (an OCR engine) runs in the UAG's process, so build your own image FROM formio/uag:<version> with them installed. The Plugins⁠ page covers writing plugins and add-ons.

⁠Trust

Plugins are trusted code. They run in the UAG's process, with its secrets: engine API keys, the project or admin key, the JWT secret. Every add-on and every plugins folder you mount installs software, so add only those you trust. Keep .env out of version control.

Tag summary

Content type

Image

Digest

sha256:71c7a599a…

Size

12.3 MB

Last updated

about 3 hours ago

docker pull formio/uag-documents

This week's pulls

Pulls:

197

Last week