[chore] Clarify supported platforms, add notes + docs (#3427)

* [chore] Don't build for OpenBSD, add support level notes + tips * tweak a bit * add supported platforms matrix
1 year ago · 020da28daa
3 changed files with 94 additions and 72 deletions
--- a/.goreleaser.yml
+++ b/.goreleaser.yml
@ -39,7 +39,6 @@ builds:
    goos:
      - linux
      - freebsd
-      - openbsd
    goarch:
      - 386
      - amd64
@ -49,19 +48,14 @@ builds:
      - 6
      - 7
    ignore:
-      # build freebsd + openbsd only for amd64
+      # Build FreeBSD
+      # only for amd64.
      - goos: freebsd
        goarch: arm64
      - goos: freebsd
        goarch: arm
      - goos: freebsd
        goarch: 386
-      - goos: openbsd
-        goarch: arm64
-      - goos: openbsd
-        goarch: arm
-      - goos: openbsd
-        goarch: 386
    mod_timestamp: "{{ .CommitTimestamp }}"
  # MODERNC SQLITE BINARY BUILDS
  -
@ -88,7 +82,6 @@ builds:
    goos:
      - linux
      - freebsd
-      - openbsd
    goarch:
      - 386
      - amd64
@ -98,19 +91,14 @@ builds:
      - 6
      - 7
    ignore:
-      # build freebsd + openbsd only for amd64
+      # Build FreeBSD
+      # only for amd64.
      - goos: freebsd
        goarch: arm64
      - goos: freebsd
        goarch: arm
      - goos: freebsd
        goarch: 386
-      - goos: openbsd
-        goarch: arm64
-      - goos: openbsd
-        goarch: arm
-      - goos: openbsd
-        goarch: 386
    mod_timestamp: "{{ .CommitTimestamp }}"

 # https://goreleaser.com/customization/docker/
@ -474,17 +462,42 @@ release:
    
    Tl;dr: Regardless of whether you're using SQLite or Postgres as your DB driver, you most likely you want the regular version without `moderncsqlite` in the name.
    
-    However, if you're on FreeBSD or OpenBSD, use the `moderncsqlite` version instead. See the table below:
+    However, if you're on FreeBSD, 32-bit Linux or 32-bit ARM, we recommend using the `moderncsqlite` version instead.
+    
+    You may need to change some configuration options too. See the table below:
+    
+    | OS      | Architecture            | Support level                      | Binary archive                                                                                                                                                                     | Docker                                                         |
+    | ------- | ----------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
+    | Linux   | x86-64/AMD64 (64-bit)   | 🟢 Full                            | [linux_amd64.tar.gz](https://github.com/superseriousbusiness/gotosocial/releases/download/{{ .Tag }}/gotosocial_{{ .Version }}_linux_amd64.tar.gz)                                 | `superseriousbusiness/gotosocial:{{ .Version }}`               |
+    | Linux   | Armv8/ARM64 (64-bit)    | 🟢 Full                            | [linux_arm64.tar.gz](https://github.com/superseriousbusiness/gotosocial/releases/download/{{ .Tag }}/gotosocial_{{ .Version }}_linux_arm64.tar.gz)                                 | `superseriousbusiness/gotosocial:{{ .Version }}`               |
+    | FreeBSD | x86-64/AMD64 (64-bit)   | 🟢 Full<sup>[1](#freebsd)</sup>    | [freebsd_amd64_moderncsqlite.tar.gz](https://github.com/superseriousbusiness/gotosocial/releases/download/{{ .Tag }}/gotosocial_{{ .Version }}_freebsd_amd64_moderncsqlite.tar.gz) | None provided                                                  |
+    | Linux   | x86-32/i386 (32-bit)    | 🟡 Partial<sup>[2](#32-bit)</sup>  | [linux_386_moderncsqlite.tar.gz](https://github.com/superseriousbusiness/gotosocial/releases/download/{{ .Tag }}/gotosocial_{{ .Version }}_linux_386_moderncsqlite.tar.gz)         | `superseriousbusiness/gotosocial:{{ .Version }}-moderncsqlite` |
+    | Linux   | Armv7/ARM32 (32-bit)    | 🟡 Partial<sup>[2](#32-bit)</sup>  | [linux_armv7_moderncsqlite.tar.gz](https://github.com/superseriousbusiness/gotosocial/releases/download/{{ .Tag }}/gotosocial_{{ .Version }}_linux_armv7_moderncsqlite.tar.gz)     | `superseriousbusiness/gotosocial:{{ .Version }}-moderncsqlite` |
+    | Linux   | Armv6/ARM32 (32-bit)    | 🟡 Partial<sup>[2](#32-bit)</sup>  | [linux_armv6_moderncsqlite.tar.gz](https://github.com/superseriousbusiness/gotosocial/releases/download/{{ .Tag }}/gotosocial_{{ .Version }}_linux_armv7_moderncsqlite.tar.gz)     | `superseriousbusiness/gotosocial:{{ .Version }}-moderncsqlite` |
+    | Linux   | x86-32/i386 (32-bit)    | 🟡 Partial<sup>[2](#32-bit)</sup>  | [linux_386_moderncsqlite.tar.gz](https://github.com/superseriousbusiness/gotosocial/releases/download/{{ .Tag }}/gotosocial_{{ .Version }}_linux_386_moderncsqlite.tar.gz)         | `superseriousbusiness/gotosocial:{{ .Version }}-moderncsqlite` |
+    
+    #### FreeBSD
+    
+    `moderncsqlite` version currently recommended, though you might have success with the regular WASM SQLite version.
+    
+    If running with regular WASM SQLite and having instability or memory issues, the following settings *may* help:
+    
+    ```yaml
+    db-max-open-conns-multiplier: 0
+    db-sqlite-journal-mode: "TRUNCATE"
+    db-sqlite-synchronous: "FULL"
+    ```
+    
+    #### 32-bit
+    
+    `moderncsqlite` version is needed, as performance with regular WASM SQLite is not guaranteed when running on 32-bit.
+    
+    Remote media processing will likely not work with reasonable performance, so you should set the following config variables to prevent download of remote media onto your instance:
    
-    | OS      | Architecture            | Binary archive                                                                                                                                                                     | Docker                                                         |
-    | ------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
-    | Linux   | x86-64/AMD64 (64-bit)   | [linux_amd64.tar.gz](https://github.com/superseriousbusiness/gotosocial/releases/download/{{ .Tag }}/gotosocial_{{ .Version }}_linux_amd64.tar.gz)                                 | `superseriousbusiness/gotosocial:{{ .Version }}`               |
-    | Linux   | x86-32/i386 (32-bit)    | [linux_386.tar.gz](https://github.com/superseriousbusiness/gotosocial/releases/download/{{ .Tag }}/gotosocial_{{ .Version }}_linux_386.tar.gz)                                     | `superseriousbusiness/gotosocial:{{ .Version }}`               |
-    | Linux   | Armv8/ARM64 (64-bit)    | [linux_arm64.tar.gz](https://github.com/superseriousbusiness/gotosocial/releases/download/{{ .Tag }}/gotosocial_{{ .Version }}_linux_arm64.tar.gz)                                 | `superseriousbusiness/gotosocial:{{ .Version }}`               |
-    | Linux   | Armv7/ARM32 (32-bit)    | [linux_armv7.tar.gz](https://github.com/superseriousbusiness/gotosocial/releases/download/{{ .Tag }}/gotosocial_{{ .Version }}_linux_armv7.tar.gz)                                 | `superseriousbusiness/gotosocial:{{ .Version }}`               |
-    | Linux   | Armv6/ARM32 (32-bit)    | [linux_armv6.tar.gz](https://github.com/superseriousbusiness/gotosocial/releases/download/{{ .Tag }}/gotosocial_{{ .Version }}_linux_armv6.tar.gz)                                 | `superseriousbusiness/gotosocial:{{ .Version }}`               |
-    | OpenBSD | x86-64/AMD64 (64-bit)   | [openbsd_amd64_moderncsqlite.tar.gz](https://github.com/superseriousbusiness/gotosocial/releases/download/{{ .Tag }}/gotosocial_{{ .Version }}_openbsd_amd64_moderncsqlite.tar.gz) | `superseriousbusiness/gotosocial:{{ .Version }}-moderncsqlite` |
-    | FreeBSD | x86-64/AMD64 (64-bit)   | [freebsd_amd64_moderncsqlite.tar.gz](https://github.com/superseriousbusiness/gotosocial/releases/download/{{ .Tag }}/gotosocial_{{ .Version }}_freebsd_amd64_moderncsqlite.tar.gz) | `superseriousbusiness/gotosocial:{{ .Version }}-moderncsqlite` |
+    ```yaml
+    media-remote-max-size: 0
+    media-emoji-remote-max-size: 0
+    ``` 

 # https://goreleaser.com/customization/changelog/
 changelog:
--- a/README.md
+++ b/README.md
@ -41,7 +41,11 @@ Here's a screenshot of the instance landing page!
  - [OIDC integration](#oidc-integration)
  - [Backend-first design](#backend-first-design)
 - [Known Issues](#known-issues)
- [Getting Started](#getting-started)
+- [Installing GoToSocial](#installing-gotosocial)
+  - [Supported Platforms](#supported-platforms)
+    - [FreeBSD](#freebsd)
+    - [32-bit](#32-bit)
+    - [OpenBSD](#openbsd)
  - [Stable Releases](#stable-releases)
  - [Snapshot Releases](#snapshot-releases)
    - [Docker](#docker)
@ -258,9 +262,49 @@ Since every ActivityPub server implementation has a slightly different interpret

 ---

-## Getting Started
+## Installing GoToSocial

-Check our [releases page](https://github.com/superseriousbusiness/gotosocial/releases) and our [getting started](https://docs.gotosocial.org/en/latest/getting_started/) documentation.
+Check our [getting started](https://docs.gotosocial.org/en/latest/getting_started/) documentation! And have a peruse of our [releases page](https://github.com/superseriousbusiness/gotosocial/releases).
+
+<!--releases-start-->
+### Supported Platforms
+
+While we try to support a reasonable number of architectures and operating systems, it's not always possible to support a given platform due to library constraints or performance issues.
+
+Platforms that we don't officially support *may* still work, but we can't test or guarantee performance or stability.
+
+This is the current status of support offered by GoToSocial for different platforms (if something is unlisted it means we haven't checked yet so we don't know):
+
+| OS      | Architecture            | Support level                      | Binary archive | Docker container |
+| ------- | ----------------------- | ---------------------------------- | -------------- | ---------------- |
+| Linux   | x86-64/AMD64 (64-bit)   | 🟢 Full                            | Yes            | Yes              |
+| Linux   | Armv8/ARM64 (64-bit)    | 🟢 Full                            | Yes            | Yes              |
+| FreeBSD | x86-64/AMD64 (64-bit)   | 🟢 Full<sup>[1](#freebsd)</sup>    | Yes            | No               |
+| Linux   | x86-32/i386 (32-bit)    | 🟡 Partial<sup>[2](#32-bit)</sup>  | Yes            | Yes              |
+| Linux   | Armv7/ARM32 (32-bit)    | 🟡 Partial<sup>[2](#32-bit)</sup>  | Yes            | Yes              |
+| Linux   | Armv6/ARM32 (32-bit)    | 🟡 Partial<sup>[2](#32-bit)</sup>  | Yes            | Yes              |
+| Linux   | x86-32/i386 (32-bit)    | 🟡 Partial<sup>[2](#32-bit)</sup>  | Yes            | Yes              |
+| OpenBSD | Any                     | 🔴 None<sup>[3](#openbsd)</sup>    | No             | No               |
+
+#### FreeBSD
+
+Mostly works, just a few issues with WASM SQLite; check release notes carefully when installing on FreeBSD. If running with Postgres you should have no issues.
+
+#### 32-bit
+
+GtS doesn't work well on 32-bit systems like i386, or Armv6/v7, mainly due to performance of media decoding.
+
+As such, we don't recommend running GtS on 32-bit, but you may have success if you turn off downloading of remote media.
+
+For more guidance, check release notes when trying to install on 32-bit. 
+
+#### OpenBSD
+
+Marked as unsupported due to performance issues (high memory usage when idle, crashes while processing media).
+
+You may have some success if you turn off decoding of remote media.
+
+We hope to support OpenBSD better in future, but this is not guaranteed.

 ### Stable Releases

@ -302,6 +346,7 @@ You can also deploy your own instance of GoToSocial with the help of:
 - [Ansible Playbook (MASH)](https://github.com/mother-of-all-self-hosting/mash-playbook): The playbook supports a many services, including GoToSocial. [Documentation](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/services/gotosocial.md)
 - [GoToSocial Helm Chart](https://github.com/fSocietySocial/charts/tree/main/charts/gotosocial) by [0hlov3](https://github.com/0hlov3).

+<!--releases-end-->
 ---

 ## Contributing
--- a/docs/getting_started/releases.md
+++ b/docs/getting_started/releases.md
@ -1,47 +1,11 @@
 # Releases

-GoToSocial can be installed in a number of different ways. We publish official binary releases as well as container images. A number of third-party packages are maintained by different distributions and some people have created additional deployment tooling to make it easy to deploy GoToSocial yourself.
+GoToSocial can be installed in a number of different ways. We publish official binary releases as well as container images.

-## Binary releases
+A number of third-party packages are maintained by different distributions, and some people have created additional deployment tooling to make it easy to deploy GoToSocial yourself.

-We publish binary builds for Linux to [our GitHub project](https://github.com/superseriousbusiness/gotosocial/releases):
-
-* 32-bit Intel/AMD (i386/x86)
-* 64-bit Intel/AMD (amd64/x86_64)
-* 32-bit ARM (v6 and v7)
-* 64-bit ARM64
-
-For FreeBSD we publish:
-
-* 64-bit Intel/AMD (amd64/x86_64)
-
-## Containers
-
-We also publish container images [on the Docker Hub](https://hub.docker.com/r/superseriousbusiness/gotosocial).
-
-Containers are released for the same Linux platforms as our binary releases, with the exception of 32-bit Intel/AMD.
-
-## Snapshots
-
-We publish snapshot binary builds and Docker images of whatever is currently on main.
-
-We always recommend using a stable release instead, but if you want to live on the edge (at your own risk!) then see the [snapshots](https://github.com/superseriousbusiness/gotosocial#snapshots) section on our GitHub repo for more information.
-
-## Third-party
-
-Some folks have created distribution packages for GoToSocial or additional tooling to aid in installing GoToSocial.
-
-### Distribution packages
-
-These packages are not maintained by GoToSocial, so please direct questions and issues to the repository maintainers (and donate to them!).
-
-[![Packaging status](https://repology.org/badge/vertical-allrepos/gotosocial.svg)](https://repology.org/project/gotosocial/versions)
-
-### Deployment tools
-
-You can deploy your own instance of GoToSocial with the help of:
-
- [YunoHost GoToSocial Packaging](https://github.com/YunoHost-Apps/gotosocial_ynh) by [OniriCorpe](https://github.com/OniriCorpe).
- [Ansible Playbook (MASH)](https://github.com/mother-of-all-self-hosting/mash-playbook): The playbook supports a many services, including GoToSocial. [Documentation](https://github.com/mother-of-all-self-hosting/mash-playbook/blob/main/docs/services/gotosocial.md)
- GoToSocial Helm Charts:
-  - [GoToSocial Helm Chart](https://github.com/fSocietySocial/charts/tree/main/charts/gotosocial) by [0hlov3](https://github.com/0hlov3).
+{%
+  include "../../README.md"
+  start='<!--releases-start-->'
+  end='<!--releases-end-->'
+%}