Skip to content
Opengist

Opengist

Snippets with history, shareable by link.

Opengist is a self-hosted take on GitHub Gist. Each gist is a git repository with one or more files, so every edit is a commit, older revisions stay one click away, and a gist can be cloned, pulled and pushed like any other repo. Gists are public, unlisted or private; public and unlisted ones render for anyone who has the link, which is the point of a snippet service. A full-text index covers file names and content, and there is a REST API alongside the web UI.

It fills a different slot from PrivateBin: PrivateBin is the throwaway, end-to-end-encrypted paste that expires; Opengist is where a snippet worth keeping lives, versioned and findable later. Anything that has grown into a project belongs in Gitea instead.

Alternatives considered

Cloud Hosted

ToolOpen SourceFree TierMonthly Cost
GitHub GistNoYesFree; tied to a GitHub account
GitLab SnippetsPartlyYesFree on gitlab.com

Self Hosted

ToolOpen SourceFull FeaturesNotes
PrivateBinYesYesAlready deployed; encrypted and ephemeral, no history or search
GiteaYesYesAlready deployed; a repository per snippet is too heavy, and Gitea has no gist feature
HastebinYesYesPaste only, no accounts or versions

Installation

Architecture

  • Deployment: Single opengist deployment in the opengist namespace, Recreate strategy (the data volume is ReadWriteOnce and the session store lives on it)
  • Image: ghcr.io/thomiceli/opengist, version and digest pinned, updated by Renovate
  • Database: CNPG PostgreSQL cluster from the shared cnpg component, OG_DB_URI from the cnpg-app secret. It holds users, gist metadata and the admin settings, nothing else
  • Storage: Longhorn PVC opengist-data (2Gi, longhorn-encrypted) mounted as Opengist’s home /opengist: the bare git repositories under repos/, the bleve search index, the filesystem session store, avatars and uploads
  • Networking: ClusterIP service on port 6157, HTTPRoute via the public gateway on opengist.web.domain.tld. Git runs over HTTPS only; the built-in SSH server is disabled because the Envoy gateway has no TCP listener for it

Security

  • Runs as 10001, runAsNonRoot: true, readOnlyRootFilesystem: true, allowPrivilegeEscalation: false, capabilities dropped. The image’s entrypoint only needs root to usermod and chown; started as non-root it execs the binary directly
  • PVC and CNPG volumes encrypted at rest with SOPS-managed keys
  • OG_SECRET_KEY comes from a SOPS secret rather than the file Opengist would otherwise generate in its home. It signs sessions and encrypts TOTP secrets in the database, so it has to be exactly 32 bytes, and keeping it in Git means a restored database never outlives its key
  • Ingress only from the public gateway’s Envoy pods; no egress beyond the network-policy baseline (the Keycloak calls go through the gateway)
  • The password registration path /-/register is redirected to the login page at the gateway, see User Management

Updates

Managed by Renovate; the digest pin moves with the tag. Opengist migrates its schema on start. Release notes are worth a glance before a minor bump: 1.15 moved the reserved routes under /-/ (for example /-/login, /-/all), which is also where the gateway redirect points.

Data Management

  • Database: CNPG cluster, dumped with pg_dump by the backups-cnpg PreBackupPod
  • PVC: opengist-data, annotated for k8up; the git repositories are the irreplaceable part, the search index is rebuilt from them (admin panel → Rebuild search index)
  • Backups: k8up Schedules to Hetzner and Backblaze via restic, covering the PVC and the database dump. The backup job runs as 10001, the owner of the repositories and of the 0600 session files

User Management

Login is Keycloak only, client opengist in the domain.tld realm with the role-gated browser flow; opengist.user is mapped to the developers group. The app’s workspace creates the client (spec.oidc, PKCE S256, since Opengist always sends a challenge) and exports the secret to workspace-outputs, which the Deployment reads as OG_OIDC_SECRET. The first Keycloak login asks for an Opengist username and creates the account. The account with id 1 becomes admin, and only developers can get that far.

