Metadata-Version: 2.5
Name: ershu
Version: 1.0.0.post20260812
Summary: Install Ershu Core or a pinned set of Ershu services.
Project-URL: Documentation, https://ershu.org
Project-URL: Repository, https://github.com/ershu-lab/ershu
Project-URL: Issues, https://github.com/ershu-lab/ershu/issues
Author: Ershu contributors
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: code-intelligence,developer-tools,ershu
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.14
Requires-Dist: ershu-core==1.0.1.post20260812
Provides-Extra: all
Requires-Dist: ershu-api==1.0.0.post20260812; extra == 'all'
Requires-Dist: ershu-mcp==1.0.0.post20260812; extra == 'all'
Requires-Dist: ershu-worker==1.0.0.post20260812; extra == 'all'
Provides-Extra: api
Requires-Dist: ershu-api==1.0.0.post20260812; extra == 'api'
Provides-Extra: mcp
Requires-Dist: ershu-mcp==1.0.0.post20260812; extra == 'mcp'
Provides-Extra: worker
Requires-Dist: ershu-worker==1.0.0.post20260812; extra == 'worker'
Description-Content-Type: text/markdown

# Ershu

[中文](README-CN.md)

This is Ershu's installation and deployment repository. Python users can install Core by itself, add API, MCP, or Worker, or install the complete backend. The repository also contains single-host infrastructure, systemd units, and a local reverse-proxy example.

The initial composition uses tag `v1.0.0-20260812`, which maps to Python package version `1.0.0.post20260812`. Components may publish independent versions later. `versions.env` records the component, frontend, and LSP image versions selected by a particular Ershu composition.

## Installation choices

Ershu requires Python 3.14 or newer.

| Command                       | Installs                                  |
| ----------------------------- | ----------------------------------------- |
| `pip install ershu`           | Core and the `ershu-db` migration command |
| `pip install "ershu[api]"`    | Core and the HTTP API                     |
| `pip install "ershu[mcp]"`    | Core and the MCP server                   |
| `pip install "ershu[worker]"` | Core and the background Worker            |
| `pip install "ershu[all]"`    | Core, API, MCP, and Worker                |

On a server, keep the environment at a fixed path and install an exact version:

```bash
uv venv --python 3.14 /opt/ershu/releases/v1.0.0-20260812/.venv
uv pip install \
  --python /opt/ershu/releases/v1.0.0-20260812/.venv/bin/python \
  "ershu[all]==1.0.0.post20260812"
```

Regular `pip` supports the same extras. The deployment installer uses `uv pip install` so systemd can always call commands from a known path.

The deployment does not use `uv tool install "ershu[all]"`. The `ershu` package describes a composition and provides no command of its own. Commands such as `ershu-db`, `ershu-api`, `ershu-worker`, and `ershu-mcp` come from its dependencies, whose executables UV does not expose by default for a tool installation.

## Repository responsibilities

This repository owns installation choices, composition versions, and shared deployment files. Component code remains in its own repository:

| Repository                                                  | Responsibility                                                          |
| ----------------------------------------------------------- | ----------------------------------------------------------------------- |
| [`ershu-core`](https://github.com/ershu-lab/ershu-core)     | Shared data model, permissions, query services, and database migrations |
| [`ershu-api`](https://github.com/ershu-lab/ershu-api)       | HTTP API, browser authentication, and repository polling                |
| [`ershu-mcp`](https://github.com/ershu-lab/ershu-mcp)       | MCP transport and tools                                                 |
| [`ershu-worker`](https://github.com/ershu-lab/ershu-worker) | Queue processing, analysis, LSP Dockerfiles, and LSP images             |
| [`frontend`](https://github.com/ershu-lab/frontend)         | Browser frontend                                                        |
| [`ershu-docs`](https://github.com/ershu-lab/ershu-docs)     | Public documentation                                                    |

LSP images follow Worker releases. This repository pins only published images in its version manifest and configuration examples.

## Deployment bundle contents

| File                                | Purpose                                                                              |
| ----------------------------------- | ------------------------------------------------------------------------------------ |
| `versions.env`                      | Records the component, frontend, LSP, and infrastructure versions in the composition |
| `runtime.env`                       | Passes the composition version and LSP images to the systemd services                |
| `compose.infrastructure.yml`        | Starts PostgreSQL, Redis, Milvus, etcd, and MinIO                                    |
| `.env.example`                      | Shared configuration example for API, Worker, MCP, and Core                          |
| `.env.compose.example`              | Infrastructure image, storage, and account example                                   |
| `deploy/systemd/`                   | Services for API, Worker, MCP, optional Poller, and database migration               |
| `deploy/nginx/ershu-local.conf`     | Loopback-only frontend and reverse-proxy example                                     |
| `scripts/generate_config_values.py` | Generates passwords and application secrets for the first deployment                 |

## Install on a Linux server

Download a deployment archive from GitHub Releases and extract it to:

```text
/opt/ershu/releases/<tag>
```

Enter the extracted directory and run:

```bash
sudo bash deploy/systemd/install.sh --uv-bin "$(command -v uv)"
```

The installer:

- creates a dedicated `ershu` system account;
- installs the composition's exact `ershu[all]` version from PyPI;
- prepares `/etc/ershu`, `/var/lib/ershu`, and `/var/cache/ershu`;
- installs the systemd units and points `/opt/ershu/current` to this release;
- updates the composition version while preserving existing secrets and deployment settings.

Edit these files after installation:

```text
/etc/ershu/.env
/etc/ershu/compose.env
```

Replace the password and secret placeholders, then start Ershu:

```bash
sudo systemctl enable --now ershu.target
sudo systemctl status ershu-api ershu-worker ershu-mcp
```

The first start brings up the infrastructure and applies database migrations before the application services. Scheduled polling remains off until enabled:

```bash
sudo systemctl enable --now ershu-poller.service
```

Follow service logs with:

```bash
journalctl -u ershu-api -u ershu-worker -u ershu-mcp -f
```

The [quick deployment guide](https://ershu.org/en/guide/quick-start) covers download verification, configuration, frontend installation, and acceptance checks.

## Worker and LSP

LSP is disabled by default. When `REPOSITORY_LSP_ENABLED=true`, Worker invokes Docker to run short-lived language-server containers. The `ershu` account must then be able to reach Docker, and Docker must be able to mount the repository directory.

Docker access is highly privileged. Review repository paths, image versions, resource limits, and dependency sources before enabling it. Environments that need a stronger boundary should not add Worker directly to the host Docker group.

## License

Apache License 2.0. See [LICENSE](LICENSE).
