Self-Hosting OS-APS
Hosted demo
We operate a reference instance at os-aps.sciflow.net that always tracks the latest stable container images.
A development build is available at os-aps-next.sciflow.net. Use it to preview upcoming changes; it may be unstable.
Intended audience
This guide targets technical university IT and library teams who want to operate their own instance of the editor. If you are an author or publisher looking for a hosted solution, visit sciflow.net instead. We are also working on a hosting service for OS-APS - stay tuned.
Questions are welcome in the #development channel on Slack.
Recommended deployment in brief
- Keep your export templates in a repository on your institutional Git service, starting from the templates that ship with OS-APS.
- Mount a dedicated, read-only font volume and point
FONT_PATHto it so your exports use your university's typography. - Store manuscripts and uploads in an S3 bucket with versioning and automated backups instead of relying solely on a Docker volume.
- Run the application through Docker Compose (or your orchestrator of choice) behind a reverse proxy that terminates TLS for your institutional domain.
- Restrict who can reach the editor at the reverse proxy or through a VPN. The editor has no login of its own.
This guide assumes you are part of a university IT or library team and are comfortable operating Linux servers, Docker, Git, and S3-compatible storage.
Quick start – local evaluation
Need a quick look at OS-APS before investing in the full setup? You can run a self-contained demo in a few minutes. The container ships with the default export templates and downloads required open-source fonts on first start, so no additional assets are needed.
On Windows, Docker Desktop may ask you to sign in or to grant administrator rights the first time it runs. That prompt comes from Docker, not from OS-APS.
mkdir osaps-demo && cd osaps-demo
docker run \
--rm \
-p 127.0.0.1:3000:3000 \
--name os-aps-demo \
-v "$(pwd):/data" \
-e LOCAL_STORAGE_PATH=/data/manuscripts \
-e INSTANCE_TITLE="OS-APS Demo" \
registry.gitlab.com/sciflow/development/server:latest
- Using PowerShell instead of a Unix shell? Replace
$(pwd)with${PWD}and either place the command on one line or use backticks (\) for line continuations. - Browse to http://localhost:3000. The editor opens directly, without a login.
- Press
Ctrl+Cto stop the container. Your manuscripts and configuration stay in theosaps-demodirectory so you can restart later. - Optional: add
-e FONT_PATH=/data/fontsand drop fonts into./fontsif you want to test custom typography, or run the image transformation sidecar for WMF/EMF support.
What's bundled in the image
The published server image is built on node:22-alpine3.20-pandoc3.9 and includes Pandoc 3.9 + PrinceXML 16 for PDF export. The file-transform-sidecar image (when you run it) adds LibreOffice 26.2.2 to convert EMF/WMF/PDF images. The Node.js runtime version, Pandoc availability, and the commit SHA the image was built from are all visible on the /status operator dashboard once the container is running.
Building from source? Pass --build-arg CI_COMMIT_SHA=$(git rev-parse HEAD) to docker build so /status can show the exact commit your image was produced from — without it the dashboard falls back to git rev-parse HEAD at runtime, which is only meaningful when the container has access to the source checkout.
Once you are ready to go beyond local testing, proceed with the production-oriented steps below.
Production
The editor has no login
OS-APS has no user accounts. Anyone who can reach the instance can open, edit and export every document on it. Protect access at your reverse proxy (for example with your institutional single sign-on or HTTP authentication) or keep the instance inside a VPN. Only the /status dashboard and its API have their own protection: HTTP Basic auth through STATUS_PASSWORD.
Prerequisites
- A Linux host (or VM) with Docker Engine 24+ and the Docker Compose plugin installed.
- Read access to the OS-APS source repository at gitlab.com/sciflow/development. It is public, so anonymous access is enough.
- An institutional Git service (GitLab, Gitea, GitHub Enterprise, …) where you can host your customized template repository.
- An S3-compatible endpoint (AWS S3, MinIO, or on-prem object storage) where you can create buckets with versioning and lifecycle policies.
- DNS control for the domain you want to publish (e.g.
aps.university.edu) and an option to obtain TLS certificates. - Optional: network access to logging or monitoring stacks if you plan to integrate them after the base install.
Step 1 – Prepare your template repository
The templates that ship with every instance live in the templates/ folder of the source code. Start your own template repository from a copy of that folder and keep it on your institutional Git platform.
Your templates replace the built-in ones
When TEMPLATE_SOURCE points at your template volume, the server lists only the template directories it finds there. The built-in templates are no longer offered. Keep a copy of every built-in template you still want in your repository.
- Create an empty project in your institutional Git service, for example
git@git.university.edu:press/os-aps-templates.git. - On an administration workstation, copy the shipped templates into it:
git clone --depth 1 https://gitlab.com/sciflow/development.git osaps-source
git clone git@git.university.edu:press/os-aps-templates.git
cp -R osaps-source/templates/. os-aps-templates/
cd os-aps-templates
git add .
git commit -m "Start from the OS-APS templates"
git push
_ or . are skipped.
4. When you update OS-APS, compare the templates/ folder of the new release with your repository and take over the changes you want.
Automate template sync
Run git-sync from a scheduled job or as a sidecar to keep your volume current. Example for a one-shot sync into a named Docker volume:
docker volume create osaps-templates
docker run --rm \
-v osaps-templates:/git \
registry.k8s.io/git-sync/git-sync:v4.1.0 \
--repo=git@git.university.edu:press/os-aps-templates.git \
--branch=main \
--root=/git \
--link=. \
--one-time
Adjust the repository URL to your internal mirror. Use SSH keys or tokens that provide read-only access.
Once the volume is ready, the application can mount it read-only and expose the templates via TEMPLATE_SOURCE=/templates.
Step 2 – Prepare font assets
Document exports look best if they use the same fonts as your institutional publications.
- Collect the font files (OTF or TTF) that you have the right to distribute.
- Store them in a dedicated directory or Docker volume so they can be mounted read-only into the container.
- Point
FONT_PATHat that mount (e.g./fonts).
Example initialization:
docker volume create osaps-fonts
# Copy your font files into the volume (replace /mnt/fonts with your source)
docker run --rm -v osaps-fonts:/fonts -v /mnt/fonts:/source busybox cp /source/*.ttf /fonts/
By separating fonts into their own volume you can keep licensing under control and audit which font versions are in use.
Step 3 – Configure durable storage
We strongly recommend storing manuscripts and uploads in S3-compatible object storage with versioning and backup policies. This protects research output against operator error and ransomware and simplifies scaling across hosts.
- Create a bucket dedicated to OS-APS (for example
os-aps-manuscripts). - Enable versioning on the bucket. With AWS you can run:
aws s3api put-bucket-versioning \
--bucket os-aps-manuscripts \
--versioning-configuration Status=Enabled
cat <<'JSON' > lifecycle.json
{
"Rules": [
{
"ID": "Archive old versions",
"Status": "Enabled",
"Filter": {"Prefix": ""},
"NoncurrentVersionTransition": {"NoncurrentDays": 30, "StorageClass": "GLACIER"},
"NoncurrentVersionExpiration": {"NoncurrentDays": 365}
}
]
}
JSON
aws s3api put-bucket-lifecycle-configuration \
--bucket os-aps-manuscripts \
--lifecycle-configuration file://lifecycle.json
CreateBucket and PutBucketVersioning on the bucket, and falls back to GetBucketVersioning if those are refused. Allow at least GetBucketVersioning: if none of these calls succeeds, the server logs Fatal error: Could not access S3 and shuts down.
If you cannot use S3, set LOCAL_STORAGE_PATH to a directory on a persistent volume (for example /var/opt/osaps/manuscripts) and back it up with your existing tooling, but note that you lose automatic versioning. With LOCAL_STORAGE_PATH set, the server stores everything on that disk and ignores the S3_* settings.
Prefixes the server writes inside the bucket
Once running, OS-APS uses these prefixes alongside your manuscripts. They are operational data, not user content:
_queue/jobs/<id>.json— durable descriptor for each AI analysis job. Survives process restarts so an interrupted job is re-queued on startup. A job descriptor is deleted as soon as the job finishes (success or terminal failure)._status/transactions/<id>.json— per-import + per-AI sidecar with timings, logs, and the server context at the time of the run. Powers the/status/<transactionId>detail page.<project>/<doc>.timings.json— per-document AI analysis timing sidecar.<project>/.analysis/<doc>.analysis-lock.json— small lock file the queue uses to mark a doc as queued/running/done/error.
These prefixes are small (a few KB per record) but grow with workload. Include them in any lifecycle rule that targets the whole bucket. The _queue/jobs/ prefix is self-cleaning; _status/transactions/ accumulates one record per import or analysis and is the right candidate for a noncurrent-version expiry rule.
Step 4 – Define the application stack
The following Docker Compose file demonstrates a production-friendly layout: manuscripts in S3, separate read-only volumes for templates and fonts, and the image transformation sidecar as a second service.
services:
osaps:
image: registry.gitlab.com/sciflow/development/server:latest
container_name: os-aps
restart: always
ports:
- "127.0.0.1:3000:3000"
environment:
INSTANCE_TITLE: "University Press"
INSTANCE_URL: "https://aps.university.edu"
LOG_LEVEL: info
TEMPLATE_SOURCE: /templates
FONT_PATH: /fonts
# Do not set LOCAL_STORAGE_PATH here: it switches storage to the local
# disk and the S3 settings below are then ignored.
S3_ENDPOINT: "https://s3.example.edu"
S3_REGION: "eu-central-1"
S3_ACCESS_KEY: "${OSAPS_S3_ACCESS_KEY}"
S3_SECRET_KEY: "${OSAPS_S3_SECRET_KEY}"
S3_IMPORTER_BUCKET: "os-aps-manuscripts"
# EMF/WMF image conversion through the sidecar service below. Remove
# this line and the transform service if you do not need it.
TRANSFORM_IMAGE_URL: "http://transform:3001"
# Optional: enable AI-assisted import (see AI-assisted import section below)
# OPENAI_API_KEY: "${OPENAI_API_KEY}"
# Set together with the key: without it, structure recognition on long
# manuscripts comes back incomplete (see AI-assisted import below).
# OPENAI_REASONING_EFFORT: "medium"
# Optional: gate the /status dashboard and its API behind HTTP Basic auth.
# Leave unset on private networks; set to a random string on anything
# reachable from the public internet. /healthz, /readiness, /metrics and
# /api/status/jobs stay open.
# STATUS_PASSWORD: "${OSAPS_STATUS_PASSWORD}"
# Optional: tune the in-process AI analysis queue. Defaults are 2 and 2.
# Raise concurrency on hosts with spare RAM + CPU; lower it if you see
# OpenAI rate-limit cascades or event-loop p99 spikes on /status.
# ANALYSIS_QUEUE_CONCURRENCY: "2"
# ANALYSIS_QUEUE_MAX_ATTEMPTS: "2"
# Optional: cap plain imports. Default is 15 minutes.
# IMPORT_TIMEOUT_MS: "900000"
volumes:
- osaps-templates:/templates:ro
- osaps-fonts:/fonts:ro
depends_on:
- transform
transform:
image: registry.gitlab.com/sciflow/development/file-transform-sidecar:latest
restart: always
# No published port: the server reaches it on the Compose network.
volumes:
osaps-templates:
external: true
osaps-fonts:
external: true
Save the file as docker-compose.yml. Store sensitive values such as OSAPS_S3_ACCESS_KEY and OSAPS_S3_SECRET_KEY in an .env file next to it (the Compose plugin loads it automatically and fills in the ${…} references).
Environment variables of note
INSTANCE_TITLE: Label displayed in the UI header.INSTANCE_URL: Public base URL (defaulthttp://localhost:3000). Export assets such as template logos are loaded from it, and it is allowed in the content security policy. Set it once your reverse proxy is ready.PORT: Port the server listens on inside the container (default3000).LOG_LEVEL: Log verbosity (defaultinfo;debugfor troubleshooting).LOCAL_STORAGE_PATH: Switches storage to the local disk. When set to a non-empty path, the server keeps all manuscripts, uploads and operational data in that directory and ignores theS3_*settings. The quick start uses this mode. Leave it unset when you use S3.TEMPLATE_SOURCE: Path inside the container that points to your template volume. The image defaults to its built-in templates; setting it replaces them (see Step 1).FONT_PATH: Directory with the mounted fonts.FONT_URL_PREFIX: Optional. URL path under which the server serves the fonts fromFONT_PATHto exports (default/export/fonts/).S3_*: Connection details for your object storage. The server readsS3_ENDPOINT,S3_IMPORTER_BUCKET(required — there is no default),S3_ACCESS_KEY,S3_SECRET_KEY, andS3_REGION(falls back toAWS_REGION, thenus-east-1). Path-style addressing is always used, so MinIO works without an extra flag. Leave the whole block unset only for evaluation deployments that rely on local storage.ALLOW_UNAUTHORIZED_TLS: Optional. Set totrueto skip TLS certificate verification on the S3 endpoint — useful only for MinIO or in-cluster object storage with a self-signed cert. Do not set it against AWS or any public endpoint.ALLOWED_ORIGINS: Optional. Comma-separated list of origins allowed to call the server from a browser (CORS). Entries are origin prefixes such ashttps://press.university.edu, wildcards such as*.university.edu, orALL_ORIGINS. Entries starting withhttpare also allowed to embed the editor in a frame. Unset, only same-origin pages can use it.TRANSFORM_IMAGE_URL: Optional URL of the image transformation sidecar, which converts EMF/WMF images during import.OPENAI_API_KEY: Optional. Enables AI-assisted import features. When set, conversions go through the in-process queue (default 2 in parallel, retries on transient 429/5xx with exponential backoff). See AI-assisted import for setup steps and Tuning the AI queue for sizing.OPENAI_REASONING_EFFORT: Set tomediumwheneverOPENAI_API_KEYis set. Acceptsnone,low,mediumorhigh; unset, the model uses no reasoning and structure recognition on long manuscripts silently comes back incomplete. Single steps can be overridden, see Reasoning effort per step.OPENAI_MODEL: Optional. The OpenAI model used for every AI step (defaultgpt-5.4-mini).OPENAI_MAX_INPUT_TOKENS: Optional. Largest request the import sends to the model, in tokens (default250000). A manuscript above it fails early with a clear message instead of at the API. Raise it only for a model that accepts larger inputs.PRINCE_LICENSE_PATH: Optional path to a PrinceXML 16 license file inside the container (the image ships with PrinceXML 16 for PDF export). Unlicensed copies emit a watermark; provide aprince-license.datfrom PrinceXML to silence it.STATUS_PASSWORD: Optional. When set, gates the/statusdashboard and its API (/api/status/dashboard,/api/status/transaction/<id>) behind HTTP Basic auth (any username, this string as the password). Leave unset on private networks; set on any deployment reachable from the public internet./healthz,/readiness,/metricsremain open so k8s liveness/readiness probes and Prometheus scrapers keep working./api/status/jobsalso stays open, because the editor itself polls it; it returns only aggregate queue counts. This password protects the dashboard only, not the editor.ANALYSIS_QUEUE_CONCURRENCY: Optional. Max concurrent AI analyses (default 2). See Monitoring with /status for tuning advice.ANALYSIS_QUEUE_MAX_ATTEMPTS: Optional. Maximum retries for retryable provider errors (default 2). The slot is held during exponential backoff so a transient rate limit does not let other jobs jump ahead.IMPORT_TIMEOUT_MS: Optional. Plain-import cutoff in milliseconds (default900000, i.e. 15 minutes). When exceeded, the lock flips toerrorwith an actionable message.OPENAI_CACHE_DIR: Optional. Directory where AI-assisted imports cache model responses. Unset, the cache goes to<LOCAL_STORAGE_PATH>/<project>/.cache/openaiin local-disk mode, and to/usr/src/app/.cache/openaiinside the container when you use S3. That container path is lost whenever the container is recreated, which only costs repeated model calls; pointOPENAI_CACHE_DIRat a mounted volume if you want the cache to survive updates. If the directory is not writable, the import still works without caching. Nothing else in an S3 setup needs a persistent writable path: import and export work in temporary directories under/tmp.RESPONSIVENESS_LOOP_P99_WARN_MS: Optional. Event-loop p99 warning threshold in milliseconds (default500)./readinessreports not ready when the p99 exceeds four times this value.RESPONSIVENESS_HEAP_USED_WARN_FRACTION: Optional. Heap-used fraction above which/readinessreports not ready (default0.85).PLUGIN_DIRS: Comma-separated list of plugin directories. The image sets it to its built-in plugins (/usr/src/app/plugins); setting it replaces that list.SENTRY_DSN: Optional. Enables error reporting to a Sentry or GitLab error-tracking instance.SENTRY_TRACES_SAMPLE_RATE(default0, no tracing) andSENTRY_RELEASE(defaults to the image's commit SHA) tune it.
Step 5 – Launch and verify
- Start the stack:
docker compose up -d
- Follow the logs during the first startup:
docker compose logs -f
- When the log shows
🚀 Server ready, openhttp://localhost:3000(or your reverse proxy URL). The editor opens directly, without a login. Watch the next log lines too: if the server cannot reach the bucket, it logsFatal error: Could not access S3and shuts down. - Upload a template-managed manuscript and confirm that exports pick up your custom templates and fonts.
- Verify that objects appear in your S3 bucket and that versioning creates multiple revisions when you overwrite files.
Keeping templates synchronized on the server
If you prefer to keep everything contained on the host, schedule git-sync as a systemd timer, cron job, or container:
cat <<'EOF' | sudo tee /etc/systemd/system/osaps-template-sync.service
[Unit]
Description=Sync OS-APS templates
After=network-online.target
[Service]
Type=oneshot
ExecStart=/usr/bin/docker run --rm \
-v osaps-templates:/git \
registry.k8s.io/git-sync/git-sync:v4.1.0 \
--repo=git@git.university.edu:press/os-aps-templates.git \
--branch=main \
--root=/git \
--link=.
EOF
Add a companion timer and reload systemd:
cat <<'EOF' | sudo tee /etc/systemd/system/osaps-template-sync.timer
[Unit]
Description=Schedule OS-APS template sync
[Timer]
OnCalendar=hourly
Persistent=true
[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now osaps-template-sync.timer
Optional components
Image transformation sidecar
The sidecar converts EMF/WMF/PDF images to PNG. It bundles LibreOffice 26.2.2 (Debian trixie base) for this. During import, the server sends it the EMF and WMF images it finds in a document. Word documents often contain such images, for example as the preview of an OLE object or a MathType equation.
The Compose file above already runs it as the transform service and sets TRANSFORM_IMAGE_URL=http://transform:3001. The sidecar listens on port 3001 and does not need to be reachable from outside the Compose network.
If your workload includes many WMF/EMF images or OLE/MathType equations, treat the sidecar as required rather than optional — without it those assets land as placeholders in the editor.
For the quick start, put both containers on a shared Docker network:
docker network create osaps
docker run --rm -d --network osaps --name os-aps-transform \
registry.gitlab.com/sciflow/development/file-transform-sidecar:latest
Then add --network osaps -e TRANSFORM_IMAGE_URL=http://os-aps-transform:3001 to the docker run command of the server.
Windows administration
When running ad-hoc docker run commands from PowerShell, break lines with backticks (```). The Compose setup above is cross-platform and avoids quoting issues.
Monitoring with /status
OS-APS ships with an operator dashboard at /status that shows everything you need to triage a running deployment without shelling into the container.
What you see:
- Overall health — a single healthy / needs attention badge. It follows the same load signals as
/readiness: heap pressure, a stalled event loop, or an overloaded AI queue. The reachability probes below do not change it. When it flips to needs attention, a "what needs attention" list explains why. - Build info — uptime, the commit SHA the running image was built from (set by the build pipeline via
--build-arg CI_COMMIT_SHA; falls back togit rev-parse HEADon local builds), and the Node.js runtime version. - Queue state — how many AI analyses are running (
active) and waiting (queued), with the configuredconcurrencyandmaxAttemptsnext to them. - Reachability probes — S3 endpoint, OpenAI (when
OPENAI_API_KEYis set), Zotero. Each shows latency and a green tick or a clear failure reason. The filesystem probe reports free disk space. - Responsiveness — event-loop p50/p99 in milliseconds, heap used / limit, GC pause totals. p99 spikes correlate with blocked event-loop time during a stage and point to bottlenecks.
- Environment — Pandoc version + features as detected at startup, templates mount status (
TEMPLATE_SOURCEmounted yes/no, template count). - Throughput stats — last 1h and 24h windows: total runs, success/failure counts, error rate, avg run time, avg queue wait, top failure stages, per-stage p50/p95. Retries are collapsed into a single logical job so the error rate reflects user-visible outcomes, not attempt counts.
Click any transaction id under the activity list to open /status/<transactionId> — the per-run detail page with the full stage breakdown chart, downloadable JSON bundle (server context + import logs + AI logs in one file), and live polling while the AI phase is still running.
Health and readiness probes
For Kubernetes (or any orchestrator) wire your liveness / readiness / metrics targets to these endpoints. They are intentionally not gated by STATUS_PASSWORD, so probes keep working when the dashboard is locked down.
| Endpoint | Purpose |
|---|---|
/healthz |
Returns {"status":"ok"} with the uptime whenever the process answers HTTP. Suitable for liveness probes. |
/readiness |
Returns {"status":"ok"}, or 503 with {"status":"degraded","reasons":[…]} while the server is under load: heap use above RESPONSIVENESS_HEAP_USED_WARN_FRACTION, more queued AI jobs than four times the queue concurrency, or event-loop p99 above four times RESPONSIVENESS_LOOP_P99_WARN_MS. It does not check S3 or templates. Suitable for readiness probes — when this returns 5xx, the orchestrator will route traffic away. |
/metrics |
Prometheus exposition format. Operational metrics suitable for scraping. |
/api/status/dashboard returns the same view-model the dashboard renders, as JSON (and status 503 while degraded). Use it for custom alerting: overall is ok or degraded (shown as healthy / needs attention in the dashboard); alert on overall === "degraded" and inspect overallReasons.
Tuning the AI queue
AI analyses run through an in-process FIFO queue, capped at ANALYSIS_QUEUE_CONCURRENCY (default 2). The cap exists because each conversion streams a .docx through JSDOM/ProseMirror, makes 6–8 sequential OpenAI calls, and pulls a base64 image set into memory — running too many in parallel produces memory pressure and OpenAI rate-limit cascades.
Rules of thumb for tuning:
- Small VM (≤ 4 GB RAM): leave concurrency at 2 (or lower to 1 if you see heap-used staying above 70%).
- Larger host (8 GB+ RAM, 4+ CPU cores): raise concurrency to 3–4 if
/statusshows event-loop p99 staying under ~150 ms and heap-used under 70%. Bumping beyond your OpenAI tier's effective concurrency just buys throttling. - You see a lot of
retryable: truefailures on /status — that is the queue recovering from transient OpenAI 429/5xx. Healthy; no action. If it happens constantly, contact OpenAI to raise your tier instead of raising the local concurrency. - Imports are timing out — raise
IMPORT_TIMEOUT_MS(e.g.1800000for 30 minutes) if your typical document needs more than 15 minutes to convert through Pandoc.
The queue persists its job descriptors to _queue/jobs/<id>.json in your S3 bucket so a process restart does not lose work. A descriptor is removed as soon as the job finishes; if you see them piling up, check the /status/<id> detail page of one to see where the pipeline is stuck.
Stuck jobs
If a single doc gets stuck and refuses to clear (status stays running or queued long after expected):
- Open
/status/<transactionId>and download the JSON bundle — thestagefield and the log tail explain what failed. - As a last resort, delete the lock file at
<project>/.analysis/<doc>.analysis-lock.jsonand the queue descriptor at_queue/jobs/<escaped-doc-id>.jsonfrom your bucket; the user can re-trigger the analysis from the editor afterwards.
AI-assisted import
The editor can use OpenAI to detect document structure, authors, references, in-text citations, and generate image alt text during import. These features are optional — when no API key is configured, the import screen offers only the standard import and documents are imported using rule-based parsing.
To enable AI-assisted import:
- Obtain an API key from your OpenAI account dashboard.
-
Add the key to your
.envfile:OPENAI_API_KEY=sk-... -
Reference it in your Compose environment block, together with the reasoning effort (both are included as comments in the example above):
OPENAI_API_KEY: "${OPENAI_API_KEY}" OPENAI_REASONING_EFFORT: "medium" -
Restart the stack:
docker compose up -d
Set the reasoning effort
Without OPENAI_REASONING_EFFORT, the default model runs with no reasoning. Imports still succeed, but on a long manuscript the structure recognition returns only part of the document's elements, with no error. medium recognises them reliably; low does not.
Once the key is active, the import screen offers a choice between the standard and the AI-assisted import. See the User Manual for what each AI option does.
Reasoning effort per step
Each step of an AI-assisted import can override OPENAI_REASONING_EFFORT with its own variable, for example to save cost on the simpler steps:
OPENAI_REASONING_EFFORT_DESCRIBE_IMAGE=low
A step's variable accepts the same values (none turns reasoning off for that step). An unset or unknown value falls back to OPENAI_REASONING_EFFORT, so nothing changes until you set one. Keep TAG_HTML, the structure recognition, at medium or higher, and lower a step only after checking its results on your own manuscripts.
| Variable suffix | Step | Runs when |
|---|---|---|
TAG_HTML |
Structure recognition: what each element of the document is | always |
GET_FRONT |
Title and front-matter metadata | Authors and affiliations is on |
GET_AFFILIATIONS |
Authors and affiliations | Authors and affiliations is on |
RATE_QUALITY |
Rating the quality of the import | Authors and affiliations is on |
REFERENCE_CSL |
References turned into structured (CSL) data | References is on |
CONTENT_MAP |
In-text citations the built-in matcher could not link | In-text citations is on |
DESCRIBE_IMAGE |
Image descriptions | Image descriptions is on |
Each variable is OPENAI_REASONING_EFFORT_ followed by the suffix.
AI analyses are funneled through an in-process queue capped at ANALYSIS_QUEUE_CONCURRENCY (default 2). See Tuning the AI queue for sizing advice and how to monitor the queue in production.
Development mode
If you plan to modify exporter code or contribute upstream, see the Development Setup Guide for instructions on building the stack locally.
Setup on various environments
Reverse proxy example (Apache)
Serve the application through a reverse proxy that terminates TLS and forwards traffic to port 3000 on the Docker host. The snippets below target Apache 2.4.58 running on the same machine as the containers.
Enable the required modules once:
sudo a2enmod proxy proxy_http headers ssl
sudo systemctl reload apache2
Port 80 virtual host (/etc/apache2/sites-available/000-default.conf)
<VirtualHost *:80>
ServerName aps.university.edu
ServerAdmin webmaster@university.edu
ProxyRequests Off
ProxyPreserveHost On
AllowEncodedSlashes NoDecode
ProxyPass / http://127.0.0.1:3000/ nocanon
ProxyPassReverse / http://127.0.0.1:3000/
ErrorLog ${APACHE_LOG_DIR}/osaps-error.log
CustomLog ${APACHE_LOG_DIR}/osaps-access.log combined
</VirtualHost>
TLS virtual host (/etc/apache2/sites-available/default-ssl.conf)
<VirtualHost *:443>
ServerName aps.university.edu
ServerAdmin webmaster@university.edu
SSLEngine on
SSLCertificateFile /etc/ssl/certs/aps.university.edu.crt
SSLCertificateKeyFile /etc/ssl/private/aps.university.edu.key
ProxyRequests Off
ProxyPreserveHost On
AllowEncodedSlashes NoDecode
ProxyPass / http://127.0.0.1:3000/ nocanon
ProxyPassReverse / http://127.0.0.1:3000/
ErrorLog ${APACHE_LOG_DIR}/osaps-error.log
CustomLog ${APACHE_LOG_DIR}/osaps-access.log combined
</VirtualHost>
Reload Apache after enabling the sites:
sudo a2ensite 000-default.conf default-ssl.conf
sudo systemctl reload apache2
The critical directive is AllowEncodedSlashes NoDecode, which prevents the proxy from rewriting %2F sequences that OS-APS uses in download URLs.
Troubleshooting
Container exits with code 139 during exports
Large images expand dramatically in memory when they are rasterized. If the container exits with code 139, raise the memory limit for the Docker service or move the export job to a host with more RAM. When possible, ask authors to upload images that are already optimized (PNG for graphics, JPEG for photos).
Encoded slashes cause 404 responses behind a proxy
Some proxies decode %2F to / before forwarding the request, breaking download links. Ensure your reverse proxy forwards encoded slashes untouched. For Apache use AllowEncodedSlashes NoDecode; for NGINX set proxy_set_header X-Original-URI $request_uri; and disable rewriting of encoded characters.
Logs and support
Use docker compose logs osaps (or docker logs <container>) to inspect runtime issues. When asking for help, include the container image version, relevant environment variables, and the reverse proxy configuration you are using.
Next steps
- Restrict access to the editor at your reverse proxy or VPN to match your university policies. The editor has no login of its own.
- Add monitoring (Prometheus, ELK) and alerting before inviting authors.
- Plan regular updates: pull the latest image, re-run
docker compose up -d, and verify exports using your staging environment. Image tags follow the branch names of the source repository (for examplelatest,development, or a release branch such asrelease-2026-3-3) and move when that branch is rebuilt. To pin an exact build, reference the image by its digest (server@sha256:…). - Provide a
SENTRY_DSNenvironment variable to enable error reporting to a Sentry / GitLab instance (see Environment variables of note). - Provide a PrinceXML license file using
PRINCE_LICENSE_PATH.