diff --git a/docs/config.md b/docs/config.md index f23bf4c..babc51d 100644 --- a/docs/config.md +++ b/docs/config.md @@ -1,6 +1,6 @@ # How to configure GoBlog -Most settings for GoBlog (still) have to be configured using a YAML configuration file. See `example-config.yaml` for the available options. It's recommended to just set the settings you really need. There are defaults for most settings. Some settings can be configured using a web UI (with the path of `/settings`). +Most settings for GoBlog (still) have to be configured using a YAML configuration file. See `example-config.yaml` for the available options. **It's recommended to just set the settings you really need, so it's best to start from a blank configuration file.** There are defaults for most settings. Some settings can be configured using a web UI (with the path of `/settings`). ## Sections @@ -12,4 +12,70 @@ Example for the path template: ``` {{printf \"/%v/%v\" .Section .Slug}} +``` + +### Setting Up GoBlog with nginx + +The following is a minimal example configuration for GoBlog running behind an nginx reverse proxy and using the certbot plugin to generate TLS certificates. + +**config.yml** + +```text-plain +# Web server +server: + port: 8080 # GoBlog Port + publicAddress: https://yourdomain.tld # Public address of your blog + +# User +user: + nick: user # Username for login (can be changed later using the settings web UI) + password: password # Password for login + +# Blogs +defaultBlog: main # Default blog name (needed because you can define multiple blogs) +blogs: + main: # Blog name + path: / # Path of blog + lang: en # Language of blog + title: My Cool Blog # Blog title + description: "Welcome to this blog." # Blog description + # Taxonomies + taxonomies: + - name: tags # Code of taxonomy (used via post parameters) + title: Tags # Name + description: "**Tags** on this blog" # Description + # Menus + menus: + # Main menu + main: + items: + - title: Home # Title + link: / # Site-relative or absolute links + - title: Posts + link: /posts +``` + +**example-nginx.conf** + +```text-plain +server { + server_name yourdomain.tld; + + location / { + proxy_set_header Host $http_host; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_max_temp_file_size 0; + proxy_pass http://localhost:8080; + proxy_redirect http:// https://; + client_max_body_size 30M; + } +} +``` + +Generate SSL certificates with the nginx certbot plugin by running: + +```text-plain +$ certbot --nginx -d yourdomain.tld -d www.yourdomain.tld ``` \ No newline at end of file diff --git a/docs/install.md b/docs/install.md index 269086e..bb0ed25 100644 --- a/docs/install.md +++ b/docs/install.md @@ -7,7 +7,6 @@ Create your config file (`./config/config.yml`) with inspiration from `example-c Then you can use Docker Compose to run GoBlog. Here's an example `docker-compose.yml` file: ```yaml -version: "3" services: goblog: container_name: goblog @@ -21,7 +20,7 @@ services: - TZ=Europe/Berlin # You timezone ``` -If you don't want to use a reverse proxy (like Caddy) you can also publish the ports directly from the GoBlog container. Remember to enable public https in the config, so GoBlog gets Let's Encrypt certificates. +If you don't want to use a reverse proxy (like Caddy or nginx) you can also publish the ports directly from the GoBlog container. Remember to enable public https in the config, so GoBlog gets Let's Encrypt certificates. ```yaml goblog: diff --git a/docs/usage.md b/docs/usage.md index f06dc91..3812324 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -43,7 +43,42 @@ There's also the possibility to configure GoBlog to use Google Cloud's Text-to-S On receiving a webmention, a new comment or a contact form submission, GoBlog will create a new notification. Notifications are displayed on `/notifications` and can be deleted by the user. -If configured, GoBlog will also send a notification using a Telegram Bot or [Ntfy.sh](https://ntfy.sh/). See the `example-config.yml` file for how to configure the notification providers. +If configured, GoBlog will also send a notification using a Telegram bot, a Matrix user and an *unencrypted* Matrix channel, or [Ntfy.sh](https://ntfy.sh/). + +### Setting up Notifications with Ntfy + +1. Create a "Topic" in the [Ntfy.sh Webapp](https://ntfy.sh/app) or another Ntfy instance. Using a randomly generated string as “Topic” is recommended. +2. Add a "notifications" section to your configuration file with the following configuration: + +```yaml +notifications: + ntfy: # Receive notifications using Ntfy.sh + enabled: true # Enable it + topic: randomlyGeneratedTopicString # The topic for the notifications + server: https://ntfy.sh # The server to use (default is https://ntfy.sh) + user: myusername # The username to use (optional) + password: mypassword # The password to use (optional) + email: notifications@yourdomain.tld # Email address for Ntfy Email Notifications +``` + +### Setting up Notifications with Matrix + +1. Set up a new Matrix account that will act as the Bot. +2. Create a new *unencrypted* room. +3. Add a "notifications" section to your configuration file with the following configuration: + +```yaml +notifications: + matrix: # Receive notifications via Matrix + enabled: true # Enable it + homeserver: https://matrix.org # The bot's homeserver + username: botUsername # The bot's username + password: botPassword # The bot's password + room: "#roomsName:matrix.org" # The Matrix chat room for the notifications + deviceid: TestBlogNotifications # A unique device ID (to not clutter your login sessions) (optional) +``` + +See the `example-config.yml` file for how to configure other notification providers. ## Tor Hidden Services @@ -59,4 +94,110 @@ GoBlog has a comment system. That can be enable using the configuration. See the All comments and interactions (Webmentions) have to be approved manually using the UI at `/webmention`. To completely delete a comment, delete the entry from the Webmention UI and also delete the comment from `/comment`. -To disable showing comments and interactions on a single post, add the parameter `comments` with the value `false` to the post's metadata. \ No newline at end of file +To disable showing comments and interactions on a single post, add the parameter `comments` with the value `false` to the post's metadata. + +## ActivityPub Support + +Publish and comment to the Fediverse by adding an "activitypub" section to your configuration file: + +```yaml +# ActivityPub +activityPub: + enabled: true # Enable ActivityPub + tagsTaxonomies: # Post taxonomies to use as "Hashtags" + - tags +``` + +This configuration creates a Fediverse account at `@blogname@yourdomain.tld` with the following features: + +✅ Publishing +✅ Replying (Unlisted/Public) +✅ Converting incoming replies to blog comments +✅ Incoming Likes/Reposts +❌ Outgoing Likes/Reposts +✅ Incoming @-mention +❌ Outgoing @-mention +✅ Followers +❌ Following + +## Redirects & Aliases + +Activate redirects by adding a `pathRedirects` section to your configuration file: + +```yaml +# Redirects +pathRedirects: + # Simple 302 redirect from /index.xml to .rss + - from: "\\/index\\.xml" + to: ".rss" + # Redirect using regular expressions + - from: "^\\/(writings|dev)\\/posts(.*)$" + to: "/$1$2" + type: 301 # custom redirect type +``` + +Individual posts can also have redirects by adding redirection paths using the `aliases` post parameter: + +```text +--- +path: /about +title: About me +aliases: +- /info +- /me +--- + +This is an about me page located at /about and it redirects from /info and /me +``` + +## Extra notes + +### Export content to Markdown + +Use the export command to export all posts as Markdown with the post parameters as frontmatter: + +```bash +$goblogpath export ./$exportpath +``` + +### Fixing a GoBlog corrupted database + +While the GoBlog binary runs, next to the main SQLite database file some accompanying files (Write-Ahead-Log and shared memory for SQLite) are created in the data folder, these files are essential for the integrity of the database. If the database gets corrupted. + +Stop the GoBlog process, backup the database files and try to recover the database with sqlite: + +```bash +sqlite3 data/db.sqlite ".recover" | sqlite3 data/newdb.sqlite +``` + +If this doesn't work look for more clues running:  + +```bash +sqlite3 data/db.sqlite “PRAGMA integrity_check” +``` + +### Cleaning up the GoBlog database + +At the moment some options can't be modified via the UI, certain changes can be applied by accessing the database directly using sqlite. + +```bash +sqlite3 data/db.sqlite +``` + +#### Revoking unused IndieAuth Tokens + +Tokens can be manually deleted: + +```sql +DELETE FROM indieauthtoken WHERE $condition; +``` + +But they can also be revoked [using the IndieAuth API](https://www.w3.org/TR/indieauth/#token-revocation). + +#### Erasing deleted posts + +GoBlog returns a 410 HTTP error for deleted posts, to stop that: + +```sql +DELETE FROM deleted WHERE path = '/deletedpost'; +``` \ No newline at end of file