From af19268d6f8ff595805f04cb521bf37575b9213b Mon Sep 17 00:00:00 2001 From: Thomas Miceli <27960254+thomiceli@users.noreply.github.com> Date: Thu, 4 Jan 2024 16:45:57 +0100 Subject: [PATCH] Add some docs (#198) --- config.yml | 2 +- docs/administration/healthcheck.md | 13 ++++++ docs/administration/oauth-providers.md | 10 ++--- docs/update.md | 57 ++++++++++++++++++++++++++ docs/usage/embed.md | 11 +++++ docs/usage/gist-json.md | 37 +++++++++++++++++ docs/usage/import-from-github-gist.md | 23 +++++++++++ internal/web/healthcheck.go | 1 + 8 files changed, 148 insertions(+), 6 deletions(-) create mode 100644 docs/administration/healthcheck.md create mode 100644 docs/update.md create mode 100644 docs/usage/embed.md create mode 100644 docs/usage/gist-json.md create mode 100644 docs/usage/import-from-github-gist.md diff --git a/config.yml b/config.yml index 168e38f7..7f27bf97 100644 --- a/config.yml +++ b/config.yml @@ -67,7 +67,7 @@ ssh.keygen-executable: ssh-keygen # OAuth2 configuration -# The callback/redirect URL must be http://opengist.domain/oauth//callback +# The callback/redirect URL must be http://opengist.url/oauth//callback # To create a new OAuth2 application using GitHub : https://github.com/settings/applications/new github.client-key: diff --git a/docs/administration/healthcheck.md b/docs/administration/healthcheck.md new file mode 100644 index 00000000..2005a889 --- /dev/null +++ b/docs/administration/healthcheck.md @@ -0,0 +1,13 @@ +# Healthcheck + +A healthcheck is a simple HTTP GET request to the `/healthcheck` endpoint. It returns a `200 OK` response if the server is healthy. + +## Example + +```shell +curl http://localhost:6157/healthcheck +``` + +```json +{"database":"ok","opengist":"ok","time":"2024-01-04T05:18:33+01:00"} +``` diff --git a/docs/administration/oauth-providers.md b/docs/administration/oauth-providers.md index e4d66961..8a9fbaca 100644 --- a/docs/administration/oauth-providers.md +++ b/docs/administration/oauth-providers.md @@ -4,8 +4,8 @@ Opengist can be configured to use OAuth to authenticate users, with GitHub, Gite ## Github -* 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` +* Add a new OAuth app in your [GitHub account settings](https://github.com/settings/applications/new) +* Set 'Authorization callback URL' to `http://opengist.url/oauth/github/callback` * Copy the 'Client ID' and 'Client Secret' and add them to the [configuration](/docs/configuration/cheat-sheet.md) : ```yaml github.client-key: @@ -16,7 +16,7 @@ Opengist can be configured to use OAuth to authenticate users, with GitHub, Gite ## GitLab * Add a new OAuth app in Application settings from the [GitLab instance](https://gitlab.com/-/user_settings/applications) -* Set 'Redirect URI' to `http://opengist.domain/oauth/gitlab/callback` +* Set 'Redirect URI' to `http://opengist.url/oauth/gitlab/callback` * Copy the 'Client ID' and 'Client Secret' and add them to the [configuration](/docs/configuration/cheat-sheet.md) : ```yaml gitlab.client-key: @@ -29,7 +29,7 @@ Opengist can be configured to use OAuth to authenticate users, with GitHub, Gite ## Gitea * 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` +* Set 'Redirect URI' to `http://opengist.url/oauth/gitea/callback` * Copy the 'Client ID' and 'Client Secret' and add them to the [configuration](/docs/configuration/cheat-sheet.md) : ```yaml gitea.client-key: @@ -42,7 +42,7 @@ Opengist can be configured to use OAuth to authenticate users, with GitHub, Gite ## OpenID Connect * Add a new OAuth app in Application settings of your OIDC provider -* Set 'Redirect URI' to `http://opengist.domain/oauth/openid-connect/callback` +* Set 'Redirect URI' to `http://opengist.url/oauth/openid-connect/callback` * Copy the 'Client ID', 'Client Secret', and the discovery endpoint, and add them to the [configuration](/docs/configuration/cheat-sheet.md) : ```yaml oidc.client-key: diff --git a/docs/update.md b/docs/update.md new file mode 100644 index 00000000..2681acfd --- /dev/null +++ b/docs/update.md @@ -0,0 +1,57 @@ +# Update + +## Make a backup + +Before updating, always make sure to backup the Opengist home directory, where all the data is stored. + +You can do so by copying the `~/.opengist` directory (default location). + +```shell +cp -r ~/.opengist ~/.opengist.bak +``` + +## Install the new version + +### With Docker + +Pull the last version of Opengist +```shell +docker pull ghcr.io/thomiceli/opengist:1 +``` + +And restart the container, using `docker compose up -d` for example if you use docker compose. + +### Via binary + +Stop the running instance; then like your first installation of Opengist, download the archive for your system from the release page [here](https://github.com/thomiceli/opengist/releases/latest), and extract it. + +```shell +# example for linux amd64 +wget https://github.com/thomiceli/opengist/releases/download/v1.6.0/opengist1.6.0-linux-amd64.tar.gz + +tar xzvf opengist1.6.0-linux-amd64.tar.gz +cd opengist +chmod +x opengist +./opengist # with or without `--config config.yml` +``` + +### From source + +Stop the running instance; then pull the last changes from the master branch, and build the new version. + +```shell +git pull +make +./opengist +``` + +## Restore the backup + +If you have any issue with the new version, you can restore the backup you made before updating. + +```shell +rm -rf ~/.opengist +cp -r ~/.opengist.bak ~/.opengist +``` + +Then run the old version of Opengist again. diff --git a/docs/usage/embed.md b/docs/usage/embed.md new file mode 100644 index 00000000..0d90d0b9 --- /dev/null +++ b/docs/usage/embed.md @@ -0,0 +1,11 @@ +# 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 + + + + +``` + diff --git a/docs/usage/gist-json.md b/docs/usage/gist-json.md new file mode 100644 index 00000000..9bd0916b --- /dev/null +++ b/docs/usage/gist-json.md @@ -0,0 +1,37 @@ +# 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" +} +``` + diff --git a/docs/usage/import-from-github-gist.md b/docs/usage/import-from-github-gist.md new file mode 100644 index 00000000..7cb5b8dd --- /dev/null +++ b/docs/usage/import-from-github-gist.md @@ -0,0 +1,23 @@ +# Import Gists from GitHub + +After running Opengist at least once, you can import your Gists from GitHub using this script: + +```shell +github_user=user # replace with your GitHub username +opengist_url="http://user:password@opengist.url/init" # replace user, password and Opengist url + +curl -s https://api.github.com/users/"$github_user"/gists?per_page=100 | jq '.[] | .git_pull_url' -r | while read url; do + git clone "$url" + repo_dir=$(basename "$url" .git) + + # Add remote, push, and remove the directory + if [ -d "$repo_dir" ]; then + cd "$repo_dir" + git remote add gist "$opengist_url" + git push -u gist --all + cd .. + rm -rf "$repo_dir" + fi +done +``` + diff --git a/internal/web/healthcheck.go b/internal/web/healthcheck.go index e7c2058e..c814361d 100644 --- a/internal/web/healthcheck.go +++ b/internal/web/healthcheck.go @@ -18,6 +18,7 @@ func healthcheck(ctx echo.Context) error { } return ctx.JSON(httpStatus, map[string]interface{}{ + "opengist": "ok", "database": dbOk, "time": time.Now().Format(time.RFC3339), })