Skip to main content

Quickstart

This guide takes a fresh checkout to a working, local Jiandu library. You will start the reviewed Docker Compose topology, claim the installation, add one sample document, and verify that you can retrieve its preserved original.

Before you begin​

You need:

  • Git;
  • Docker Engine with the Compose plugin;
  • Bash, curl, jq, and standard Unix file utilities for the current bootstrap and recovery-copy helpers;
  • TCP port 443 available on the host; and
  • a non-sensitive PDF or image for the first upload.

The example builds Jiandu from source. The first build can take several minutes because it compiles the server and browser application locally.

Evaluate before relying on it

Jiandu is evolving software and does not yet publish release packages. Use sample documents, read the current support boundaries, and complete a restore drill before making it the only home for important records.

Repository access is currently required

The source repository is not anonymously accessible at the time of writing. If the clone command returns 404, there is no public package fallback and this evaluation path is unavailable. That is a project-distribution blocker, not a local Git or Docker problem.

1. Start Jiandu​

git clone https://github.com/zhyuri/jiandu.git
cd jiandu
docker compose -f examples/docker-compose/docker-compose.yml up --build

Keep this terminal open. A healthy stack has a jiandu application service, a pinned PostgreSQL 18.6 database, and a caddy HTTPS proxy. Only Caddy publishes a host port; Jiandu and PostgreSQL stay on the internal container network. The stack generates the database password and private database CA on first startup and does not put either secret in the Compose file or shell environment.

In a second terminal, confirm the application is ready:

docker compose -f examples/docker-compose/docker-compose.yml ps

Wait until the Jiandu service reports healthy. If it does not, inspect the recent service log without sharing secrets:

docker compose -f examples/docker-compose/docker-compose.yml logs --tail=100 jiandu

2. Open the local site​

Open https://jiandu.localhost.

The example uses Caddy's local certificate authority. Install that local root certificate in the test browser before treating the connection as valid; the Compose guide explains the trust boundary. Do not train yourself to ignore certificate warnings on a real household deployment.

3. Create the first human Administrator​

The default configuration has no external identity provider and no existing human account, so the first account is created with the installation's Owner recovery token. You can do that from a terminal or in the browser. Either way the result is a normal human account with the built-in Administrator role, and the token proves control of the installation without being attached to that account or consumed.

For this Compose topology the helper is the simpler path. The token file lives in the container's data volume, and the helper reads it there without ever displaying it. It follows the same steps as the browser form:

./examples/docker-compose/bootstrap-local-account.sh

Choose a display name, username, and unique password when prompted. The helper:

  1. copies Caddy's local root certificate and validates HTTPS with it;
  2. streams the Owner recovery token directly from the container without printing it or placing it in command arguments;
  3. verifies that setup is still unclaimed before creating anything;
  4. creates the human account first as a Member;
  5. signs in as that human and claims setup, making the account Administrator; and
  6. verifies each response, revokes both temporary sessions, and deletes its private response, cookie, and certificate files.

On success it prints Created <username> and completed installation setup. Open https://jiandu.localhost and sign in with that username and password.

A cleanup failure makes the command fail and retains the private directory it names so you can revoke the session manually. If an account-creation request had an ambiguous outcome, the helper names the username to inspect before retrying; do not blindly rerun and create a second account.

To use the browser instead, open https://jiandu.localhost while the installation is unclaimed and choose Create the first account on the sign-in page. Enter your name, a username, a password twice, and the Recovery access token, then choose Create account. Jiandu creates the account, makes it Administrator, and opens Settings; from then on you sign in with that username and password. The username and password rules apply, and the option appears only while the installation is unclaimed.

The token is the 64-character value in the owner-only file Jiandu created at first startup. In this topology that file is inside the container volume, so copy it to a protected file with the export helper in the next step and paste it from there instead of printing it in a terminal.

The Owner token remains separate and usable for break-glass recovery. Store an offline copy through a protected channel. Enter it only in Jiandu's own first-account or recovery forms; never paste it into chat, an issue, a shell transcript, or a shared password field.

4. Preserve the Owner recovery credential​

The recovery backup intentionally excludes the raw Owner token. Before trusting the installation, copy it to a new owner-only file outside the repository and outside the Compose volumes. Replace the example destination with a path on protected storage:

./examples/docker-compose/export-owner-token.sh \
  /protected/offline/jiandu-recovery/owner-access-token

The helper refuses repository destinations and existing files, requires an owner-controlled directory with no group or other access, validates the 64-character token shape, and compares the copy byte-for-byte with the running installation without printing either value. Move or copy the result through a protected channel to storage that will survive loss of the Docker host. Keep the in-volume original: Jiandu still needs it for Owner recovery.

5. Prove the basic workflow​

Use a non-sensitive sample and verify the whole loop:

  1. Add the PDF or image in the browser.
  2. Open the preserved original.
  3. Correct the title or another filing field.
  4. Search for a distinctive word from that correction.
  5. Download the preserved original and open it outside Jiandu.

You have reached the first useful milestone only when all five checks pass. A green readiness probe proves that dependencies are available; it does not prove that a document is usable.

6. Stop without deleting data​

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

The named Jiandu, PostgreSQL, Caddy, and runtime volumes remain. Start the same installation again with the command from step 1.

Do not add --volumes unless you deliberately intend to erase the example's Jiandu and Caddy data and have already verified a backup.

Next steps​

Last updated on