Skip to main content

Install with Docker Compose

The repository includes a Caddy-based example that builds Jiandu from the checked-out source, publishes HTTPS on port 443, and keeps Jiandu plus a pinned PostgreSQL 18.6 server on an internal container network. PostgreSQL uses certificate-verified TLS and publishes no host port.

1. Get the source​

git clone https://github.com/zhyuri/jiandu.git
cd jiandu

For a reproducible installation, check out a release tag instead of an arbitrary commit once release tags are available.

2. Start the reviewed example​

docker compose -f examples/docker-compose/docker-compose.yml up --build

The first build can take a while. Keep the terminal open until the services report that they are ready. The stack generates its database password and private database CA on first startup; neither secret needs to be placed in the Compose file or your shell environment.

:::warning Existing Compose installations Earlier revisions of this example used SQLite. Jiandu does not silently convert an existing SQLite database to PostgreSQL. Preserve your existing volumes and make a verified backup before changing the backend of an installation that already contains data. :::

The example sets pids_limit: 256 on the Jiandu service. This applies one container-scoped ceiling to Jiandu and its PDF/OCR helpers while leaving enough room for ONNX Runtime's inference threads. Do not replace it with an OCR-child RLIMIT_NPROC: Linux accounts that limit across every process and thread owned by the same real UID, which may also be shared by unrelated host services. OCR still has its own memory, CPU-time, open-file, output, wall-clock, and process-group termination controls.

3. Open Jiandu​

Open https://jiandu.localhost. Caddy uses a local certificate authority in this example, so your browser may warn until that CA is trusted on your device. Follow the instructions in the example's README rather than bypassing certificate warnings permanently.

4. Complete first-run setup​

Jiandu creates a recovery token on first full startup. The terminal reports the path, not the token itself. From a second terminal in the repository root, read it from the running Jiandu container:

docker compose -f examples/docker-compose/docker-compose.yml exec jiandu \
  cat /app/jiandu-data/owner-access-token

The command prints a secret. Do not paste its output into chat, issue reports, or shared shell logs. Use it once to claim the clean installation with the human account that should administer Jiandu, then continue with first run.

Stop and return later​

docker compose -f examples/docker-compose/docker-compose.yml down
docker compose -f examples/docker-compose/docker-compose.yml up

Do not add --volumes to the down command unless you intend to remove persistent data and have confirmed a restorable backup.