The password side is closed at the gateway: Opengist keeps /-/register open until an admin ticks Disable login form, and the first account it creates becomes admin, so on a public hostname that window is a takeover risk. The HTTPRoute sends /-/register to /-/login before Opengist ever sees it. No password account can exist, and the admin-panel toggles that follow are cosmetic.

Configuration Management

  • Runtime settings are OG_* env vars in the base Deployment and the talos patch: external URL, OIDC provider, SSH off, default branch main, stdout-only logging
  • The instance toggles (Disable signup, Require login, Allow individual gists without login, Disable login form, Disable Gravatar) live only in the database and are set once in the admin panel; Opengist has no env var or config key for them

Administration

The admin panel (/-/admin-panel, visible to admins) shows instance stats, lists users and gists, and runs the maintenance jobs by hand (some also run on a schedule): Rebuild search index, Garbage collect all git repositories, Synchronize all gists previews and languages, Reset Git server hooks. /healthcheck answers 200 with a small JSON body while the database responds and 503 when it does not; the readiness probe and Gatus use it, the liveness probe deliberately only checks the port.

The database dump and the PVC snapshot come from the same k8up run but are not taken atomically, so a restore can leave a gist row without its repository or a repository without its row. Two admin actions clean that up, and both delete: Delete gists without a repository on disk and Delete repositories without a gist in the database. Look at what is orphaned before running either.

Usage

Create a gist in the web UI with one or more files; the language is guessed from the extension and rendered with syntax highlighting (Markdown and CSV render as documents). Visibility per gist: public (listed and searchable), unlisted (link only) or private (only you). Each gist has a clone URL:

git clone https://opengist.web.domain.tld/<user>/<gist-id>.git

Pushing needs credentials. Every account is a Keycloak account without an Opengist password, so create an access token under Settings → Access tokens and use it as the password in git, with the Opengist username. The same token authenticates the REST API as Authorization: Bearer og_… (spec at /api/openapi.yaml). Raw and download links for each file are on the gist’s page.

Cluster-specific deviations from the above live in the per-cluster README — see k8s/apps/opengist/talos/README.md.

Cluster Deployment

Opengist — Talos cluster

Deviations from defaults

  • Public gateway (opengist.web.domain.tld) — gists are shared by link with people outside the homelab, so the route hangs off public behind the realm-wide DE geo allowlist; the ingress policy admits only that gateway’s Envoy pods.
  • /-/register redirected at the gateway — Opengist leaves password registration open until an admin disables the login form, and the first account becomes admin. http-route.yaml sends the path to /-/login, so accounts only ever come from the Keycloak login.
  • Keycloak gated on developers — the workspace client opengist (workspace/patch-oidc.yaml, PKCE S256) maps opengist.user to developers, which today is Johnny alone, so the first login is his and becomes admin (Opengist promotes account id 1 when no OG_OIDC_ADMIN_GROUP is set). Widening it to family is a one-line change; set an admin group first if that happens before the first login.
  • No SSH — OG_SSH_GIT_ENABLED=disabled; git runs over HTTPS with access tokens because the public gateway has no TCP listener for port 2222.
  • OG_SECRET_KEY from SOPS (secret-opengist.yaml, exactly 32 characters) instead of the generated opengist-secret.key on the PVC, so a database restore never outlives its key.
  • Postgres via the cnpg component — users, gist metadata and settings; the git repositories, search index and session store live on the 2Gi opengist-data volume.
  • Runs as 10001 — the image only needs root to usermod/chown; the k8up job runs as the same uid (backups/patch-schedule.yaml) to read the 0600 session files and the repositories.
  • Backup slots 03:06 / 05:09 — the 3-minute grid is full, so this app shares a grid minute with another namespace, as openbao does.
  • Tier 3, first-estimate requests — 96Mi/256Mi for the app, 128Mi/256Mi for Postgres; re-measure after a week.

