ledgerdock/README.md

LedgerDock

LedgerDock is a private document workspace you can run on your own computer or server. It helps teams collect files, process text from documents, and find information quickly with search.

What LedgerDock Is For

• Upload files and folders from one place
• Keep documents organized and searchable
• Extract text from scans and images (OCR)
• Download originals or extracted text

Before You Start

You need:

• Docker Desktop (Windows or macOS) or Docker Engine + Docker Compose (Linux)
• A terminal app
• The project folder on your machine
• Internet access the first time you build containers

Install With Docker Compose

Follow these steps from the project folder (where docker-compose.yml is located).

1. Create your local settings file from the template.

cp .env.example .env

2. Open .env in a text editor and set your own passwords and keys.
3. Start LedgerDock.

docker compose up --build -d

4. Wait until startup is complete, then open the app:

• LedgerDock web app: http://localhost:5173
• Health check: http://localhost:8000/api/v1/health

5. Sign in with the admin username and password you set in .env.

.env Settings Explained In Plain Language

LedgerDock reads settings from .env. Some values are required and some are optional.

Required: Change These Before First Use

• POSTGRES_PASSWORD: Password for the internal database.
• REDIS_PASSWORD: Password for the internal queue service.
• AUTH_BOOTSTRAP_ADMIN_PASSWORD: First admin login password.
• APP_SETTINGS_ENCRYPTION_KEY: Secret used to protect saved app settings.
• TYPESENSE_API_KEY: Secret key for the search engine.

Use long, unique values for each one. Do not reuse personal passwords.

Required: Usually Keep Defaults Unless You Know You Need Changes

• POSTGRES_USER: Database username.
• POSTGRES_DB: Database name.
• DATABASE_URL: Connection string to the database service.
• REDIS_URL: Connection string to the Redis service.
• AUTH_BOOTSTRAP_ADMIN_USERNAME: First admin username (default admin).

If you change passwords, make sure matching URLs use the same new password.

Optional User Account (Can Be Left Empty)

• AUTH_BOOTSTRAP_USER_USERNAME
• AUTH_BOOTSTRAP_USER_PASSWORD

These create an extra non-admin account on first startup.

Network and Access Settings

• HOST_BIND_IP: Where services listen. Keep 127.0.0.1 for local-only access.
• PUBLIC_BASE_URL: Backend base URL. Local default is http://localhost:8000.
• CORS_ORIGINS: Allowed frontend origins. Keep local defaults for single-machine use.
• VITE_API_BASE: Frontend API URL override. Leave empty unless you know you need it.

Environment Mode

• APP_ENV=development: Local mode (default).
• APP_ENV=production: Use when running as a real shared deployment with HTTPS and tighter security settings.
  • Frontend runtime switches to a static build served by Nginx in this mode.

Daily Use Commands

Start or rebuild:

docker compose up --build -d

Stop:

docker compose down

View logs:

docker compose logs -f

View backend logs only:

docker compose logs -f api worker

Where Your Data Is Stored

LedgerDock stores persistent runtime data in host bind mounts. By default the host root is ./data, or set DCM_DATA_DIR to move it:

• ${DCM_DATA_DIR:-./data}/db-data for PostgreSQL data
• ${DCM_DATA_DIR:-./data}/redis-data for Redis data
• ${DCM_DATA_DIR:-./data}/storage for uploaded files and app storage
• ${DCM_DATA_DIR:-./data}/typesense-data for the search index

On startup, Compose runs a one-shot storage-init service that creates the storage tree and applies write access for the backend runtime user uid=10001. If you want to inspect or repair it manually, use:

mkdir -p ${DCM_DATA_DIR:-./data}/storage
sudo chown -R 10001:10001 ${DCM_DATA_DIR:-./data}/storage
sudo chmod -R u+rwX,g+rwX ${DCM_DATA_DIR:-./data}/storage

To remove everything, including data:

docker compose down
rm -rf ${DCM_DATA_DIR:-./data}

Warning: this permanently deletes your LedgerDock data on this machine.

First Checks After Install

• Open http://localhost:5173 and confirm the login page appears.
• Open http://localhost:8000/api/v1/health and confirm you get {"status":"ok"}.
• Upload one sample file and confirm it appears in search.

Need Technical Documentation?

Developer and operator docs are in doc/, starting at doc/README.md.