From 5fa48241f2c3b4df5359f22fdb8b9df9b5ba32ff Mon Sep 17 00:00:00 2001 From: casjay Date: Fri, 12 Jun 2026 05:55:25 -0400 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Update=20README=20with=20complet?= =?UTF-8?q?e=20opengist=20documentation=20=F0=9F=93=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrote the README from a generic boilerplate to accurate, complete documentation reflecting the actual container configuration. - README.md: Replace placeholder content with full project docs — description of OpenGist (self-hosted Git-backed pastebin), dockermgr install, manual docker run with correct ports (80 HTTP + 7823 SSH), docker-compose example, volumes/ports/env var tables, OAuth2 config section with callback URL pattern, and development/build instructions README.md --- README.md | 182 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 126 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 3999dc2..3c4bada 100644 --- a/README.md +++ b/README.md @@ -1,79 +1,149 @@ -## 👋 Welcome to opengist 🚀 +# opengist -opengist README - - -## Install my system scripts +A containerized [OpenGist](https://github.com/thomiceli/opengist) — a self-hosted pastebin powered by Git. Create, share, and fork code snippets with full Git history, HTTP clone, SSH push/pull, and OAuth2 login via GitHub, GitLab, Gitea, or OpenID Connect. Built on Alpine Linux with SQLite storage and no external database required. + +--- + +## 📦 Install + +### Via dockermgr (recommended) ```shell - sudo bash -c "$(curl -q -LSsf "https://github.com/systemmgr/installer/raw/main/install.sh")" - sudo systemmgr --config && sudo systemmgr install scripts -``` - -## Automatic install/update - -```shell +sudo bash -c "$(curl -q -LSsf "https://github.com/systemmgr/installer/raw/main/install.sh")" +sudo systemmgr --config && sudo systemmgr install scripts dockermgr update opengist ``` - -## Install and run container - + +### Manual docker run + ```shell -dockerHome="/var/lib/srv/$USER/docker/casjaysdevdocker/opengist/latest/volumes" -mkdir -p "$dockerHome" -git clone "https://github.com/dockermgr/opengist" "$HOME/.local/share/CasjaysDev/dockermgr/opengist" -cp -Rfva "$HOME/.local/share/CasjaysDev/dockermgr/opengist/volumes/." "$dockerHome/" docker run -d \ ---restart always \ ---privileged \ ---name casjaysdevdocker-opengist-latest \ ---hostname opengist \ --e TZ=${TIMEZONE:-America/New_York} \ --v "$dockerHome/data:/data:z" \ --v "$dockerHome/config:/config:z" \ --p 80:80 \ -casjaysdevdocker/opengist:latest + --restart always \ + --name casjaysdevdocker-opengist-latest \ + --hostname opengist \ + -e TZ=${TIMEZONE:-America/New_York} \ + -v /var/lib/srv/$USER/docker/casjaysdevdocker/opengist/latest/volumes/data:/data:z \ + -v /var/lib/srv/$USER/docker/casjaysdevdocker/opengist/latest/volumes/config:/config:z \ + -p 80:80 \ + -p 7823:7823 \ + casjaysdevdocker/opengist:latest ``` - -## via docker-compose - + +### docker-compose + ```yaml services: - ProjectName: - image: casjaysdevdocker/opengist + opengist: + image: casjaysdevdocker/opengist:latest container_name: casjaysdevdocker-opengist + hostname: opengist environment: - TZ=America/New_York - - HOSTNAME=opengist volumes: - "/var/lib/srv/$USER/docker/casjaysdevdocker/opengist/latest/volumes/data:/data:z" - "/var/lib/srv/$USER/docker/casjaysdevdocker/opengist/latest/volumes/config:/config:z" ports: - - 80:80 + - "80:80" + - "7823:7823" restart: always ``` - -## Get source files - + +--- + +## ⚙️ Configuration + +### Volumes + +| Path | Purpose | +|------|---------| +| `/config` | Runtime configuration (auto-generated on first start) | +| `/data` | Gist repositories, SQLite database, logs, and index | + +### Ports + +| Port | Protocol | Purpose | +|------|----------|---------| +| `80` | HTTP | Web UI and HTTP Git clone/pull | +| `7823` | TCP | Built-in SSH server for Git push/pull | + +### Environment variables + +| Variable | Default | Description | +|----------|---------|-------------| +| `TZ` | `America/New_York` | Container timezone | +| `HOSTNAME` | `casjaysdev-opengist` | Sets the `external-url` in opengist config | +| `SERVER_NAME` / `FULL_DOMAIN_NAME` | — | Override hostname for external URL | +| `OPENGIST_APPNAME_ENABLED` | `yes` | Set to `no` to disable the service | +| `OPENGIST_ROOT_USER_NAME` | — | Initial admin username | +| `OPENGIST_ROOT_PASS_WORD` | — | Initial admin password | +| `OPENGIST_USER_NAME` | — | Initial normal user name | +| `OPENGIST_USER_PASS_WORD` | — | Initial normal user password | +| `DEBUGGER` | — | Set to `on` to enable shell-level debug tracing | + +### Runtime config overrides + +Place a shell script at `/config/env/opengist.sh` inside the container (or mount it as a file) to override any variable at runtime without rebuilding the image. A template is written on first start. + +### OAuth2 + +After first start, edit `/config/opengist/config.yaml` to add OAuth2 credentials: + +```yaml +github.client-key: +github.secret: + +gitlab.client-key: +gitlab.secret: +gitlab.url: https://gitlab.com/ + +gitea.client-key: +gitea.secret: +gitea.url: https://your-gitea-instance/ + +oidc.client-key: +oidc.secret: +oidc.discovery-url: https://auth.example.com/.well-known/openid-configuration +``` + +OAuth2 callback URLs must follow the pattern: +`http:///oauth//callback` + +--- + +## 🛠️ Development + +### Prerequisites + +- Docker with `buildx` support +- `git` + +### Get source + +```shell +git clone "https://github.com/casjaysdevdocker/opengist" \ + "$HOME/Projects/github/casjaysdevdocker/opengist" +cd "$HOME/Projects/github/casjaysdevdocker/opengist" +``` + +Or via dockermgr: + ```shell dockermgr download src casjaysdevdocker/opengist ``` - -OR - -```shell -git clone "https://github.com/casjaysdevdocker/opengist" "$HOME/Projects/github/casjaysdevdocker/opengist" -``` - -## Build container - -```shell -cd "$HOME/Projects/github/casjaysdevdocker/opengist" -buildx -``` - -## Authors - -🤖 casjay: [Github](https://github.com/casjay) 🤖 -⛵ casjaysdevdocker: [Github](https://github.com/casjaysdevdocker) [Docker](https://hub.docker.com/u/casjaysdevdocker) ⛵ +### Build the image + +```shell +buildx +``` + +The build downloads the latest OpenGist release binary from GitHub at build time and bundles it into the image. + +--- + +## 📄 License + +WTFPL — see [LICENSE.md](LICENSE.md) + +🤖 casjay: [Github](https://github.com/casjay) 🤖 +⛵ casjaysdevdocker: [Github](https://github.com/casjaysdevdocker) [Docker](https://hub.docker.com/u/casjaysdevdocker) ⛵