Bootstrap

  1. Log in through Keycloak at https://opengist.web.domain.tld/oauth/openid-connect, pick the username (johnny); that account is admin.
  2. Admin panel → Configuration: tick Disable login form (hides the dead password form) and Disable Gravatar (the browser would otherwise send e-mail hashes to gravatar.com). Leave Disable signup off: it also blocks first Keycloak logins.
  3. Decide visibility for anonymous visitors: as installed, public gists, user pages and /-/all are browsable without login. Require login plus Allow individual gists without login keeps shared links working while hiding the lists.

Kubernetes Metadata

  • Image: ghcr.io/thomiceli/opengist:1.15.3@sha256:f5dd39cc9409b4006f8b090e5f9ed042cdb736d28a06b4f985c674dacafc94d5
Rendered manifests (kustomize build)
apiVersion: apps/v1
kind: Deployment
metadata:
  annotations:
    kustomize.toolkit.fluxcd.io/force: enabled
  labels:
    app.kubernetes.io/name: opengist
  name: opengist
  namespace: opengist
spec:
  replicas: 1
  revisionHistoryLimit: 2
  selector:
    matchLabels:
      app.kubernetes.io/name: opengist
  strategy:
    rollingUpdate:
    type: Recreate
  template:
    metadata:
      labels:
        app.kubernetes.io/name: opengist
    spec:
      automountServiceAccountToken: false
      containers:
      - env:
        - name: OG_EXTERNAL_URL
          value: https://opengist.web.domain.tld
        - name: OG_SSH_GIT_ENABLED
          value: disabled
        - name: OG_GIT_DEFAULT_BRANCH
          value: main
        - name: OG_SECRET_KEY
          valueFrom:
            secretKeyRef:
              key: secret-key
              name: opengist
        - name: OG_OIDC_PROVIDER_NAME
          value: Keycloak
        - name: OG_OIDC_CLIENT_KEY
          value: opengist
        - name: OG_OIDC_SECRET
          valueFrom:
            secretKeyRef:
              key: client-secret
              name: workspace-outputs
        - name: OG_OIDC_DISCOVERY_URL
          value: https://keycloak.web.domain.tld/realms/domain.tld/.well-known/openid-configuration
        - name: OG_DB_URI
          valueFrom:
            secretKeyRef:
              key: uri
              name: cnpg-app
        - name: OG_HTTP_PORT
          value: '6157'
        - name: OG_LOG_LEVEL
          value: info
        - name: OG_LOG_OUTPUT
          value: stdout
        image: ghcr.io/thomiceli/opengist:1.15.3@sha256:f5dd39cc9409b4006f8b090e5f9ed042cdb736d28a06b4f985c674dacafc94d5
        livenessProbe:
          initialDelaySeconds: 10
          periodSeconds: 20
          tcpSocket:
            port: 6157
          timeoutSeconds: 5
        name: opengist
        ports:
        - containerPort: 6157
          name: web
          protocol: TCP
        readinessProbe:
          httpGet:
            path: /healthcheck
            port: 6157
          initialDelaySeconds: 10
          periodSeconds: 10
          timeoutSeconds: 5
        resources:
          limits:
            memory: 256Mi
          requests:
            cpu: 25m
            memory: 96Mi
        securityContext:
          allowPrivilegeEscalation: false
          capabilities:
            drop:
            - ALL
          privileged: false
          readOnlyRootFilesystem: true
        volumeMounts:
        - mountPath: /opengist
          name: opengist-data
        - mountPath: /tmp
          name: tmp
      priorityClassName: tier-3
      securityContext:
        fsGroup: 10001
        fsGroupChangePolicy: OnRootMismatch
        runAsGroup: 10001
        runAsNonRoot: true
        runAsUser: 10001
        seccompProfile:
          type: RuntimeDefault
      volumes:
      - name: opengist-data
        persistentVolumeClaim:
          claimName: opengist-data
      - emptyDir: {}
        name: tmp
Last updated on