Install Fulgoria

Fulgoria ships a thin server (server.js, Node/Express) that does only two things: it serves the static app and, optionally, gates it behind a login read from .env. The document itself is always processed 100% in the browser — the server never receives it, applies a strict CSP and security headers, and never exposes .env, server.js or any private samples.

Requirements

Docker

Recommended for production. Use the prebuilt image or build locally with docker compose.

Node.js 18+

Required only if you run the server directly with npm instead of Docker.

A modern browser

All extraction (PDF parsing, OCR, editing) runs client-side, so a current browser is where the real work happens.

Run with Docker

The fastest path is the image published to GHCR, built by CI on every push to main.

docker run

docker run -d \
  -p 3000:3000 \
  -e AUTH_ENABLED=true \
  -e AUTH_USER=diego \
  -e AUTH_PASSWORD='your-password' \
  -e SESSION_SECRET="$(openssl rand -hex 32)" \
  -e COOKIE_SECURE=false \
  ghcr.io/diegoparras/fulgoria:latest

Then open http://localhost:3000.

docker compose

Clone the repo, prepare your .env, and build:

cp .env.example .env
# edit .env: set AUTH_PASSWORD and SESSION_SECRET
docker compose up --build

The bundled compose file maps port 3000, loads variables from .env, and restarts unless stopped.

Node / npm

cp .env.example .env
npm install
node server.js --hash 'your-password'   # → paste the hash into AUTH_PASSWORD
openssl rand -hex 32                     # → paste into SESSION_SECRET
npm start                               # → http://localhost:3000

Deploying on EasyPanel

Use the same ghcr.io/diegoparras/fulgoria:latest image and set the environment variables in the panel. Behind HTTPS, keep COOKIE_SECURE=true.

First run

1. Open the app at http://localhost:3000 (or your configured host).
2. If AUTH_ENABLED=true, sign in with AUTH_USER and the password you configured.
3. Click Open PDF or image, or See an example to load a sample bank statement.
4. Mark the columns, check the balance turns green, and export to CSV.

Passwords

You can store AUTH_PASSWORD as plain text (like the rest of the Escriba family), but a bcrypt hash is safer if the .env ever leaks. Generate one with node server.js --hash 'your-password' and paste the resulting $2a$... value.

Environment variables

All configuration lives in .env (copy it from .env.example). The .env file is never committed and never served.

Variable	Default	Description
PORT	3000	Port the thin server listens on.
AUTH_ENABLED	true	Set to false to serve the app with no password (local or private-network use).
AUTH_USER	diego	Username for the login.
AUTH_PASSWORD	(empty)	The password — plain text, or a bcrypt hash from --hash.
SESSION_SECRET	(empty)	Secret used to sign the session cookie. Generate with openssl rand -hex 32.
SESSION_TTL_HOURS	12	Session lifetime, in hours.
COOKIE_SECURE	true	Keep true behind HTTPS; set false only to test locally over http://.
ESCRIBA_URL	(empty)	Destination of the “Send to Escriba” button. Empty falls back to /. Point it at your Escriba, e.g. https://your-escriba.com/.