# 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.

```bash
cp .env.example .env
```

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

```bash
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.

## Daily Use Commands

Start or rebuild:

```bash
docker compose up --build -d
```

Stop:

```bash
docker compose down
```

View logs:

```bash
docker compose logs -f
```

View backend logs only:

```bash
docker compose logs -f api worker
```

## Where Your Data Is Stored

LedgerDock stores data in Docker volumes so it survives container restarts:

- `db-data` for PostgreSQL data
- `redis-data` for Redis data
- `dcm-storage` for uploaded files and app storage
- `typesense-data` for the search index

To remove everything, including data:

```bash
docker compose down -v
```

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`.