Ershu

中文

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.

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

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:

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

Deployment bundle contents

Install on a Linux server

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

/opt/ershu/releases/<tag>

Enter the extracted directory and run:

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:

/etc/ershu/.env
/etc/ershu/compose.env

Replace the password and secret placeholders, then start Ershu:

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:

sudo systemctl enable --now ershu-poller.service

Follow service logs with:

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

The quick deployment guide 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.