# rusticdoc

> rusticdoc is a self-hosted document service written in Rust, at version 0.1.4. It fills Office (.docx, .xlsx, .pptx, .odt, .ods, .odp), text, HTML and PDF form templates from JSON, converts the result with LibreOffice or Fulgur, and finishes it with PDF operations, in one multipart HTTP request or from the `rusticdoc` CLI.

Things to know before writing templates or calls:

- Templates use a Jinja-style syntax evaluated by minijinja: `{{ customer.name }}`, `{% for %}`, `{% if %}` and filters. It is not Carbone's `{d.field}` or docxtemplater's `{#items}` syntax.
- A missing value stops the render with an error instead of printing nothing. `POST /v1/templates/validate` lists every problem in a template against sample data.
- `image` takes base64 or a data URL and never fetches a URL. HTML is laid out by Fulgur with no browser, no JavaScript and no network.
- There is no hosted service: every call goes to the reader's own deployment, usually on port 9027, with an `X-Api-Key` header when credentials are configured.
- Agent skills for writing templates and calling the API are in the repository's `skills/` folder: https://github.com/crafted-systems/rusticdoc/tree/main/skills

## Start here

- [Quickstart](https://rusticdoc.com/docs/start/quickstart/): Start the service, send it a Word template and some JSON, and get a filled invoice back as a PDF.
- [Install](https://rusticdoc.com/docs/start/install/): Run rusticdoc from the image, with Compose or from source, and use its CLI.
- [Concepts](https://rusticdoc.com/docs/start/concepts/): How a request moves through the template, data, steps and engines, and what the service keeps.

## Write templates

- [Template syntax](https://rusticdoc.com/docs/templates/syntax/): How to write tags, loops, conditions and expressions, what a missing value does, and how each format escapes values.
- [Conditions](https://rusticdoc.com/docs/templates/conditions/): Show, hide or choose text with inline conditions, if blocks, elif chains, tests and membership checks, in every kind of template.
- [Calculations](https://rusticdoc.com/docs/templates/calculations/): Do arithmetic, totals, averages, counts, per-group totals, running balances, lookups and date arithmetic inside a template.
- [Filters](https://rusticdoc.com/docs/templates/filters/): Format numbers, money and dates, translate labels, and transform values with every filter a template can use.
- [Rich content](https://rusticdoc.com/docs/templates/rich-content/): Put images, barcodes, links, coloured text, HTML, charts and page breaks into Office templates.
- [Office formats](https://rusticdoc.com/docs/templates/office/): Where to put loops and conditions in DOCX, ODT, XLSX, ODS, PPTX and ODP templates, and what each format supports.
- [PDF templates](https://rusticdoc.com/docs/templates/pdf-templates/): Fill PDF form fields from JSON, use tags in fields and annotations, flatten the result, and overlay one PDF on another.
- [Translations and settings](https://rusticdoc.com/docs/templates/translations/): Set a template's language, translated labels, time zone and default currency, per template or per request, and keep translations in dictionaries.
- [Validate a template](https://rusticdoc.com/docs/templates/validate/): Check a template against sample data and get a list of every problem and where it is, without producing a file.
- [Batch rendering](https://rusticdoc.com/docs/templates/batch/): Render one template once per element of an array in your data, and get the files back in a ZIP.

## Use the API

- [The render pipeline](https://rusticdoc.com/docs/guides/pipeline/): Fill a template from JSON and run conversion and PDF steps in one request to /v1/render.
- [Convert documents](https://rusticdoc.com/docs/guides/convert/): Convert one or more uploaded documents with LibreOffice, or HTML with Fulgur, and merge or finish the result with PDF options.
- [HTML to PDF](https://rusticdoc.com/docs/guides/html/): Turn HTML and CSS you write for print into PDF with Fulgur, a layout engine with no browser and no network access.
- [PDF operations](https://rusticdoc.com/docs/guides/pdf-operations/): Merge, split, rotate, mark, sign with an image or a certificate, secure, describe and fill PDFs through the /v1/pdf routes.
- [Stored templates](https://rusticdoc.com/docs/guides/stored-templates/): Upload a template once, then render it by id or alias, roll versions forward and back, list the data it reads and preview it as a PNG.
- [Fonts](https://rusticdoc.com/docs/guides/fonts/): Add fonts by uploading them, mounting them or sending them with one request, and check which fonts a document used.
- [Background jobs](https://rusticdoc.com/docs/guides/background-jobs/): Run a request as a background job, poll it until it finishes, and download the result from any replica.
- [Webhooks](https://rusticdoc.com/docs/guides/webhooks/): Get results by HTTP callback instead of holding a request open, and verify that a delivery came from your service.
- [Authentication](https://rusticdoc.com/docs/guides/authentication/): Turn on API keys, tenant keys, basic auth or OpenID Connect, choose who is an admin, and see which routes stay open.

## Run it

- [Docker](https://rusticdoc.com/docs/operate/docker/): Run one rusticdoc container that other people can use, with credentials, limits, fonts, health checks and upgrades.
- [Many containers](https://rusticdoc.com/docs/operate/many-containers/): Run several rusticdoc replicas on one store, and see what happens when the store fails.
- [Kubernetes](https://rusticdoc.com/docs/operate/kubernetes/): What the manifest in deploy/kubernetes.yaml sets up, and what to change before you apply it to your cluster.
- [Sizing](https://rusticdoc.com/docs/operate/sizing/): Work out how many workers and how much memory a rusticdoc container needs.
- [Security](https://rusticdoc.com/docs/operate/security/): What to set up around rusticdoc, what to do where tenants don't trust each other, and how to check the image you run.
- [Observability](https://rusticdoc.com/docs/operate/observability/): Follow a request through rusticdoc's logs, metrics, health routes and request ids.

## Use with AI

- [Agent skills](https://rusticdoc.com/docs/ai/skills/): Install the rusticdoc skills so AI assistants write correct templates, check them and render documents, in Claude Code, Codex, Cursor, Copilot, Gemini CLI, claude.ai and ChatGPT.

## Reference

- [CLI](https://rusticdoc.com/docs/reference/cli/): Every rusticdoc command and option, from the binary's own help.
- [Configuration](https://rusticdoc.com/docs/reference/configuration/): Every environment variable rusticdoc reads, with its default and purpose.
- [Errors](https://rusticdoc.com/docs/reference/errors/): Every error status and code, the JSON body, and what to do about each.

## Project

- [Security overview](https://rusticdoc.com/docs/project/security-overview/): How rusticdoc handles hostile documents, and where its protection stops.
- [Known limits](https://rusticdoc.com/docs/project/known-limits/): What rusticdoc doesn't do, and what could surprise you.
- [Changelog](https://rusticdoc.com/docs/project/changelog/): What each rusticdoc release contains.
- [SDKs](https://rusticdoc.com/docs/project/sdks/): The state of rusticdoc's generated client libraries, and how to call it with plain HTTP today.
- [Licence](https://rusticdoc.com/docs/project/license/): rusticdoc's licence and the licences of what it ships with.

## Optional

- [Every page in one file](https://rusticdoc.com/llms-full.txt): the documentation above as one Markdown file
- [OpenAPI description](https://rusticdoc.com/openapi.json): every endpoint, field and response of the HTTP API