--- obj: application website: https://opengist.io repo: https://github.com/thomiceli/opengist rev: 2025-05-19 --- # OpenGist Opengist is a self-hosted pastebin powered by Git. All snippets are stored in a Git repository and can be read and/or modified using standard Git commands, or with the web interface. It is similiar to GitHub Gist, but open-source and could be self-hosted. ## Features - Create public, unlisted or private snippets - Init / Clone / Pull / Push snippets via Git over HTTP or SSH - Syntax highlighting ; markdown & CSV support - Search code in snippets ; browse users snippets, likes and forks - Add topics to snippets - Embed snippets in other websites - Revisions history - Like / Fork snippets - Editor with indentation mode & size ; drag and drop files - Download raw files or as a ZIP archive - Retrieve snippet data/metadata via a JSON API - OAuth2 login with GitHub, GitLab, Gitea, and OpenID Connect - Avatars via Gravatar or OAuth2 providers - Light/Dark mode - Responsive UI - Enable or disable signups - Restrict or unrestrict snippets visibility to anonymous users ## Compose ```yml services: opengist: image: ghcr.io/thomiceli/opengist:1 container_name: opengist restart: unless-stopped ports: - "6157:6157" # HTTP port - "2222:2222" # SSH port, can be removed if you don't use SSH volumes: - "$HOME/.opengist:/opengist" environment: # OG_LOG_LEVEL: info # other configuration options ``` ## Configuration | YAML Config Key | Environment Variable | Default value | Description | | --------------------- | ----------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | log-level | OG_LOG_LEVEL | `warn` | Set the log level to one of the following: `debug`, `info`, `warn`, `error`, `fatal`. | | log-output | OG_LOG_OUTPUT | `stdout,file` | Set the log output to one or more of the following: `stdout`, `file`. | | external-url | OG_EXTERNAL_URL | none | Public URL to access to Opengist. | | opengist-home | OG_OPENGIST_HOME | home directory | Path to the directory where Opengist stores its data. | | secret-key | OG_SECRET_KEY | randomized 32 bytes | Secret key used for session store & encrypt MFA data on database. | | db-uri | OG_DB_URI | `opengist.db` | URI of the database. | | index | OG_INDEX | `bleve` | Define the code indexer (either `bleve`, `meilisearch`, or empty for no index). | | index.meili.host | OG_MEILI_HOST | none | Set the host for the Meiliseach server. | | index.meili.api-key | OG_MEILI_API_KEY | none | Set the API key for the Meiliseach server. | | git.default-branch | OG_GIT_DEFAULT_BRANCH | none | Default branch name used by Opengist when initializing Git repositories. If not set, uses the Git default branch name. More info [here](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup#_new_default_branch) | | sqlite.journal-mode | OG_SQLITE_JOURNAL_MODE | `WAL` | Set the journal mode for SQLite. More info [here](https://www.sqlite.org/pragma.html#pragma_journal_mode) | | http.host | OG_HTTP_HOST | `0.0.0.0` | The host on which the HTTP server should bind. | | http.port | OG_HTTP_PORT | `6157` | The port on which the HTTP server should listen. | | http.git-enabled | OG_HTTP_GIT_ENABLED | `true` | Enable or disable git operations (clone, pull, push) via HTTP. (`true` or `false`) | | metrics.enabled | OG_METRICS_ENABLED | `false` | Enable or disable Prometheus metrics endpoint at `/metrics` (`true` or `false`) | | ssh.git-enabled | OG_SSH_GIT_ENABLED | `true` | Enable or disable git operations (clone, pull, push) via SSH. (`true` or `false`) | | ssh.host | OG_SSH_HOST | `0.0.0.0` | The host on which the SSH server should bind. | | ssh.port | OG_SSH_PORT | `2222` | The port on which the SSH server should listen. | | ssh.external-domain | OG_SSH_EXTERNAL_DOMAIN | none | Public domain for the Git SSH connection, if it has to be different from the HTTP one. If not set, uses the URL from the request. | | ssh.keygen-executable | OG_SSH_KEYGEN_EXECUTABLE | `ssh-keygen` | Path to the SSH key generation executable. | | github.client-key | OG_GITHUB_CLIENT_KEY | none | The client key for the GitHub OAuth application. | | github.secret | OG_GITHUB_SECRET | none | The secret for the GitHub OAuth application. | | gitlab.client-key | OG_GITLAB_CLIENT_KEY | none | The client key for the GitLab OAuth application. | | gitlab.secret | OG_GITLAB_SECRET | none | The secret for the GitLab OAuth application. | | gitlab.url | OG_GITLAB_URL | `https://gitlab.com/` | The URL of the GitLab instance. | | gitlab.name | OG_GITLAB_NAME | `GitLab` | The name of the GitLab instance. It is displayed in the OAuth login button. | | gitea.client-key | OG_GITEA_CLIENT_KEY | none | The client key for the Gitea OAuth application. | | gitea.secret | OG_GITEA_SECRET | none | The secret for the Gitea OAuth application. | | gitea.url | OG_GITEA_URL | `https://gitea.com/` | The URL of the Gitea instance. | | gitea.name | OG_GITEA_NAME | `Gitea` | The name of the Gitea instance. It is displayed in the OAuth login button. | | oidc.provider-name | OG_OIDC_PROVIDER_NAME | none | The name of the OIDC provider | | oidc.client-key | OG_OIDC_CLIENT_KEY | none | The client key for the OpenID application. | | oidc.secret | OG_OIDC_SECRET | none | The secret for the OpenID application. | | oidc.discovery-url | OG_OIDC_DISCOVERY_URL | none | Discovery endpoint of the OpenID provider. | | ldap.url | OG_LDAP_URL | none | URL of the LDAP instance; if not set, LDAP authentication is disabled | | ldap.bind-dn | OG_LDAP_BIND_DN | none | Bind DN to authenticate against the LDAP. e.g: cn=read-only-admin,dc=example,dc=com | | ldap.bind-credentials | OG_LDAP_BIND_CREDENTIALS | none | The password for the Bind DN. | | ldap.search-base | OG_LDAP_SEARCH_BASE | none | The Base DN to start search from. e.g: ou=People,dc=example,dc=com | | ldap.search-filter | OG_LDAP_SEARCH_FILTER | none | The filter to search against (the format string %s will be replaced with the username). e.g: (uid=%s) | | custom.name | OG_CUSTOM_NAME | none | The name of your instance, to be displayed in the tab title | | custom.logo | OG_CUSTOM_LOGO | none | Path to an image, relative to $opengist-home/custom. | | custom.favicon | OG_CUSTOM_FAVICON | none | Path to an image, relative to $opengist-home/custom. | | custom.static-links | OG_CUSTOM_STATIC_LINK_#_(PATH,NAME) | none | Path and name to custom links, more info [here](custom-links.md). | ## Usage ### Init Gists via Git Opengist allows you to create new snippets via Git over HTTP. Simply init a new Git repository where your file(s) is/are located: ```shell git init git add . git commit -m "My cool snippet" ``` Then add this Opengist special remote URL and push your changes: ```shell git remote add origin http://localhost:6157/init git push -u origin master ``` Log in with your Opengist account credentials, and your snippet will be created at the specified URL: ```shell Username for 'http://localhost:6157': thomas Password for 'http://thomas@localhost:6157': Enumerating objects: 3, done. Counting objects: 100% (3/3), done. Delta compression using up to 8 threads Compressing objects: 100% (2/2), done. Writing objects: 100% (3/3), 416 bytes | 416.00 KiB/s, done. Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 remote: remote: Your new repository has been created here: http://localhost:6157/thomas/6051e930f140429f9a2f3bb1fa101066 remote: remote: If you want to keep working with your gist, you could set the remote URL via: remote: git remote set-url origin http://localhost:6157/thomas/6051e930f140429f9a2f3bb1fa101066 remote: To http://localhost:6157/init * [new branch] master -> master ``` ### Embed a Gist to your webpage To embed a Gist to your webpage, you can add a script tag with the URL of your gist followed by `.js` to your HTML page: ```html ``` ### Retrieve Gist as JSON To retrieve a Gist as JSON, you can add `.json` to the end of the URL of your gist: ```shell curl http://opengist.url/thomas/my-gist.json | jq '.' ``` It returns a JSON object with the following structure similar to this one: ```json { "created_at": "2023-04-12T13:15:20+02:00", "description": "", "embed": { "css": "http://localhost:6157/assets/embed-94abc261.css", "html": "
\n
\n \n
\n
\n hello.md · 21 B · Markdown\n Hosted via Opengist · view raw\n
\n \n \n \n

Welcome to Opengist

\n
\n \n\n
\n \n
\n
\n", "js": "http://localhost:6157/thomas/my-gist.js", "js_dark": "http://localhost:6157/thomas/my-gist.js?dark" }, "files": [ { "filename": "hello.md", "size": 21, "human_size": "21 B", "content": "# Welcome to Opengist", "truncated": false, "type": "Markdown" } ], "id": "my-gist", "owner": "thomas", "title": "hello.md", "uuid": "8622b297bce54b408e36d546cef8019d", "visibility": "public" } ``` ### Push Options Opengist has support for a few [Git push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt). These options are passed to `git push` command and can be used to change the metadata of a gist. #### Set URL ```shell git push -o url=mygist # Will set the URL to https://opengist.example.com/user/mygist ``` #### Change title ```shell git push -o title=Gist123 git push -o title="My Gist 123" ``` #### Change description ```shell git push -o description="This is my gist description" ``` #### Change visibility ```shell git push -o visibility=public git push -o visibility=unlisted git push -o visibility=private ```