---
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
<script src="http://opengist.url/user/gist-url.js"></script>

<!-- Dark mode: -->
<script src="http://opengist.url/user/gist-url.js?dark"></script>
```

### 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": "<div class=\"opengist-embed\" id=\"my-gist\">\n    <div class=\"html \">\n    \n        <div class=\"rounded-md border-1 border-gray-100 dark:border-gray-800 overflow-auto mb-4\">\n            <div class=\"border-b-1 border-gray-100 dark:border-gray-700 text-xs p-2 pl-4 bg-gray-50 dark:bg-gray-800 text-gray-400\">\n                <a target=\"_blank\" href=\"http://localhost:6157/thomas/my-gist#file-hello-md\"><span class=\"font-bold text-gray-700 dark:text-gray-200\">hello.md</span> · 21 B · Markdown</a>\n                <span class=\"float-right\"><a target=\"_blank\" href=\"http://localhost:6157\">Hosted via Opengist</a> · <span class=\"text-gray-700 dark:text-gray-200 font-bold\"><a target=\"_blank\" href=\"http://localhost:6157/thomas/my-gist/raw/HEAD/hello.md\">view raw</a></span></span>\n            </div>\n            \n            \n            \n            <div class=\"chroma markdown markdown-body p-8\"><h1>Welcome to Opengist</h1>\n</div>\n            \n\n        </div>\n    \n    </div>\n</div>\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
```
