Add some docs (thomiceli#198)

config.yml

@@ -67,7 +67,7 @@ ssh.keygen-executable: ssh-keygen
 
 
 # OAuth2 configuration
-# The callback/redirect URL must be http:https://opengist.domain/oauth/<github|gitlab|gitea|openid-connect>/callback
+# The callback/redirect URL must be http:https://opengist.url/oauth/<github|gitlab|gitea|openid-connect>/callback
 
 # To create a new OAuth2 application using GitHub : https://github.com/settings/applications/new
 github.client-key:

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:https://localhost:6157/healthcheck
+```
+
+```json
+{"database":"ok","opengist":"ok","time":"2024-01-04T05:18:33+01:00"}
+```

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:https://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:https://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: <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:https://opengist.domain/oauth/gitlab/callback`
+* Set 'Redirect URI' to `http:https://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: <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:https://opengist.domain/oauth/gitea/callback`
+* Set 'Redirect URI' to `http:https://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: <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:https://opengist.domain/oauth/openid-connect/callback`
+* Set 'Redirect URI' to `http:https://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: <key>

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.

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
+<script src="http:https://opengist.url/user/gist-url.js"></script>
+
+<!-- Dark mode: -->
+<script src="http:https://opengist.url/user/gist-url.js?dark"></script>
+```
+

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:https://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:https://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:https://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:https://localhost:6157\">Hosted via Opengist</a> · <span class=\"text-gray-700 dark:text-gray-200 font-bold\"><a target=\"_blank\" href=\"http:https://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:https://localhost:6157/thomas/my-gist.js",
+ "js_dark": "http:https://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"
+}
+```
+

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:https://user:[email protected]/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
+```
+

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),
  })