mirror of
https://github.com/thomiceli/opengist.git
synced 2025-07-11 18:31:51 +02:00
Add documentation (#110)
This commit is contained in:
210
README.md
210
README.md
@ -1,63 +1,42 @@
|
||||
# Opengist
|
||||
|
||||
<img height="108px" src="https://raw.githubusercontent.com/thomiceli/opengist/a9dd531f676d01b93bb6bd70751a69382ca563b0/public/opengist.svg" alt="Opengist" align="right" />
|
||||
|
||||
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](https://gist.github.com/), but open-source and could be self-hosted.
|
||||
|
||||
[Documentation](/docs) • [Demo](https://opengist.thomice.li)
|
||||
|
||||
|
||||

|
||||

|
||||

|
||||
[](https://github.com/thomiceli/opengist/actions/workflows/go.yml)
|
||||
[](https://goreportcard.com/report/github.com/thomiceli/opengist)
|
||||
|
||||
A self-hosted pastebin **powered by Git**. [Try it here](https://opengist.thomice.li).
|
||||
|
||||
* [Features](#features)
|
||||
* [Install](#install)
|
||||
* [With Docker](#with-docker)
|
||||
* [From source](#from-source)
|
||||
* [Configuration](#configuration)
|
||||
* [Via YAML file](#configuration-via-yaml-file)
|
||||
* [Via Environment Variables](#configuration-via-environment-variables)
|
||||
* [Administration](#administration)
|
||||
* [Use Nginx as a reverse proxy](#use-nginx-as-a-reverse-proxy)
|
||||
* [Use Fail2ban](#use-fail2ban)
|
||||
* [Configure OAuth](#configure-oauth)
|
||||
* [License](#license)
|
||||
|
||||
## Features
|
||||
|
||||
* Create public, unlisted or private snippets
|
||||
* Clone / Pull / Push snippets **via Git** over HTTP or SSH
|
||||
* [Init](/docs/usage/init-via-git.md) / Clone / Pull / Push snippets **via Git** over HTTP or SSH
|
||||
* Revisions history
|
||||
* Syntax highlighting ; markdown & CSV support
|
||||
* Like / Fork snippets
|
||||
* Search for snippets ; browse users snippets, likes and forks
|
||||
* Editor with indentation mode & size ; drag and drop files
|
||||
* Download raw files or as a ZIP archive
|
||||
* OAuth2 login with GitHub, 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
|
||||
* Admin panel : delete users/gists; clean database/filesystem by syncing gists
|
||||
* SQLite database
|
||||
* Logging
|
||||
* Docker support
|
||||
* [More...](/docs/index.md#features)
|
||||
|
||||
#### Todo
|
||||
|
||||
- [ ] Translation
|
||||
- [ ] Code/text search
|
||||
- [ ] Embed snippets
|
||||
- [ ] Tests
|
||||
- [ ] Filesystem/Redis support for user sessions
|
||||
- [ ] Have a cool logo
|
||||
|
||||
## Install
|
||||
## Quick start
|
||||
|
||||
### With Docker
|
||||
|
||||
Docker [images](https://github.com/thomiceli/opengist/pkgs/container/opengist) are available for each release :
|
||||
|
||||
```shell
|
||||
docker pull ghcr.io/thomiceli/opengist:1.4
|
||||
docker pull ghcr.io/thomiceli/opengist:1
|
||||
```
|
||||
|
||||
It can be used in a `docker-compose.yml` file :
|
||||
@ -105,167 +84,12 @@ make
|
||||
|
||||
Opengist is now running on port 6157, you can browse http://localhost:6157
|
||||
|
||||
## Configuration
|
||||
|
||||
Opengist provides flexible configuration options through either a YAML file and/or environment variables.
|
||||
You would only need to specify the configuration options you want to change — for any config option left untouched, Opengist will simply apply the default values.
|
||||
## Documentation
|
||||
|
||||
<details>
|
||||
<summary>Configuration option list</summary>
|
||||
The documentation is available in [/docs](/docs) directory.
|
||||
|
||||
| YAML Config Key | Environment Variable | Default value | Description |
|
||||
| --------------------- | ------------------------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| log-level | OG_LOG_LEVEL | `warn` | Set the log level to one of the following: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`. |
|
||||
| external-url | OG_EXTERNAL_URL | none | Public URL for the Git HTTP/SSH connection. If not set, uses the URL from the request. |
|
||||
| opengist-home | OG_OPENGIST_HOME | home directory | Path to the directory where Opengist stores its data. |
|
||||
| db-filename | OG_DB_FILENAME | `opengist.db` | Name of the SQLite database file. |
|
||||
| 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`) |
|
||||
| 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. |
|
||||
| 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. |
|
||||
| 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. |
|
||||
|
||||
</details>
|
||||
|
||||
### Configuration via YAML file
|
||||
|
||||
The configuration file must be specified when launching the application, using the `--config` flag followed by the path to your YAML file.
|
||||
|
||||
```shell
|
||||
./opengist --config /path/to/config.yml
|
||||
```
|
||||
|
||||
You can start by copying and/or modifying the provided [config.yml](config.yml) file.
|
||||
|
||||
### Configuration via Environment Variables
|
||||
|
||||
Usage with Docker Compose :
|
||||
|
||||
```yml
|
||||
services:
|
||||
opengist:
|
||||
# ...
|
||||
environment:
|
||||
OG_LOG_LEVEL: "info"
|
||||
# etc.
|
||||
```
|
||||
Usage via command line :
|
||||
|
||||
```shell
|
||||
OG_LOG_LEVEL=info ./opengist
|
||||
```
|
||||
|
||||
## Administration
|
||||
|
||||
### Use Nginx as a reverse proxy
|
||||
|
||||
Configure Nginx to proxy requests to Opengist. Here is an example configuration file :
|
||||
```
|
||||
server {
|
||||
listen 80;
|
||||
server_name opengist.example.com;
|
||||
|
||||
location / {
|
||||
proxy_pass http://127.0.0.1:6157;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then run :
|
||||
```shell
|
||||
service nginx restart
|
||||
```
|
||||
|
||||
### Use Fail2ban
|
||||
|
||||
Fail2ban can be used to ban IPs that try to bruteforce the login page.
|
||||
Log level must be set at least to `warn`.
|
||||
|
||||
Add this filter in `etc/fail2ban/filter.d/opengist.conf` :
|
||||
```ini
|
||||
[Definition]
|
||||
failregex = Invalid .* authentication attempt from <HOST>
|
||||
ignoreregex =
|
||||
```
|
||||
|
||||
Add this jail in `etc/fail2ban/jail.d/opengist.conf` :
|
||||
```ini
|
||||
[opengist]
|
||||
enabled = true
|
||||
filter = opengist
|
||||
logpath = /home/*/.opengist/log/opengist.log
|
||||
maxretry = 10
|
||||
findtime = 3600
|
||||
bantime = 600
|
||||
banaction = iptables-allports
|
||||
port = anyport
|
||||
```
|
||||
|
||||
Then run
|
||||
```shell
|
||||
service fail2ban restart
|
||||
```
|
||||
|
||||
## Configure OAuth
|
||||
|
||||
Opengist can be configured to use OAuth to authenticate users, with GitHub, Gitea, or OpenID Connect.
|
||||
|
||||
<details>
|
||||
<summary>Integrate Github</summary>
|
||||
|
||||
* Add a new OAuth app in your [Github account settings](https://github.com/settings/applications/new)
|
||||
* Set 'Authorization callback URL' to `http://opengist.domain/oauth/github/callback`
|
||||
* Copy the 'Client ID' and 'Client Secret' and add them to the configuration :
|
||||
```yaml
|
||||
github.client-key: <key>
|
||||
github.secret: <secret>
|
||||
```
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Integrate Gitea</summary>
|
||||
|
||||
* Add a new OAuth app in Application settings from the [Gitea instance](https://gitea.com/user/settings/applications)
|
||||
* Set 'Redirect URI' to `http://opengist.domain/oauth/gitea/callback`
|
||||
* Copy the 'Client ID' and 'Client Secret' and add them to the configuration :
|
||||
```yaml
|
||||
gitea.client-key: <key>
|
||||
gitea.secret: <secret>
|
||||
# URL of the Gitea instance. Default: https://gitea.com/
|
||||
gitea.url: http://localhost:3000
|
||||
```
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Integrate OpenID</summary>
|
||||
|
||||
* Add a new OAuth app in Application settings of your OIDC provider
|
||||
* Set 'Redirect URI' to `http://opengist.domain/oauth/openid-connect/callback`
|
||||
* Copy the 'Client ID', 'Client Secret', and the discovery endpoint, and add them to the configuration :
|
||||
```yaml
|
||||
oidc.client-key: <key>
|
||||
oidc.secret: <secret>
|
||||
# Discovery endpoint of the OpenID provider. Generally something like http://auth.example.com/.well-known/openid-configuration
|
||||
oidc.discovery-url: http://auth.example.com/.well-known/openid-configuration
|
||||
```
|
||||
</details>
|
||||
|
||||
## License
|
||||
|
||||
Opengist is licensed under the [AGPL-3.0 license](LICENSE).
|
||||
Opengist is licensed under the [AGPL-3.0 license](/LICENSE).
|
||||
|
Reference in New Issue
Block a user