Metadata-Version: 2.5
Name: percival-server
Version: 0.1.2
Summary: Self-hosted control panel for Celery: live schedules, run history, stale-worker safety.
Project-URL: Homepage, https://percivalhq.dev
Project-URL: Documentation, https://percivalhq.dev
Project-URL: Source, https://github.com/RijinRaju/percival
Project-URL: Issues, https://github.com/RijinRaju/percival/issues
Author: Rijin Raju
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Celery
Classifier: Framework :: FastAPI
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: alembic>=1.13
Requires-Dist: argon2-cffi>=23.1
Requires-Dist: celery-redbeat>=2.0
Requires-Dist: celery[redis]>=5.3
Requires-Dist: cryptography>=42
Requires-Dist: fastapi>=0.110
Requires-Dist: percival>=0.1.2
Requires-Dist: redis>=4.5
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: uvicorn[standard]>=0.29
Provides-Extra: dev
Requires-Dist: fakeredis>=2.20; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

<img src="https://raw.githubusercontent.com/RijinRaju/percival/main/brand/percival-tile.png" width="72" height="72" alt="Percival logo">

# percival-server

The panel for [Percival](https://github.com/RijinRaju/percival), a
self-hosted control panel for Celery. It provides the web UI and API for
managing RedBeat schedules, run history, worker versions and the audit log.

Your Celery project needs the [`percival`](https://pypi.org/project/percival/)
client too.

## Run it

The easiest way is the Docker image, which has the UI built in:

```
docker run -d -p 8080:8080 -v percival:/data \
  -e PERCIVAL_REDIS_URL=redis://redis:6379/0 \
  -e PERCIVAL_ADMIN_PASSWORD=pick-a-long-one \
  ghcr.io/rijinraju/percival
```

Or from PyPI:

```
pip install percival-server
PERCIVAL_REDIS_URL=redis://localhost:6379/0 PERCIVAL_ADMIN_PASSWORD=pick-a-long-one percival-server
```

Then open http://localhost:8080 and log in as `admin`.

| env | default | |
|---|---|---|
| `PERCIVAL_REDIS_URL` | none | where RedBeat and the client keep their keys |
| `PERCIVAL_BROKER_URL` | the Redis URL | set it when the broker isn't Redis (`CELERY_BROKER_URL` works too) |
| `PERCIVAL_ADMIN_USERNAME` / `PERCIVAL_ADMIN_PASSWORD` | `admin` / none | creates the first admin if nobody exists yet |
| `PERCIVAL_SECRET_KEY` | generated into the data dir | |
| `PERCIVAL_DATA_DIR` | `./data` | SQLite database and the generated key |
| `PERCIVAL_DATABASE_URL` | SQLite in the data dir | Postgres works too |
| `PERCIVAL_HOST` / `PERCIVAL_PORT` | `127.0.0.1` / `8080` | |
| `PERCIVAL_SECURE_COOKIES` | on | turn it off only for plain http on localhost |

Every setting is optional. If you leave out the URLs or the admin, the first
visit asks for them.

Put the panel behind a reverse proxy with TLS if anyone besides you will use
it. The [full README](https://github.com/RijinRaju/percival#readme) has the
rest.
