gitea/opengist
0
0
Fork 0
mirror of https://github.com/thomiceli/opengist.git synced 2025-07-12 10:51:49 +02:00
Code Issues Packages Projects Releases Wiki Activity

Add documentation (#110)

Browse Source
This commit is contained in:
Thomas Miceli
2023-09-25 18:57:47 +02:00
committed by GitHub
parent 5b278e2e86
commit 72275e7573
10 changed files with 324 additions and 194 deletions
Download Patch File Download Diff File Expand all files Collapse all files

210
README.md
View File

@ -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)
![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/thomiceli/opengist?sort=semver)
![License](https://img.shields.io/github/license/thomiceli/opengist?color=blue)
![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/thomiceli/opengist/go.yml)
[![Go CI](https://github.com/thomiceli/opengist/actions/workflows/go.yml/badge.svg)](https://github.com/thomiceli/opengist/actions/workflows/go.yml)
[![Go Report Card](https://goreportcard.com/badge/github.com/thomiceli/opengist)](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).