X-Financial/docker/README.md

# Docker Compose

This project currently uses the Vite `__setup/*` middleware during the initial setup flow.
Because of that, the Docker deployment keeps the web frontend and FastAPI startup chain in
the same main container and runs the existing root `start.sh`.

## Start

```bash
cp .env.example .env
docker compose up -d
```

Open:

```text
http://<your-linux-host>:5173
```

## Container Layout

- `main`: web + FastAPI main container
- `onlyoffice`: ONLYOFFICE Document Server
- `postgres`: PostgreSQL database container

The project root is mounted directly into the main container:

```text
.:/app
```

That means the container reads your existing `.env`, source code, `server/.secrets`, logs,
and generated dependency directories directly from the mapped project folder.

This is a `compose`-only setup. There is no custom `Dockerfile`.
The tradeoff is that the `main` container installs the Python runtime packages it needs
when it starts.

## Persistence

The PostgreSQL data directory is stored in the named volume `postgres_data`.

## Notes

- Most configuration should be maintained in the project root `.env`.
- The first `docker compose up -d` does not require an existing `.env`; the compose file
  uses built-in defaults for the PostgreSQL container and the main container database URL.
- Docker Compose only overrides a few values that must differ inside containers:
  - `WEB_HOST=0.0.0.0`
  - `SERVER_HOST=0.0.0.0`
  - `POSTGRES_HOST=postgres`
  - `POSTGRES_PORT=5432`
  - `DATABASE_URL=...@postgres:...`
- PostgreSQL is also published to the host by default as `127.0.0.1:55432`.
- ONLYOFFICE is published to the host by default as `127.0.0.1:8082`.
- First boot with `SETUP_COMPLETED=false` starts the setup UI only.
- After you complete setup in the browser, the Vite setup bridge will start FastAPI in the
  same container using the saved runtime configuration.
- On later restarts, `start.sh` will detect the saved setup state and start both web and
  server automatically.
- If you access the system from another machine, make sure `CORS_ORIGINS` in `.env` includes
  the frontend address you actually use.
- For Navicat or any host-side client, use `127.0.0.1:55432`.
- If you need to access ONLYOFFICE from another machine, override `ONLYOFFICE_PUBLIC_URL`
  so the browser can reach the document server address you actually expose.
- For the setup page, using `127.0.0.1` is acceptable in this Docker layout; the internal
  test bridge will resolve that back to the Docker PostgreSQL service.