From 3d94cd8cf5435900f698c184704aa94366692d2a Mon Sep 17 00:00:00 2001 From: jiriks74 Date: Sun, 28 Apr 2024 03:42:15 +0200 Subject: [PATCH 1/2] feat(docs): Update - Merge administration folder with configuration as they're quite simmilar - Rename index.md to README.md so that it's rendered when opening docs - Add Traefik proxy basic config --- docs/{index.md => README.md} | 0 docs/administration/healthcheck.md | 13 --- docs/administration/nginx-reverse-proxy.md | 46 -------- docs/configuration/{index.md => README.md} | 13 +++ docs/configuration/admin-panel.md | 51 +++++++++ docs/configuration/cheat-sheet.md | 8 ++ .../fail2ban-setup.md | 0 docs/configuration/healthcheck.md | 27 +++++ .../oauth-providers.md | 0 docs/configuration/proxy.md | 102 ++++++++++++++++++ .../reset-password.md | 0 .../run-with-systemd.md | 0 docs/installation.md | 4 + 13 files changed, 205 insertions(+), 59 deletions(-) rename docs/{index.md => README.md} (100%) delete mode 100644 docs/administration/healthcheck.md delete mode 100644 docs/administration/nginx-reverse-proxy.md rename docs/configuration/{index.md => README.md} (74%) create mode 100644 docs/configuration/admin-panel.md rename docs/{administration => configuration}/fail2ban-setup.md (100%) create mode 100644 docs/configuration/healthcheck.md rename docs/{administration => configuration}/oauth-providers.md (100%) create mode 100644 docs/configuration/proxy.md rename docs/{administration => configuration}/reset-password.md (100%) rename docs/{administration => configuration}/run-with-systemd.md (100%) diff --git a/docs/index.md b/docs/README.md similarity index 100% rename from docs/index.md rename to docs/README.md diff --git a/docs/administration/healthcheck.md b/docs/administration/healthcheck.md deleted file mode 100644 index 2005a889..00000000 --- a/docs/administration/healthcheck.md +++ /dev/null @@ -1,13 +0,0 @@ -# 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/nginx-reverse-proxy.md b/docs/administration/nginx-reverse-proxy.md deleted file mode 100644 index fdbdc807..00000000 --- a/docs/administration/nginx-reverse-proxy.md +++ /dev/null @@ -1,46 +0,0 @@ -# Use Nginx as a reverse proxy - -Configure Nginx to proxy requests to Opengist. Here are example configuration file to use Opengist on a subdomain or on a subpath. - -Make sure you set the base url for Opengist via the [configuration](/docs/configuration/cheat-sheet.md). - -### Subdomain -``` -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; - } -} -``` - -### Subpath -``` -server { - listen 80; - server_name example.com; - - location /opengist/ { - rewrite ^/opengist(/.*)$ $1 break; - 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; - proxy_set_header X-Forwarded-Prefix /opengist; - } -} -``` - ---- - -To apply changes: -```shell -sudo systemctl restart nginx -``` diff --git a/docs/configuration/index.md b/docs/configuration/README.md similarity index 74% rename from docs/configuration/index.md rename to docs/configuration/README.md index 3283e272..a67d0b81 100644 --- a/docs/configuration/index.md +++ b/docs/configuration/README.md @@ -6,6 +6,19 @@ Opengist will simply apply the default values. The [configuration cheat sheet](cheat-sheet.md) lists all available configuration options. +## Table of contents + +- [Cheat sheet](cheat-sheet.md) +- [Admin panel](admin-panel.md) +- [OAuth providers](oauth-providers.md) +- [Password reset](reset-password.md) +- [Custom assets](custom-assets.md) +- [Custom links](custom-links.md) +- [Fail2ban](fail2ban.md) +- [Running using `systemd`](run-with-systemd.md) +- [Running behind reverse proxy](proxy.md) +- [Health check](healthcheck.md) + ## Configuration via YAML file diff --git a/docs/configuration/admin-panel.md b/docs/configuration/admin-panel.md new file mode 100644 index 00000000..cf53dcfe --- /dev/null +++ b/docs/configuration/admin-panel.md @@ -0,0 +1,51 @@ +# Admin panel + +The first user created on your Opengist instance has access to the Admin panel. + +To access the Admin panel: + +1. Log in +2. Click your username in the upper right corner +3. Select `Admin` + +## Usage + +### General + +Here you can see some basic information, like Opengist version, alongside some stats. + +You can also start some actions like forcing synchronization of gists, +starting garbage collection, etc. + +### Users + +Here you can see your users and delete them. + +### Gists + +Here you can see all the gists and some basic informations about them. You also have an option +to delete them. + + +### Invitations + +Here you can create invitation links with some options like limiting the number of signed up +users or setting an expiration date. + +> [!Note] +> Invitation links override the `Disable signup` option but not the `Disable login form` option. +> +> Users will see only the OAuth providers when `Disable login form` is enabled. + +### Configuration + +Here you can change a limited number of settings. + +- Disable signup + - Forbid the creation of new accounts. +- Require login + - Enforce users to be logged in to see gists. +- Disable login form + - Forbid logging in via the login form to force using OAuth providers instead. +- Disable Gravatar + - Disable the usage of Gravatar as an avatar provider. diff --git a/docs/configuration/cheat-sheet.md b/docs/configuration/cheat-sheet.md index ef7768fd..2281c20c 100644 --- a/docs/configuration/cheat-sheet.md +++ b/docs/configuration/cheat-sheet.md @@ -1,5 +1,13 @@ # Configuration Cheat Sheet +> [!Important] +> The following options can be changes only using the [admin panel](admin-panel.md) +> +> - Disable signup +> - Require login +> - Disable login form +> - Disable Gravatar + | 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`. | diff --git a/docs/administration/fail2ban-setup.md b/docs/configuration/fail2ban-setup.md similarity index 100% rename from docs/administration/fail2ban-setup.md rename to docs/configuration/fail2ban-setup.md diff --git a/docs/configuration/healthcheck.md b/docs/configuration/healthcheck.md new file mode 100644 index 00000000..d01574d7 --- /dev/null +++ b/docs/configuration/healthcheck.md @@ -0,0 +1,27 @@ +# Healthcheck + +A healthcheck is a simple HTTP GET request to the `/healthcheck` endpoint. It returns a `200 OK` response if the server is healthy. + +> [!Note] +> Don't forget to change the port from `6157` in the below examples +if you changed it in the configuration. + +## `docker-compose` + +```yml + healthcheck: + test: curl -sS http://localhost:6157/healthcheck | grep '"database":"ok"' | grep '"opengist":"ok"' || exit 1 + interval: 10s + timeout: 5s + retries: 10 +``` + +## 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/configuration/oauth-providers.md similarity index 100% rename from docs/administration/oauth-providers.md rename to docs/configuration/oauth-providers.md diff --git a/docs/configuration/proxy.md b/docs/configuration/proxy.md new file mode 100644 index 00000000..49ea7a67 --- /dev/null +++ b/docs/configuration/proxy.md @@ -0,0 +1,102 @@ +# Reverse proxy + +Configure Traefik or Nginx to proxy requests to Opengist. + +> [!Important] +> Make sure you set the base url for Opengist via the [configuration](/docs/configuration/cheat-sheet.md). + +## Traefik + +You can set up Traefik in two ways: + +
+Using Docker labels + +Add these labels to your `docker-compose.yml` file: + +```yml + labels: + - traefik.http.routers.opengist.rule=Host(`opengist.example.com`) # Change to your subdomain + # Uncomment the line below if you run Opengist in a subdirectory + # - traefik.http.routers.app1.rule=PathPrefix(`/opengist{regex:$$|/.*}`) # Change opentist in the regex to yuor subdirectory name + - traefik.http.routers.opengist.entrypoints=websecure # Change to the name of your 443 port entrypoint + - traefik.http.routers.opengist.tls.certresolver=lets-encrypt # Change to certresolver's name + - traefik.http.routers.opengist.service=opengist + - traefik.http.services.opengist.loadBalancer.server.port=6157 +``` + +
+ + +
+Using a yml file + +> ![Note] +> Don't forget to change the `` to your server's IP + +`traefik_dynamic.yml` +```yml +http: + routers: + opengist: + entrypoints: websecure + rule: Host(`opengist.example.com`) # Comment this line and uncomment the line below if using a subpath + # rule: PathPrefix(`/opengist{regex:$$|/.*}`) # Change opentist in the regex to yuor subdirectory name + # middlewares: + # - opengist-fail2ban + service: opengist + tls: + certresolver: lets-encrypt + services: + opengist: + loadbalancer: + servers: + - url: "http://:6157" + +``` + +
+ +## Nginx + + +### Subdomain +``` +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; + } +} +``` + +### Subpath +``` +server { + listen 80; + server_name example.com; + + location /opengist/ { + rewrite ^/opengist(/.*)$ $1 break; + 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; + proxy_set_header X-Forwarded-Prefix /opengist; + } +} +``` + +--- + +To apply changes: +```shell +sudo systemctl restart nginx +``` diff --git a/docs/administration/reset-password.md b/docs/configuration/reset-password.md similarity index 100% rename from docs/administration/reset-password.md rename to docs/configuration/reset-password.md diff --git a/docs/administration/run-with-systemd.md b/docs/configuration/run-with-systemd.md similarity index 100% rename from docs/administration/run-with-systemd.md rename to docs/configuration/run-with-systemd.md diff --git a/docs/installation.md b/docs/installation.md index 9b5f7122..09c19971 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -72,3 +72,7 @@ make ``` Opengist is now running on port 6157, you can browse http://localhost:6157 + +## Admin user + +The first user created, be it by using the sign up form or OAuth, had Admin priviledges and therefore has access to the `Admin` page. From b6d6b31d3cdc83c749b30b4746fd57d35001c0c2 Mon Sep 17 00:00:00 2001 From: jiriks74 Date: Sun, 28 Apr 2024 03:45:40 +0200 Subject: [PATCH 2/2] feat(README): Add healthceck to sample compose file --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index 4cc5fabb..5eb6ae5b 100644 --- a/README.md +++ b/README.md @@ -59,6 +59,11 @@ services: - "2222:2222" # SSH port, can be removed if you don't use SSH volumes: - "$HOME/.opengist:/opengist" + healthcheck: + test: curl -sS http://localhost:6157/healthcheck | grep '"database":"ok"' | grep '"opengist":"ok"' || exit 1 + interval: 10s + timeout: 5s + retries: 10 ``` You can define which user/group should run the container and own the files by setting the `UID` and `GID` environment variables :