feat(docs): Update documentation

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:https://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 :

docs/configuration/index.md → 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
 

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.

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`. |

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:https://localhost:6157/healthcheck | grep '"database":"ok"' | grep '"opengist":"ok"' || exit 1
+ interval: 10s
+ timeout: 5s
+ retries: 10
+```
+
+## Example
+
+```shell
+curl http:https://localhost:6157/healthcheck
+```
+
+```json
+{"database":"ok","opengist":"ok","time":"2024-01-04T05:18:33+01:00"}
+```

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:
+
+<details>
+<summary>Using Docker labels</summary>
+
+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
+```
+
+</details>
+
+
+<details>
+<summary>Using a <code>yml</code> file</summary>
+
+> ![Note]
+> Don't forget to change the `<server-address>` 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:https://<server-address>:6157"
+
+```
+
+</details>
+
+## Nginx
+
+
+### Subdomain
+```
+server {
+ listen 80;
+ server_name opengist.example.com;
+
+ location / {
+ proxy_pass http:https://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:https://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
+```

docs/installation.md

@@ -72,3 +72,7 @@ make
 ```
 
 Opengist is now running on port 6157, you can browse http:https://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.