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

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

Open:

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

Container Layout

• main: web + FastAPI main container
• postgres: PostgreSQL database container

The project root is mounted directly into the main container:

.:/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.
• 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.
• 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.