One platform. Your own tool.

Try Hello first

Run these commands from the repository root. You need Python 3.12–3.14, uv and Docker Compose.

uv sync --project deploy --frozen
uv run --project deploy ergon-deploy validate deploy/examples/hello.yaml
uv run --project deploy ergon-deploy render deploy/examples/hello.yaml
docker compose --project-directory deploy/out/hello up -d --build

Open https://localhost:8443/, trust the local development certificate, and sign in as developer@example.org using the initial password in deploy/out/hello/credentials.txt. Change it when prompted, then open Hello from your workspace.

About the installed Hello module →

Build your own module in six steps

1. Copy the small example

   Start from modules/hello/. Give the directory, Python package and project their own names. Regenerate its lockfile with uv lock --project modules/your-module.

2. Declare the tool

   Edit ergon-module.json: module ID, names, audiences, permissions, navigation and introduction. All paths are relative to the module: /help becomes /m/hello/help for Hello.

   See the key parts of Hello’s manifest

   {
     "id": "hello",
     "permissions": [{
       "id": "hello.read",
       "label": {"en": "Open Hello"},
       "default_roles": ["staff", "viewer"]
     }],
     "nav": [{
       "path": "/", "label": {"en": "Hello"}, "permission": "hello.read"
     }],
     "public_paths": ["/health", "/help", "/help/style.css"]
   }

   This is an excerpt. Copy the complete example manifest, including contract, version, introduction and blocked_paths.

3. Verify access, then run your logic

   Use ModuleSettings, AssertionVerifier, ErgonAuth.require("hello.read") and EnablementCache. The example’s src/ergon_hello/app.py shows the complete implementation. Never trust plain user or organization headers.

4. Explain the tool

   Keep /help read-only and public. Explain who it’s for, what they need and what they get. Load /_ergon/shell.js for the shared header. Use ERGON_BASE_PATH for module links and assets.

5. Register and install

   Add its manifest and Docker build to deploy/modules.yaml. Select its ID in an installation’s modules list and in each allowed organization’s modules list. Render and start that installation. These are explicit configuration steps; copying a folder alone does not install a module.

6. Test the boundary

   Check that the guide is public, private pages reject invalid assertions, disabled organizations and missing permissions, and displayed names are escaped. Rename the example’s permission and module IDs in its tests too.

Keep the first version small

Hello is a staff example with one read permission and no writes. Add a module-owned database only when you need storage. For writes, add permission checks, SDK CSRF validation and an origin check; Notices is the fuller example. Citizen links need their own scoped access mechanism.

For an existing installation, follow the re-rendering procedure in deploy/OPERATIONS.md, including database initialization when adding storage.