ansible-roles/hister
Watch
5
0
Fork
You've already forked hister
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
Ansible role for configuring rootless podman based hister
2 commits 1 branch 0 tags 7.6 KiB
Find a file
Exact
Repository files (latest commit first)
Filename Latest commit message Latest commit date
agent 32b8767cae Fix OAuth provider name: hister only accepts github/google/oidc 
The oauth map key is validated against a fixed enum, and the authentik
app allows the strict redirect URI ?provider=oidc - so the env prefix
becomes HISTER__SERVER__OAUTH__OIDC__*.

Agent: pi
2026-10-21 08:32:41 +00:00
defaults/main Fix OAuth provider name: hister only accepts github/google/oidc 2026-10-21 08:32:41 +00:00
meta Add hister role: rootless podman deployment with postgres and authentik OIDC 2026-10-21 08:27:23 +00:00
tasks Add hister role: rootless podman deployment with postgres and authentik OIDC 2026-10-21 08:27:23 +00:00
.gitignore Add hister role: rootless podman deployment with postgres and authentik OIDC 2026-10-21 08:27:23 +00:00
README.md Fix OAuth provider name: hister only accepts github/google/oidc 2026-10-21 08:32:41 +00:00

README.md

ansible-roles-hister

Role for deploying Hister — a private search engine that indexes visited pages and files, with web UI, CLI and a built-in MCP server — under rootless Podman with PostgreSQL.

Hister is authored by asciimoo (AGPLv3):

Task Configuration

Deployment Example

- name: Setup proxy and service
  hosts: somehost
  become: true
  roles:
    - role: hister
    - role: caddy
      caddy_sites:
        - name: hister
          url: hister.boxcar.sh
          dns: cloudflare
          srv: 4433
          log: true

Host loopback ports (defaults): 127.0.0.1:4433 (web), 127.0.0.1:5442 (postgres). The server talks to postgres over pod-local loopback; the DSN is built from hister_database_pass (vault).

Required variables (vault)

  • hister_database_pass — postgres password
  • hister_oidc_client_id / hister_oidc_client_secret / hister_oidc_configuration_url — authentik app "hister"

OAuth discovery uses configuration_url; the authentik app must allow the redirect URI https://<base_url>/api/oauth/callback?provider=oidc (the provider name comes from the HISTER__SERVER__OAUTH__OIDC__* env prefix). server.oauth_only is enabled, so password login is disabled and SSO is required for the UI; token auth (API/MCP) is unaffected.

Configuration is environment-based (HISTER__<SECTION>__<KEY> maps to the config path, e.g. HISTER__SERVER__DATABASE); add overrides via hister_deploy_env in group_vars.

User management (multi-user mode)

app.user_handling is enabled. Manage users from inside the container:

sudo -iu <service-user> podman exec hister-server /hister/hister user create USERNAME --offline --admin
sudo -iu <service-user> podman exec hister-server /hister/hister user show USERNAME --show-token

user create --offline --admin prints a bootstrap token for the new admin. user show --show-token requires an admin token (HISTER__APP__ACCESS_TOKEN=<token> env or config).

MCP

Hister serves MCP (Streamable HTTP) at <base_url>/mcp; authenticate with Authorization: Bearer <access-token> using a user's access token. Record the URL in group_vars/all/mcp.yml and keep tokens in vault.

Deployment and Removal

./run.sh deploy actual --tags hister --limit <host>
./run.sh deploy actual --tags hister --limit <host> --extra-vars "hister_state=absent hister_pod_state=absent"