Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion .dockerignore
Original file line number Diff line number Diff line change
Expand Up @@ -16,4 +16,3 @@ docs
.github
.qa
explorer-dist
desktop
113 changes: 113 additions & 0 deletions DEVELOPMENT.en.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
# Web development

[简体中文](DEVELOPMENT.md) | **English** · [Use and deployment](README.en.md)

## Requirements

Python 3.10+, Node.js 22.15+, and pnpm 10.28.2. Run the Windows commands in PowerShell.

## First run

Install dependencies from the repository root.

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r web/requirements.txt
pnpm --dir web install --frozen-lockfile
pnpm --dir web build
cd web
..\.venv\Scripts\python.exe app.py
```

Open <http://127.0.0.1:8767> and press Ctrl+C to stop the server. The default local SQLite database is created at `data/ledger.sqlite3` in the repository root.

On Linux / macOS, use these commands.

```sh
python3 -m venv .venv
.venv/bin/python -m pip install -r web/requirements.txt
pnpm --dir web install --frozen-lockfile
pnpm --dir web build
cd web
../.venv/bin/python app.py
```

## Edit the application

| Path | Contents |
| --- | --- |
| `web/src/` | React pages, styles, and interactions |
| `web/public/` | Website icons and static files |
| `web/backend/` | HTTP API, validation, and ledger storage |
| `web/runtime/` | Container startup and health checks |
| `web/tests/` | Frontend, backend, and database tests |
| `deploy/` | Docker runtime and database deployment configuration |
| `.github/workflows/publish.yml` | Automated checks and image publishing |

For frontend changes, keep the Python server running. Open another terminal in `web/` and run the build watcher.

```sh
pnpm exec vite build --watch
```

Saving a change rebuilds the frontend. Refresh <http://127.0.0.1:8767> to view it. Restart the Python server after backend changes.

## Local configuration

`python app.py` reads process environment variables. Docker Compose loads `.env`. When running Python directly, set variables in the terminal.

For a fixed local privacy password, set this in the PowerShell terminal that starts the server.

```powershell
$env:DATABACK_PRIVACY_PASSWORD = "replace-with-your-own-privacy-password"
```

| Setting | Purpose |
| --- | --- |
| `DATABACK_PORT` | Python server port, default `8767` |
| `DATABACK_DATA_DIR` | SQLite directory, default `data/` in the repository root |
| `DATABACK_SNAPSHOT_DIR` | Snapshot directory, default `snapshots/` beside the SQLite file |
| `MONGODB_URI`, `MONGODB_DATABASE` | Development MongoDB replica-set connection and database name |

From `web/`, use the same virtual-environment Python path as in the first-run commands and add `--port 8768 --db /path/to/ledger.sqlite3` to select a port and a separate test ledger. Keep test data in a different location from your daily ledger.

## Checks

Run from `web/`.

```sh
pnpm test
pnpm build
```

On Windows, run backend tests with the project virtual environment.

```powershell
..\.venv\Scripts\python.exe -m unittest discover -s tests -p 'test_*.py'
```

On Linux / macOS, use `../.venv/bin/python`. Full MongoDB tests require `DATABACK_TEST_MONGO_URI` pointing to an isolated replica set. Those tests are skipped locally when it is unset. GitHub Actions creates a test database and runs the full checks.

## Commit and publish

1. Create a branch from the latest `main`, make changes, and run the checks.
2. Commit, push the branch, and open a PR. Reference the relevant issue in fix commits and use `Fixes #number` when the issue is fully resolved.
3. Merge into `main` after PR checks pass.
4. Wait for the GitHub Actions `test` and `publish` jobs to succeed.
5. Pull the image and update the application on the Docker host.

```sh
docker compose pull app
docker compose up -d --no-deps app
docker compose ps
```

Builds publish `ghcr.io/cimorn/databack:latest` and `sha-<full-commit-hash>` for `amd64` and `arm64`. In a NAS interface, redeploy the DataBack project with the option to pull the latest image selected.

## Data and cleanup

