Metadata-Version: 2.4
Name: ichec_django_core
Version: 8.6.1
Summary: Library of base Django app building blocks and utilities.
Author-email: Irish Centre for High End Computing <platformengineering@ichec.ie>
License: MIT
Project-URL: Repository, https://git.ichec.ie/platform-engineering/modules/ichec-web
Project-URL: Homepage, https://git.ichec.ie/platform-engineering/modules/ichec-web
Keywords: Web Application,Django
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: django>=6.0.9
Requires-Dist: markdown
Requires-Dist: pillow
Requires-Dist: pyyaml
Requires-Dist: pydantic
Requires-Dist: djangorestframework>=3.18
Requires-Dist: django-filter
Requires-Dist: django-countries
Requires-Dist: django-cors-headers
Requires-Dist: django-downloadview
Requires-Dist: django-prometheus>=2.5
Requires-Dist: prometheus-client>=0.20
Requires-Dist: mozilla-django-oidc
Requires-Dist: drf-spectacular>=0.30.0
Requires-Dist: django-fsm-2>=4.0
Requires-Dist: django-axes>=8
Requires-Dist: django-health-check>=4
Requires-Dist: nh3>=0.2.18
Requires-Dist: whitenoise>=6.12
Requires-Dist: pypdf[crypto]>=5
Provides-Extra: async
Requires-Dist: celery>=5.3; extra == "async"
Requires-Dist: redis>=5.0; extra == "async"
Provides-Extra: container
Requires-Dist: psycopg2-binary; extra == "container"
Requires-Dist: gunicorn; extra == "container"
Provides-Extra: s3
Requires-Dist: django-storages[s3]; extra == "s3"
Provides-Extra: keycloak
Requires-Dist: python-keycloak; extra == "keycloak"
Provides-Extra: codegen
Requires-Dist: datamodel-code-generator[ruff]==0.86.0; extra == "codegen"
Provides-Extra: workflows
Requires-Dist: django-simple-history>=3.13.0; extra == "workflows"
Provides-Extra: types
Requires-Dist: types-requests; extra == "types"
Provides-Extra: sentry
Requires-Dist: sentry-sdk[django]>=2; extra == "sentry"
Dynamic: license-file

# ICHEC Web

ICHEC Web is the reference ICHEC web portal. It is a working portal you can run
on your machine with one command, and the two libraries it is built from. Use
it to see what an ICHEC portal gives you, and as the starting point for your
own.

- `ichec-django-core`, on PyPI, is the backend. It gives a portal secure
  settings, members and organisations, sign-in through Keycloak, permissions,
  forms, workflows and a REST API.
- `ichec-angular-core`, on npm, is the frontend. It gives a portal pages to
  list, view, create and edit, and talks to the API through a client generated
  from the backend's [schema.yaml](schema.yaml).

![The portal's building blocks: workflows, forms, files, people, sign-in and background tasks over a secure foundation, all through a standards-based REST API](docs/diagrams/ichec-django-core.svg)

## Try the portal

You need Docker, or Podman with `podman compose`.

```shell
git clone https://git.ichec.ie/platform-engineering/modules/ichec-web.git
cd ichec-web
cp .env.example .env
docker compose up -d
```

The first start builds the portal, which takes several minutes. Then open
<http://localhost:8080/> and sign in as `admin`, password `admin`.
<http://localhost:8080/api/> is the API, and <http://localhost:8025/> shows
the emails the portal sends. `docker compose down -v` stops it and deletes
its data.

The portal's backend is in [app/](app), and its frontend is the test app in
[frontend/projects/test-app](frontend/projects/test-app).

## Build your own portal

A portal of your own uses the two libraries from PyPI and npm, and adds its
own models, pages and rules. Build each side with its guide:

- [Build a portal's backend](docs/backend.md) covers the settings, URLs,
  permissions, Keycloak sign-in, the optional features and testing.
- [Build a portal's frontend](frontend/README.md) covers the setup, the pages
  and the generated API client.

The example portal shows the result: [app/settings.py](app/settings.py) for
the backend, and the test app's
[app.config.ts](frontend/projects/test-app/src/app/app.config.ts) for the
frontend.

## Deploy a portal

The [sample web portal](https://git.ichec.ie/platform-engineering/products/sample-web-portal)
deploys a portal built on these libraries to a server, with HTTPS, Keycloak and
backups, using the `ichec.platform` Ansible collection. Start there when your
portal is ready to run somewhere other than your machine.

## Work on this repo

The backend is at the top of the repo, and the frontend in `frontend/`. CI runs
each side's checks only when that side changes, and both when `schema.yaml`
changes. [The frontend's README](frontend/README.md#work-on-the-library) has
its checks. For the backend, install the development tools and run the checks
that CI runs:

```shell
uv sync --group dev --extra async
uv run pytest
uv run ruff format --check .
uv run ruff check .
uv run mypy src
```

The tests run on SQLite locally, and on Postgres 18 in CI, as production
runs it. Postgres finds faults that SQLite hides, such as a foreign key to a
table that doesn't exist yet. To run them on Postgres, start a server and
run the `postgres` env:


```shell
podman run -d --rm --name ichec-test-postgres -p 5432:5432 -e POSTGRES_PASSWORD=password postgres:18
uv run tox -e postgres
```

`DJANGO_SQL_HOST`, `DJANGO_SQL_PORT`, `DJANGO_SQL_USER` and
`DJANGO_SQL_PASSWORD` point it at another server.

If you use [direnv](https://direnv.net/), run `direnv allow` once and the
environment activates when you enter the directory.

The `messages` check needs GNU gettext (`brew install gettext`). If you add or
change a string people read, mark it for translation, and update the
catalogue with `uv run tox -e messages`, and commit it. An app can check its
own catalogue the same way, with `python manage.py check_messages -l <code>`
run from its package.

If you change a model or serializer, regenerate the API schema and both
clients, and commit them:

```shell
uv run python manage.py generate_client ichec_django_core.client
cd frontend && npm run generate
```

## Licence

Copyright of the Irish Centre for High End Computing (ICHEC), released under the
MIT License. See [LICENSE](./LICENSE).
