121 lines
5.8 KiB
Markdown
121 lines
5.8 KiB
Markdown
# EcoSpecies-Atlas
|
|
|
|
Modern open-source follow-on to the legacy EcoSpecies application, built to ingest historical Species Life History materials and evolve into a maintainable public research platform.
|
|
|
|
## Repository layout
|
|
|
|
- `apps/api`: Python API and import logic
|
|
- `apps/web`: public web UI served by nginx
|
|
- `docs`: migration survey and roadmap
|
|
- `scripts`: Compose runtime scripts for bootstrapping the container-managed Python environment
|
|
- Docker named volume `python_venv`: container-managed Python virtual environment
|
|
- Docker named volume `pip_cache`: pip cache for container bootstrapping
|
|
- Docker named volume `postgres_data`: PostgreSQL data directory
|
|
- `var/sqlite`: host fallback for local non-Compose verification
|
|
|
|
## Runtime model
|
|
|
|
Docker Compose owns all runtime dependencies:
|
|
|
|
- PostgreSQL runs in a container with a Docker-managed named volume
|
|
- Python services run in `python:3.12-slim`
|
|
- the Python virtual environment is created in a Docker-managed volume mounted at `/workspace/.docker/venv`
|
|
- dependencies are installed from `apps/api/requirements.txt` inside that virtual environment
|
|
- the legacy corpus is mounted read-only from `../01-legacy-code-and-data`
|
|
|
|
No host Python packages are required for the Compose workflow.
|
|
|
|
## Start the stack
|
|
|
|
```bash
|
|
cd EcoSpecies-Atlas
|
|
docker compose up
|
|
```
|
|
|
|
Endpoints:
|
|
|
|
- web UI: `http://localhost:8080`
|
|
- API: `http://localhost:8000`
|
|
- PostgreSQL: `localhost:5432`
|
|
- liveness: `/healthz`
|
|
- readiness: `/readyz`
|
|
- auth session: `/api/auth/session`
|
|
- editor status: `/api/editor/status` (requires `editor` or `admin`)
|
|
- editor species list: `/api/editor/species` (requires `editor` or `admin`)
|
|
- editor workflow detail/update: `/api/editor/species/<slug>/workflow` (requires `editor` or `admin`)
|
|
- editor species detail: `/api/editor/species/<slug>` (requires `editor` or `admin`)
|
|
- editor editorial update: `/api/editor/species/<slug>/editorial` (requires `editor` or `admin`)
|
|
- editor section detail/update: `/api/editor/species/<slug>/sections/<position>` (requires `editor` or `admin`)
|
|
- editor audit history: `/api/editor/species/<slug>/audit` (requires `editor` or `admin`)
|
|
|
|
If those host ports are already in use, override them when starting Compose, for example:
|
|
|
|
```bash
|
|
ECOSPECIES_API_PORT=18000 ECOSPECIES_WEB_PORT=18080 docker compose up
|
|
```
|
|
|
|
## Host-visible state
|
|
|
|
All important runtime state is bind-mounted and visible on the host:
|
|
|
|
- source code and docs in this repo
|
|
- SQLite fallback database in `var/sqlite`
|
|
- optional SQLite fallback in `var/sqlite`
|
|
|
|
## Automated checks
|
|
|
|
Repository-host CI runs the repository-layer tests and the stubbed browser smoke test on pushes and change requests.
|
|
Contributor workflow guidance is in `CONTRIBUTING.md`.
|
|
|
|
When hosted on Forgejo, the current GitHub-compatible workflow layout can still be used. Forgejo Actions will look for workflows in `.forgejo/workflows`, and if that directory is absent it will fall back to `.github/workflows`. A Forgejo-native template is provided at `.forgejo/workflows/ci.yml.template`; copy it to `.forgejo/workflows/ci.yml` only after adapting the runner label and action source policy for the target instance. The activation checklist is in `docs/forgejo-activation.md`.
|
|
|
|
Run the repository-layer test suite with:
|
|
|
|
```bash
|
|
./scripts/check-api-tests.sh
|
|
```
|
|
|
|
Run the browser-level editor smoke test with:
|
|
|
|
```bash
|
|
./scripts/check-ui-smoke.sh
|
|
```
|
|
|
|
Run the browser-level smoke test against the real Compose stack with:
|
|
|
|
```bash
|
|
./scripts/check-ui-stack-smoke.sh
|
|
```
|
|
|
|
## Notes
|
|
|
|
- The importer seeds PostgreSQL from the legacy text corpus before the API starts and now synchronizes by slug instead of truncating the full dataset.
|
|
- Species missing from a later import payload are archived instead of deleted. Public endpoints hide archived records; editor endpoints can still inspect them.
|
|
- The editor species list supports `active`, `all`, and `archived` client-side filtering so archived records remain manageable in the UI.
|
|
- Editors can also archive or unarchive species explicitly from the editorial controls, with audit history recorded alongside other editorial changes.
|
|
- The API also supports a host-local SQLite fallback for direct verification when `ECOSPECIES_DATABASE_URL` is unset.
|
|
- PostgreSQL, the Python virtualenv, and the pip cache use Docker named volumes because bind-mounted runtime state is not reliable on CIFS-backed workspaces like this one.
|
|
- Initial editor auth uses `ECOSPECIES_AUTH_TOKENS` in the format `token:username:role[,token2:username2:role2]`, where `role` is `viewer`, `editor`, or `admin`.
|
|
- Editorial workflow state is persisted per species with `draft`, `review`, and `published` statuses. Public endpoints return only `published` records; editor endpoints can inspect and update all records.
|
|
- Editors can curate top-level metadata and section content from the web UI, and every editorial or section change is recorded in per-species audit history.
|
|
- Summary authoring guidance for future FLELMR-compatible records is in `docs/flelmr-authoring.md`.
|
|
- Legacy survey and roadmap artifacts are in `docs/`.
|
|
|
|
## Governance And Operations
|
|
|
|
The repository host, such as GitHub or Forgejo, is used for source control, change requests, code review, and CI checks. It is not part of the application runtime.
|
|
|
|
EcoSpecies-Atlas itself runs through Docker Compose, the Python API, nginx, and PostgreSQL. Import jobs, editor workflows, and browser access all depend on the application stack, not on the repository host.
|
|
|
|
In practice, the repository host is responsible for change management:
|
|
|
|
- storing the code, docs, workflow definitions, and test harnesses
|
|
- running CI checks on pushes and change requests
|
|
- supporting review and merge workflows
|
|
|
|
In practice, the application stack is responsible for operations:
|
|
|
|
- serving the web UI and API
|
|
- persisting editorial and import state
|
|
- running imports and editor workflows
|