149 lines
4.4 KiB
Markdown
149 lines
4.4 KiB
Markdown
# 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.
|
|
- Frontend runtime switches to a static build served by Nginx in this mode.
|
|
|
|
## 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 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`.
|