Bring Escriba home

Escriba ships as one prebuilt Docker image that already bundles everything it needs — ffmpeg, Tesseract OCR, Whisper and an embedded Redis. There are no extra services to wire up. Pull it, set a password, and you have a private document-to-Markdown engine running on your own infrastructure.

Why self-host?

Your documents are converted on your machine and deleted right after. Nothing is stored, nothing is sent to a third-party cloud. The control stays on the human layer — you decide what ever reaches an LLM.

Quick start

Pull the image and run it with a single command:

Run Escriba

docker run -d --name escriba --restart unless-stopped -p 8000:8000 \
-e SECRET_KEY="$(openssl rand -hex 32)" \
-e GOD_PASSWORD="change-me" \
ghcr.io/diegoparras/escriba:latest

Then open http://localhost:8000 and sign in with the GOD_PASSWORD you set.

Note

The image bundles ffmpeg, Tesseract OCR, Whisper and embedded Redis. No additional services are required. Generate keys with openssl rand -hex 32.

Deploy on your platform

Everything runs from the single image above. Pick the platform you use.

EasyPanel

1. Project → + Service → App, then set Source → Docker Image to ghcr.io/diegoparras/escriba:latest.
2. Add your environment variables (see Configuration).
3. Under Domains, set Container Port 8000, add your domain and enable HTTPS.
4. Deploy.

Docker Compose

git clone https://github.com/diegoparras/escriba.git
cd escriba
cp .env.example .env          # set your secrets
docker compose up -d --build

Portainer

Stacks → Add stack → Repository using https://github.com/diegoparras/escriba and compose path docker-compose.yml (or paste the compose file in the web editor). Set the environment variables and deploy; the app listens on port 8000.

Dokploy

Create Application → GitHub (repo diegoparras/escriba) with Build Type: Dockerfile, add your environment variables, set the domain to Container Port 8000 with HTTPS, and deploy.

Plain Docker

docker build -t escriba .
docker run -d --name escriba --restart unless-stopped -p 8000:8000 \
-e SECRET_KEY="$(openssl rand -hex 32)" -e GOD_PASSWORD="change-me" escriba

For TLS, put a reverse proxy in front. With Caddy, a two-line Caddyfile gives you automatic HTTPS:

Caddyfile

example.com {
    reverse_proxy localhost:8000
}

Minimum configuration

All settings are environment variables. The recommended minimum:

.env

SECRET_KEY=<openssl rand -hex 32>   # required in production
GOD_PASSWORD=<a strong password>
ANGEL_PASSWORD=<optional>
HUMAN_PASSWORD=<optional>

If no password is set, a random GOD_PASSWORD is generated and printed to the container logs on startup. See the full list in Configuration.

Requirements

The base app is light: a 1-core / 2 GB VPS with ~5 GB of disk is genuinely enough to start, and Escriba scales workers to your CPU. The optional enterprise PII anonymization module (Anonimal) is heavier — mount it only when you need it.

Be sure before you deploy

We list honest minimum and recommended specs for every setup — base app, enterprise anonymization, and heavy transcription — so it never feels like it “doesn’t work” because of your machine. See the full system requirements →

Full deployment guide All configuration options