The AI Document add-on for formio/uag, the Form.io UAG. Runs beside it; not the UAG.
790
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.
| Plugin | What it does |
|---|---|
module:ai-document | The AI Document component (uagdocument), served in uag.use.js and the portal script, its process route, and the document plugin type. |
document:extract | The parts of the documents the instructions ask for, in their exact wording, checked against the documents' text. |
document:analyze | Content about the documents: summaries, assessments, comparisons. |
document:translate | The documents in the language the form designer picks, keeping their structure. |
converter:office-text | Word 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.
The tags follow @formio/uag-extras, whose major version is the UAG's:
| Tag | For |
|---|---|
latest, 2, 2.x.y | formio/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.0 | The 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.
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.
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.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.UAG_ENGINES (claude, openai, grok or gemini) with its key, such as CLAUDE_API_KEY.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.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.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.MODULES_DISABLED=ai-document turns off the module; PLUGINS_DISABLED=document:translate turns off a plugin.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.
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.
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.
@formio/uag-extras). The image also holds the office-text converter's libraries (mammoth, node-html-markdown, exceljs), under their own licenses.Content type
Image
Digest
sha256:71c7a599a…
Size
12.3 MB
Last updated
about 3 hours ago
docker pull formio/uag-documentsPulls:
197
Last week