- For a full local backup, stop the Python server and copy `data/`. To restore, stop the server, restore the data directory, and restart.
- The server creates daily ledger snapshots and retains the latest 30. New snapshots continue to be created after old ones are cleared.
- Follow the deployment guide for Docker database, snapshot, and configuration backups. [Database backup and restore](docs/docker.en.md#full-backup)
- Run `git status --short` before committing. Commit source, lockfiles, and documentation. Keep credentials, databases, snapshots, dependencies, builds, and test output on the local or deployment host.
- After development, you can remove `web/dist/`, `web/node_modules/`, `.venv/`, and Python caches. Reinstall dependencies and rebuild when you return.
113 changes: 113 additions & 0 deletions DEVELOPMENT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
# 网页开发

**简体中文** | [English](DEVELOPMENT.en.md) · [使用与部署](README.md)

## 环境

Python 3.10+、Node.js 22.15+、pnpm 10.28.2。以下 Windows 命令在 PowerShell 中执行。

## 首次运行

在项目根目录安装依赖。

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r web/requirements.txt
pnpm --dir web install --frozen-lockfile
pnpm --dir web build
cd web
..\.venv\Scripts\python.exe app.py
```

打开 <http://127.0.0.1:8767>,按 Ctrl+C 停止。默认使用本机 SQLite,首次运行会在项目根目录创建 `data/ledger.sqlite3`。

Linux / macOS 使用以下命令。

```sh
python3 -m venv .venv
.venv/bin/python -m pip install -r web/requirements.txt
pnpm --dir web install --frozen-lockfile
pnpm --dir web build
cd web
../.venv/bin/python app.py
```

## 修改代码

| 路径 | 内容 |
| --- | --- |
| `web/src/` | React 页面、样式和交互 |
| `web/public/` | 网站图标和静态文件 |
| `web/backend/` | HTTP 接口、校验和台账存储 |
| `web/runtime/` | 容器启动与健康检查 |
| `web/tests/` | 前端、后端和数据库测试 |
| `deploy/` | Docker 运行与数据库部署配置 |
| `.github/workflows/publish.yml` | 自动测试和镜像发布 |

修改前端时,保留 Python 服务,在另一个终端进入 `web/` 执行。

```sh
pnpm exec vite build --watch
```

保存代码后会重新构建,刷新 <http://127.0.0.1:8767> 查看。修改后端后,重启 Python 服务。

## 本机配置

`python app.py` 读取进程环境变量。`.env` 由 Docker Compose 加载,直接运行 Python 时需在终端设置变量。

在启动服务的 PowerShell 终端中,可设置固定的本机隐私密码。

```powershell
$env:DATABACK_PRIVACY_PASSWORD = "替换为你自己的隐私密码"
```

| 配置 | 用途 |
| --- | --- |
| `DATABACK_PORT` | Python 服务端口,默认 `8767` |
| `DATABACK_DATA_DIR` | SQLite 数据目录,默认项目根目录的 `data/` |
| `DATABACK_SNAPSHOT_DIR` | 快照目录,默认与 SQLite 文件同级的 `snapshots/` |
| `MONGODB_URI`、`MONGODB_DATABASE` | 开发用 MongoDB 副本集连接和数据库名 |

在 `web/` 沿用首次运行的虚拟环境 Python 路径,添加 `--port 8768 --db /path/to/ledger.sqlite3` 可指定端口和独立测试台账。测试数据与日常台账使用不同路径。

## 检查

在 `web/` 执行。

```sh
pnpm test
pnpm build
```

Windows 后端测试使用项目虚拟环境。

```powershell
..\.venv\Scripts\python.exe -m unittest discover -s tests -p 'test_*.py'
```

Linux / macOS 将 Python 路径换为 `../.venv/bin/python`。完整 MongoDB 测试需用 `DATABACK_TEST_MONGO_URI` 指向独立副本集,本机未配置时对应测试会跳过。GitHub Actions 会创建测试数据库并执行完整检查。

## 提交与发布

1. 从最新 `main` 创建分支,修改并完成检查。
2. 提交、推送分支,创建 PR。修复提交引用对应 issue,完整解决使用 `Fixes #编号`。
3. PR 检查通过后合并到 `main`。
4. 等待 GitHub Actions 的 `test` 和 `publish` 成功。
5. Docker 主机拉取镜像并更新应用。

```sh
docker compose pull app
docker compose up -d --no-deps app
docker compose ps
```

构建发布 `ghcr.io/cimorn/databack:latest` 和 `sha-完整提交编号`,支持 `amd64`、`arm64`。NAS 图形界面可在 DataBack 项目中重新部署并勾选“拉取最新镜像”。

## 数据与清理

- 本机完整备份时,先停止 Python 服务,再复制 `data/`。恢复时停止服务,放回对应数据目录后启动。
- 服务端每天生成台账快照,保留最新 30 份。清空历史快照后,服务会继续生成新快照。
- Docker 的数据库、快照和配置备份按部署文档操作。 [数据库备份与恢复](docs/docker.md#完整备份)
- 提交前运行 `git status --short`,只提交源码、锁文件和文档。凭据、数据库、快照、依赖、构建产物和测试输出保存在本机或部署主机。
- 开发结束后可删除 `web/dist/`、`web/node_modules/`、`.venv/` 和 Python 缓存,再次开发时重新安装依赖并构建。
30 changes: 3 additions & 27 deletions README.en.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,36 +53,12 @@ Updates preserve data volumes and `.env`. Check status with `docker compose ps`

## Develop and publish

Requires Python 3.10+, Node.js 22.15+, and pnpm 10.28.2.
See [Web development](DEVELOPMENT.en.md) for setup, local previews, code changes, and test commands.

```sh
cd web
python -m pip install -r requirements.txt
pnpm install --frozen-lockfile
pnpm build
python app.py
```

Open <http://127.0.0.1:8767>. For frontend development, run `pnpm dev` from `web/` in another terminal. Keep the Python server running for API requests.

```sh
pnpm test
pnpm build
python -m unittest discover -s tests -p 'test_*.py'
```

MongoDB integration tests require a separate replica set. Set `DATABACK_TEST_MONGO_URI` to its connection string. CI creates an isolated test database automatically.

Edit `web/src/` for the interface and `web/backend/` for the API. Push to `main` to run tests and publish `ghcr.io/cimorn/databack:latest` through GitHub Actions. Each build also publishes a `sha-<full-commit-hash>` tag for pinning or rolling back an image.
Push a branch and open a PR → merge into `main` after checks pass → wait for GitHub Actions to publish the image → pull the update on the Docker host. Images use `latest` and `sha-<full-commit-hash>` tags.

To build locally, run `docker build -t databack .` from the repository root.

## Desktop launcher

On Windows, build `web/`, then double-click `desktop/启动.cmd` to start and `desktop/关闭.cmd` to stop. The launcher opens the local web app in your browser. Data is stored in `data/` at the repository root.

Set the `DATABACK_PRIVACY_PASSWORD` environment variable before using private folders locally.

## Back up and restore data

- **Automatic backups:** The server saves one ledger snapshot per day and retains the latest 30. Docker stores these in the `databack_snapshots` volume by default.
Expand All @@ -95,7 +71,7 @@ The ledger records folders and backup information. Save actual files and deploym

```text
web/ Web interface, API, and tests
desktop/ Windows start and stop scripts
DEVELOPMENT.en.md Web development guide
deploy/mongodb/ Optional MongoDB replica-set configuration
Dockerfile Image build
compose.yaml Docker deployment
Expand Down
30 changes: 3 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,36 +53,12 @@ docker compose up -d app

## 开发与发布

需要 Python 3.10+、Node.js 22.15+、pnpm 10.28.2。
环境安装、本地运行、修改代码和测试命令见 [网页开发文档](DEVELOPMENT.md)。

```sh
cd web
python -m pip install -r requirements.txt
pnpm install --frozen-lockfile
pnpm build
python app.py
```

打开 <http://127.0.0.1:8767>。开发界面时另开终端,在 `web/` 运行 `pnpm dev`,API 由 Python 服务提供。

```sh
pnpm test
pnpm build
python -m unittest discover -s tests -p 'test_*.py'
```

MongoDB 集成测试使用独立副本集,通过 `DATABACK_TEST_MONGO_URI` 指定测试连接。CI 自动创建测试数据库。

修改 `web/src/` 更新界面,修改 `web/backend/` 更新接口。提交并推送到 `main` 后,GitHub Actions 自动测试并发布 `ghcr.io/cimorn/databack:latest`。也会发布 `sha-完整提交编号` 标签,可用于固定镜像或回退。
推送分支并创建 PR → 检查通过后合并到 `main` → 等待 GitHub Actions 发布镜像 → Docker 主机拉取更新。镜像同时提供 `latest` 和 `sha-完整提交编号` 标签。

本机构建镜像:`docker build -t databack .`(在项目根目录执行)。

## 桌面启动

Windows 构建 `web/` 后,双击 `desktop/启动.cmd`;关闭时双击 `desktop/关闭.cmd`。启动器使用浏览器打开本机网页,数据保存在项目根目录的 `data/`。

使用本机隐私目录前,设置 `DATABACK_PRIVACY_PASSWORD` 环境变量。

## 数据备份与恢复

- **自动备份:** 服务端每天保存一份台账快照,保留最新 30 份;Docker 默认保存在 `databack_snapshots` 数据卷。
Expand All @@ -95,7 +71,7 @@ Windows 构建 `web/` 后,双击 `desktop/启动.cmd`;关闭时双击 `deskt

```text
web/ 网页界面、API、测试
desktop/ Windows 启动与关闭脚本
DEVELOPMENT.md 网页开发说明
deploy/mongodb/ 可选 MongoDB 副本集配置
Dockerfile 镜像构建
compose.yaml Docker 部署
Expand Down
Loading