bigbuffet/bigbuffet-rw
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Remove docs, point to docs.soapbox.pub

Browse source
This commit is contained in:
Alex Gleason 2024-04-11 20:42:47 -05:00
parent c0849e7250
commit a3c4c7646a
No known key found for this signature in database
GPG key ID: 7211D1F99744FBB7
17 changed files with 3 additions and 898 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
docs/README.md Normal file
View file

@ -0,0 +1,3 @@
# Soapbox Docs
Read the Soapbox documentation here: https://docs.soapbox.pub/soapbox/

112
docs/administration/deploy-at-scale.md
View file

@ -1,112 +0,0 @@
# Deploying Soapbox at scale
Fortunately Soapbox is just static files!
HTML, CSS, and JS is as scalable as it gets, but there are some additional considerations when deploying at scale.
This guide is intended for users with a lot of traffic, who need to serve Soapbox behind a load-balancer.
## Getting or building Soapbox
The best way to get Soapbox builds is from a GitLab CI job.
The official build URL is here:
```
https://dl.soapbox.pub/main/soapbox.zip
```
(Note that `develop` in that URL can be replaced with any git ref, eg `v2.0.0`, and thus will be updated with the latest zip whenever a new commit is pushed to `develop`.)
### Producing a custom build
If you'd like to customize Soapbox, we recommend forking it on GitLab and having GitLab CI produce the build for you at your own URL.
You may be interested in [build configuration options](../development/build-config) for customization and compile-time options.
## Load-balanced Nginx
A common way to deploy Soapbox at scale is with multiple Nginx servers behind a load-balancer.
The load-balancer could run HAProxy, be a Cloudflare load-balancer, or even be another Nginx.
Each Nginx should have the latest Soapbox deployed on it, while the load-balancer distributes traffic to each Nginx.
Soapbox is an [SPA (single-page application)](https://en.wikipedia.org/wiki/Single-page_application), meaning Nginx should serve the same `index.html` for every route except build files and known API paths.
Loosely, that can be achieved like this:
```nginx
location / {
root /opt/soapbox/static;
try_files $uri index.html;
}
location ~ ^/(api|oauth|admin) {
proxy_pass http://127.0.0.1:3000;
}
```
We recommend trying [`mastodon.conf`](https://gitlab.com/soapbox-pub/soapbox/-/blob/main/installation/mastodon.conf) as a starting point.
It is fine-tuned, includes support for federation, and should work with any backend.
## The ServiceWorker
Soapbox ships with a ServiceWorker, `sw.js`, as part of its build.
ServiceWorkers enable native app-like functionality on the site, including:
- Offline support.
- Native push notifications.
- "Add to home screen" prompt.
Overall, the ServiceWorker offers a better experience for users.
However it requires careful planning for deployments, because it has an unprecedented level of control over the browser.
Here are some surprising things ServiceWorkers can do:
- Serve a different page for any URL on the domain, even if no such file/page has been deployed.
- Serve an outdated file even after clearing your browser cache.
To help mitigate ServiceWorker issues, it's important to follow the directions in this guide regarding the order of files deployed and caching.
It is also possible to omit `sw.js` from your deployment if you aren't ready for it, but beware that simply removing the file won't cause the ServiceWorker to disappear from users' devices.
You should deploy a [no-op ServiceWorker](https://developer.chrome.com/docs/workbox/remove-buggy-service-workers/) for that.
## Deploying files in order
Soapbox files depend on one-another, so it's important they're deployed in the following order:
1. `packs/` is deployed to _all servers_ first.
2. `index.html` is deployed to _all servers_ next.
3. `sw.js` (and everything else) is deployed to _all servers_ last.
_"All servers"_ is stressed because with a load-balanced deployment, it's important to wait between each step so things don't get out of sync.
Files in `packs/` are generated with [contenthash filenames](https://webpack.js.org/guides/caching/#output-filenames), so a new deployment won't interfere with the running deployment.
It is safe to merge directories with "overwrite" or "skip" mode.
The `index.html` contains hardcoded paths to files in `packs/`, so it must be deployed after all `packs/` have been uploaded.
New index files will overwrite the existing one on each server.
Finally, `sw.js` should be deployed, overwriting the existing one on each server.
It is dependent on `index.html`, and if deployed too soon, the ServiceWorker could cache an outdated `index.html` leaving users stuck on an old version of your website.
## Cache considerations
Build files in `packs/` have [unique filenames](https://webpack.js.org/guides/caching/#output-filenames) based on their content.
They are considered **idempotent** and may be cached forever.
You could even consider deploying these to an S3-compatible CDN.
However, **all other files else should not be cached at all**.
Please ensure that your Nginx configuration does not return `cache-control` headers on the index of your website (or any other page that serves Soapbox), and you _must not enable edge caching_ in Nginx or third-party services like Cloudflare.
Furthermore, `sw.js` must not be cached at the edge.
Failure to do this could lead to improper ServiceWorker functioning upon new deployments, leaving users stuck on a malfunctioning version of the site.
## Server Side Rendering (SSR)
AKA "why don't links to my website show a preview when posted on Facebook/Twitter/Slack/etc"?
Deploying with Nginx means that you forego the link preview functionality offered by Pleroma and Mastodon, since Soapbox has no knowledge of the backend whatsoever.
Our official solution is [Soapbox Worker](https://gitlab.com/soapbox-pub/soapbox-worker), a Cloudflare Worker that intercepts the reqest/response and injects metadata into the page by querying the API behind the scenes.

151
docs/administration/install-subdomain.md
View file

@ -1,151 +0,0 @@
# Installing Soapbox on a subdomain
If you would like to retain Pleroma FE on your Pleroma server, but install Soapbox alongside it on a subdomain, you can do so by following these steps.
## 1. Download the build
Create a directory on your system for Soapbox.
```sh
mkdir -p /opt/soapbox
```
Fetch the build.
```sh
curl -L https://gitlab.com/soapbox-pub/soapbox/-/jobs/artifacts/v1.3.0/download?job=build-production -o /tmp/soapbox-fe.zip
```
Unzip the build.
```sh
busybox unzip /tmp/soapbox-fe.zip -o -d /opt/soapbox
```
## 2. Configure Nginx
You will need to add an Nginx vhost for the subdomain.
Create a new file in `/etc/nginx/sites-available/soapbox.nginx` with the following content:
```nginx
server {
server_name soapbox.example.com;
listen 80;
listen [::]:80;
# Uncomment this if you need to use the 'webroot' method with certbot. Make sure
# that the directory exists and that it is accessible by the webserver. If you followed
# the guide, you already ran 'mkdir -p /var/lib/letsencrypt' to create the folder.
# You may need to load this file with the ssl server block commented out, run certbot
# to get the certificate, and then uncomment it.
#
location ~ /\.well-known/acme-challenge {
root /var/lib/letsencrypt/;
}
location / {
return 301 https://$server_name$request_uri;
}
}
# Enable SSL session caching for improved performance
ssl_session_cache shared:ssl_session_cache:10m;
server {
server_name soapbox.example.com;
listen 443 ssl http2;
listen [::]:443 ssl http2;
ssl_session_timeout 5m;
ssl_trusted_certificate /etc/letsencrypt/live/soapbox.example.com/chain.pem;
ssl_certificate /etc/letsencrypt/live/soapbox.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/soapbox.example.com/privkey.pem;
# Add TLSv1.0 to support older devices
ssl_protocols TLSv1.2;
# Uncomment line below if you want to support older devices (Before Android 4.4.2, IE 8, etc.)
# ssl_ciphers "HIGH:!aNULL:!MD5 or HIGH:!aNULL:!MD5:!3DES";
ssl_ciphers "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:!aNULL:!eNULL:!EXPORT:!DES:!MD5:!PSK:!RC4";
ssl_prefer_server_ciphers on;
# In case of an old server with an OpenSSL version of 1.0.2 or below,
# leave only prime256v1 or comment out the following line.
ssl_ecdh_curve X25519:prime256v1:secp384r1:secp521r1;
ssl_stapling on;
ssl_stapling_verify on;
#brotli on;
#brotli_static on;
#brotli_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript application/activity+json application/atom+xml;
gzip_vary on;
gzip_proxied any;
gzip_comp_level 6;
gzip_buffers 16 8k;
gzip_http_version 1.1;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript application/activity+json application/atom+xml;
# the nginx default is 1m, not enough for large media uploads
client_max_body_size 40m;
root /opt/soapbox/static/;
location / {
try_files $uri /index.html;
}
location = /index.html {
expires 30s;
}
# here goes long list of what we will use from real instance
location ~ ^/(api|.well-known|nodeinfo|proxy|media|emoji|oauth|favicon.*) {
proxy_pass $scheme://127.0.0.1$request_uri;
# proxy_redirect $scheme://example.com$request_uri $scheme://soapbox.example.com$request_uri;
proxy_set_header Host example.com;
proxy_set_header X-Real-IP $remote_addr;
# doesn't work with some browsers
# return 308 $scheme://example.com$request_uri;
}
access_log /var/log/nginx/access.soapbox.log;
error_log /var/log/nginx/error.soapbox.log;
}
```
Replace `soapbox.example.com` with your desired subdomain and save the file.
You should also adjust `client_max_body_size` to your instance file size limit.
Replace `example.com` to your original domain.
Additionally, activate the vhost file:
```sh
sudo ln -s /etc/nginx/sites-available/soapbox.nginx /etc/nginx/sites-enabled/soapbox.nginx
```
## 3. Configure HTTPS support
TODO
## 4. Reload Nginx
Finally, test that your new configuration is valid:
```sh
nginx -t
```
If that passed, reload Nginx:
```sh
systemctl reload nginx
```
If all is well, you should be able to visit the subdomain in your browser and access Soapbox!
---
Thank you to [@a1batross@expired.mentality.rip](https://expired.mentality.rip/users/a1batross) for originally discovering and authoring this method.

37
docs/administration/install-yunohost.md
View file

@ -1,37 +0,0 @@
# Installing Soapbox via YunoHost
If you want to install Soapbox to a Pleroma instance installed using [YunoHost](https://yunohost.org), you can do so by following these steps.
## 1. Download the build
First, download the latest build of Soapbox from GitLab.
```sh
curl -O https://dl.soapbox.pub/main/soapbox.zip
```
## 2. Unzip the build
Then, unzip the build to the Pleroma directory under YunoHost's directory:
```sh
busybox unzip soapbox.zip -o -d /home/yunohost.app/pleroma/static
```
## 3. Change YunoHost Admin Static directory
(A bug documented in the YunoHost deployment about this issue is [here](https://github.com/YunoHost-Apps/pleroma_ynh/issues/215))
Go to:
> Admin Panel > Settings > Instance
Look for the "Static dir" entry and set it to:
> /home/yunohost.app/pleroma/static
**That's it! 🎉 Soapbox is installed.** The change will take effect immediately, just refresh your browser tab. It's not necessary to restart the Pleroma service.
---
Thank you to [@jeroen@social.franssen.xyz](https://social.franssen.xyz/@jeroen) for discovering this method.

35
docs/administration/mastodon.md
View file

@ -1,35 +0,0 @@
# Installing Soapbox over Mastodon
It is possible to run Soapbox as your main frontend on top of Mastodon.
This will replace the homepage and all static pages with Soapbox, using Mastodon only as the API.
To do so, shell into your server and unpack Soapbox:
```sh
mkdir -p /opt/soapbox
curl -O https://dl.soapbox.pub/main/soapbox.zip
busybox unzip soapbox.zip -o -d /opt/soapbox
```
Now create an Nginx file for Soapbox with Mastodon.
If you already have one, replace it:
```sh
curl https://gitlab.com/soapbox-pub/soapbox/-/raw/main/installation/mastodon.conf > /etc/nginx/sites-available/mastodon
```
Edit this file and replace all occurrences of `example.com` with your domain name.
Uncomment the SSL lines if you've enabled SSL, otherwise do that first.
Finally, ensure the file is symlinked, then restart Nginx:
```sh
ln -s /etc/nginx/sites-available/mastodon /etc/nginx/sites-enabled/mastodon
systemctl restart nginx
```
If all is well, hopefully this worked!
If not, run `nginx -t` to see if anything is amiss, and try reviewing Mastodon's [install guide](https://docs.joinmastodon.org/admin/install/).

10
docs/administration/removing.md
View file

@ -1,10 +0,0 @@
# Removing Soapbox
Removing Soapbox and reverting to Pleroma FE is really easy. Just run the following:
```
rm /opt/pleroma/instance/static/index.html
rm -R /opt/pleroma/instance/static/packs
rm -R /opt/pleroma/instance/static/sounds
```
If you need to remove other stuff, feel free to do so. But be careful not to remove your own HTML files.

21
docs/administration/updating.md
View file

@ -1,21 +0,0 @@
# Updating Soapbox
You should always check the [release notes/changelog](https://gitlab.com/soapbox-pub/soapbox/-/blob/main/CHANGELOG.md) in case there are deprecations, special update changes, etc.
Besides that, it's relatively pretty easy to update Soapbox. There's two ways to go about it: with the command line or with an unofficial script.
## Updating with the command line
To update Soapbox via the command line, do the following:
```
# Download the build.
curl -O https://dl.soapbox.pub/main/soapbox.zip
# Unzip the new build to Pleroma's instance directory.
busybox unzip soapbox.zip -o -d /opt/pleroma/instance/static
```
## After updating Soapbox
The changes take effect immediately, just refresh your browser tab. It's not necessary to restart the Pleroma service.

34
docs/contributing.md
View file

@ -1,34 +0,0 @@
# Contributing to Soapbox
Thank you for your interest in Soapbox!
When contributing to Soapbox, please first discuss the change you wish to make by [opening an issue](https://gitlab.com/soapbox-pub/soapbox/-/issues).
## Opening an MR (merge request)
1. Smash that "fork" button on GitLab to make a copy of the repo.
2. Clone the repo locally, then begin work on a new branch (eg not `develop`).
3. Push your branch to your fork.
4. Once pushed, GitLab should provide you with a URL to open a new merge request right in your terminal. If not, do it [manually](https://gitlab.com/soapbox-pub/soapbox/-/merge_requests/new).
### Ensuring the CI pipeline succeeds
When you push to a branch, the CI pipeline will run.
[Soapbox uses GitLab CI](https://gitlab.com/soapbox-pub/soapbox/-/blob/main/.gitlab-ci.yml) to lint, run tests, and verify changes.
It's important this pipeline passes, otherwise we cannot merge the change.
New users of gitlab.com may see a "detatched pipeline" error.
If so, please check the following:
1. Your GitLab email address is confirmed.
2. You may have to have a credit card on file before the CI job will run.
## Text editor
We recommend developing Soapbox with [VSCodium](https://vscodium.com/) (or its proprietary ancestor, [VS Code](https://code.visualstudio.com/)).
This will help give you feedback about your changes _in the editor itself_ before GitLab CI performs linting, etc.
When this project is opened in Code it will automatically recommend extensions.
See [`.vscode/extensions.json`](https://gitlab.com/soapbox-pub/soapbox/-/blob/main/.vscode/extensions.json) for the full list.

40
docs/customization.md
View file

@ -1,40 +0,0 @@
# Customizing Soapbox
Soapbox uses your own site's name and branding throughout the interface.
This allows every Soapbox site to be different, and catered to a particular audience.
Unlike Mastodon, which uses the "Mastodon" branding on all instances, Soapbox does not refer to itself in the user interface.
## Backend settings
The site's name and description are **configured in the backend itself.**
These are settings global to your website, and will also affect mobile apps and other frontends accessing your website.
- On Mastodon, you can change it through the admin interface.
- On Pleroma, it can be edited through AdminFE, or by editing `config/prod.secret.exs` on the server.
These settings are exposed through the API under GET `/api/v1/instance`.
## Soapbox settings
Most settings are specific to your Soapbox installation and not the entire website.
That includes the logo, default theme, and more.
- On Pleroma, admins can edit these settings directly from Soapbox. Just click "Soapbox config" in the sidebar, or navigate directly to `/soapbox/config`.
- On Mastodon, admins need to upload a JSON file with the settings, and make it available at `https://yoursite.tld/instance/soapbox.json`.
If using Pleroma, these settings are exposed through the API under GET `/api/pleroma/frontend_configurations`.
Otherwise, the settings need to be uploaded manually and made available at GET `/instance/soapbox.json`.
## About pages
It is possible to create arbitrary HTML pages under `/about/:page` on your website.
In your Soapbox installation directory (probably on your server), find the `instance` folder.
For Pleroma, this will be located under `/opt/pleroma/instance/static/instance`.
This directory contains files that are loaded on-demand by the browser, including about pages.
Just create a file like `instance/about/hello.html` on your server and it will become available under `/about/hello` on your instance.
If you create a file called `index.html`, it will be treated as the root (available under `/about`), and you can create subfolders too.
For convenience, Soapbox ships with sample files under `instance/about.example`.
Simply rename that directory to `about` and start editing!

181
docs/development/build-config.md
View file

@ -1,181 +0,0 @@
# Build Configuration
Soapbox supports compile-time customizations in the form of environment variables and a gitignored `custom/` directory.
## `custom/` directory
You can place files into the `custom/` directory to customize the Soapbox build.
### Custom snippets (`custom/snippets.html`)
If you'd like to include analytics snippets, custom meta tags, or anything else in the `<head>` of the document, you may do so by creating a `custom/snippets.html` file.
For example:
```html
<link href='/icons/icon-57x57.png' rel='apple-touch-icon' sizes='57x57'>
<link href='/icons/icon-64x64.png' rel='apple-touch-icon' sizes='64x64'>
<link href='/icons/icon-72x72.png' rel='apple-touch-icon' sizes='72x72'>
<link href='/icons/icon-114x114.png' rel='apple-touch-icon' sizes='114x114'>
<link href='/icons/icon-120x120.png' rel='apple-touch-icon' sizes='120x120'>
<link href='/icons/icon-180x180.png' rel='apple-touch-icon' sizes='180x180'>
<link href='/icons/icon-192x192.png' rel='apple-touch-icon' sizes='192x192'>
<link href='/icons/icon-512x512.png' rel='apple-touch-icon' sizes='512x512'>
<!-- Matomo -->
<script>
var _paq = window._paq = window._paq || [];
/* tracker methods like "setCustomDimension" should be called before "trackPageView" */
_paq.push(['trackPageView']);
_paq.push(['enableLinkTracking']);
(function() {
var u="//trk.bonsa.net/";
_paq.push(['setTrackerUrl', u+'matomo.php']);
_paq.push(['setSiteId', '12345678']);
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
})();
</script>
```
The snippet will be included **before** any Soapbox application code.
### Custom locales (`custom/locales/*.json`)
It is possible to override locale messages by creating a file for each language, eg `custom/locales/en.json`.
In this file, add only the messages you want to be overridden.
For example:
```json
{
"account.posts": "Poasts",
"account.posts_with_replies": "Poasts & Replies",
"compose.submit_success": "Your poast was sent!",
"compose_form.publish": "Poast"
}
```
These messages will be merged into the language file shipped with Soapbox.
### Feature overrides (`custom/features.json`)
You can create a file called `custom/features.json` to disable version-checking and force some features on or off.
For example:
```json
{
"bookmarks": false,
"lists": false,
"quotePosts": true
}
```
See `src/utils/features.js` for the full list of features.
### Embedded app (`custom/app.json`)
By default, Soapbox will create a new OAuth app every time a user tries to register or log in.
This is usually the desired behavior, as it works "out of the box" without any additional configuration, and it is resistant to tampering and subtle client bugs.
However, some larger servers may wish to skip this step for performance reasons.
If an app is supplied in `custom/app.json`, it will be used for authorization.
The full app entity must be provided, for example:
```json
{
"client_id": "cf5yI6ffXH1UcDkEApEIrtHpwCi5Tv9xmju8IKdMAkE",
"client_secret": "vHmSDpm6BJGUvR4_qWzmqWjfHcSYlZumxpFfohRwNNQ",
"id": "7132",
"name": "Soapbox",
"redirect_uri": "urn:ietf:wg:oauth:2.0:oob",
"website": "https://soapbox.pub/",
"vapid_key": "BLElLQVJVmY_e4F5JoYxI5jXiVOYNsJ9p-amkykc9NcI-jwa9T1Y2GIbDqbY-HqC6ayPkfW4K4o9vgBFKYmkuS4"
}
```
It is crucial that the app has the expected scopes.
You can obtain one with the following curl command (replace `MY_DOMAIN`):
```sh
curl -X POST -H "Content-Type: application/json" -d '{"client_name": "Soapbox", "redirect_uris": "urn:ietf:wg:oauth:2.0:oob", "scopes": "read write follow push admin", "website": "https://soapbox.pub/"}' "https://MY_DOMAIN.com/api/v1/apps"
```
### Custom files (`custom/instance/*`)
You can place arbitrary files of any type in the `custom/instance/` directory.
They will be available on your website at `https://example.com/instance/{filename}`.
Subdirectories are supported, too.
Some use cases:
- Logos, which can then be referenced from `soapbox.json`
- About pages, available at `/about` on your website.
## Environment variables
When compiling Soapbox, environment variables may be passed to change the build itself.
For example:
```sh
NODE_ENV="production" FE_SUBDIRECTORY="/soapbox" yarn build
```
### `NODE_ENV`
The environment to build Soapbox for.
Options:
- `"production"` - For live sites
- `"development"` - For local development
- `"test"` - Bootstraps test environment
Default: `"development"`
It's recommended to always build in `"production"` mode for live sites.
### `BACKEND_URL`
The base URL for API calls.
You only need to set this if Soapbox is hosted in a different place than the backend.
Options:
- An absolute URL, eg `"https://gleasonator.com"`
- Empty string (`""`)`
Default: `""`
### `FE_SUBDIRECTORY`
Subdirectory to host Soapbox out of.
When hosting on a subdirectory, you must create a custom build for it.
This option will set the imports in `index.html`, and the basename for routes in React.
Options:
- Any path, eg `"/soapbox"` or `"/fe/soapbox"`
Default: `"/"`
For example, if you want to host the build on `https://gleasonator.com/soapbox`, you can compile it like this:
```sh
NODE_ENV="production" FE_SUBDIRECTORY="/soapbox" yarn build
```
### `SENTRY_DSN`
[Sentry](https://sentry.io/) endpoint for this custom build.
Sentry is an error monitoring service that may be optionally included.
When an endpoint is not configured, it does nothing.
Sentry's backend was FOSS until 2019 when it moved to source-available, but a BSD-3 fork called [GlitchTip](https://glitchtip.com/) may also be used.
Options:
- Endpoint URL, eg `"https://abcdefg@app.glitchtip.com/123"`
Default: `""`

76
docs/development/developing-backend.md
View file

@ -1,76 +0,0 @@
# Developing a backend
Soapbox expects backends to implement the [Mastodon API](https://docs.joinmastodon.org/methods/).
At the very least:
- [instance](https://docs.joinmastodon.org/methods/instance/)
- [apps](https://docs.joinmastodon.org/methods/apps/)
- [oauth](https://docs.joinmastodon.org/methods/apps/oauth/)
- [accounts](https://docs.joinmastodon.org/methods/accounts/)
- [statuses](https://docs.joinmastodon.org/methods/statuses/)
Soapbox uses feature-detection on the instance to determine which features to show.
By default, a minimal featureset is used.
## Feature detection
First thing, Soapbox fetches GET `/api/v1/instance` to identify the backend.
The instance should respond with a `version` string:
```js
{
"title": "Soapbox",
"short_description": "hello world!",
// ...
"version": "2.7.2 (compatible; Pleroma 2.4.52+soapbox)"
}
```
The version string should match this format:
```
COMPAT_VERSION (compatible; BACKEND_NAME VERSION)
```
The Regex used to parse it:
```js
/^([\w+.]*)(?: \(compatible; ([\w]*) (.*)\))?$/
```
- `COMPAT_VERSION` - The highest Mastodon API version this backend is compatible with. If you're not sure, use a lower version like `2.7.2`. It MUST follow [semver](https://semver.org/).
- `BACKEND_NAME` - Human-readable name of the backend. No spaces!
- `VERSION` - The actual version of the backend. It MUST follow [semver](https://semver.org/).
Typically checks are done against `BACKEND_NAME` and `VERSION`.
The version string is similar in purpose to a [User-Agent](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent) string.
The format was first invented by Pleroma, but is now widely used, including by Pixelfed, Mitra, and Soapbox BE.
See [`features.ts`](https://gitlab.com/soapbox-pub/soapbox/-/blob/main/src/utils/features.ts) for the complete list of features.
## Forks of other software
If your software is a fork of another software, the version string should indicate that.
Otherwise, Soapbox will use the minimal featureset.
### Forks of Mastodon
Mastodon forks do not need the compat section, and can simply append `+[NAME]` to the version string (eg Glitch Social):
```
3.2.0+glitch
```
### Forks of Pleroma
For Pleroma forks, the fork name should be in the compat section (eg Soapbox BE):
```
2.7.2 (compatible; Pleroma 2.4.52+soapbox)
```
## Adding support for a new backend
If the backend conforms to the above format, please modify [`features.ts`](https://gitlab.com/soapbox-pub/soapbox/-/blob/main/src/utils/features.ts) and submit a merge request to enable features for your backend!

24
docs/development/how-it-works.md
View file

@ -1,24 +0,0 @@
# How it works
Soapbox is a [single-page application (SPA)](https://en.wikipedia.org/wiki/Single-page_application) that runs entirely in the browser with JavaScript.
It has a single HTML file, `index.html`, responsible only for loading the required JavaScript and CSS.
It interacts with the backend through [XMLHttpRequest (XHR)](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest).
Here is a simplified example with Nginx:
```nginx
location /api {
proxy_pass http://backend;
}
location / {
root /opt/soapbox;
try_files $uri index.html;
}
```
(See [`mastodon.conf`](https://gitlab.com/soapbox-pub/soapbox/-/blob/main/installation/mastodon.conf) for a full example.)
Soapbox incorporates much of the [Mastodon API](https://docs.joinmastodon.org/methods/), [Pleroma API](https://api.pleroma.social/), and more.
It detects features supported by the backend to provide the right experience for the backend.

32
docs/development/local-config.md
View file

@ -1,32 +0,0 @@
# Local Dev Configuration
The following configuration variables are supported supported in local development.
Edit `.env` to set them.
All configuration is optional, except `NODE_ENV`.
## `NODE_ENV`
The Node environment.
Soapbox checks for the following options:
- `development` - What you should use while developing Soapbox.
- `production` - Use when compiling to deploy to a live server.
- `test` - Use when running automated tests.
## `BACKEND_URL`
URL to the backend server.
Can be http or https, and can include a port.
For https, be sure to also set `PROXY_HTTPS_INSECURE=true`.
**Default:** `http://localhost:4000`
## `PROXY_HTTPS_INSECURE`
Allows using an HTTPS backend if set to `true`.
This is needed if `BACKEND_URL` is set to an `https://` value.
[More info](https://stackoverflow.com/a/48624590/8811886).
**Default:** `false`

44
docs/development/running-locally.md
View file

@ -1,44 +0,0 @@
# Running locally
To get it running, just clone the repo:
```
git clone https://gitlab.com/soapbox-pub/soapbox.git
cd soapbox
```
Ensure that Node.js and Yarn are installed, then install dependencies:
```
yarn
```
Finally, run the dev server:
```
yarn dev
```
**That's it!** 🎉
It will serve at `http://localhost:3036` by default.
You should see an input box - just enter the domain name of your instance to log in.
Tip: you can even enter a local instance like `http://localhost:3000`!
## Troubleshooting: `ERROR: NODE_ENV must be set`
Create a `.env` file if you haven't already.
```sh
cp .env.example .env
```
And ensure that it contains `NODE_ENV=development`.
Try again.
## Troubleshooting: it's not working!
Run `node -V` and compare your Node.js version with the version in [`.tool-versions`](https://gitlab.com/soapbox-pub/soapbox/-/blob/main/.tool-versions).
If they don't match, try installing [asdf](https://asdf-vm.com/).

31
docs/development/yarn-commands.md
View file

@ -1,31 +0,0 @@
# Yarn Commands
The following commands are supported.
You must set `NODE_ENV` to use these commands.
To do so, you can add the following line to your `.env` file:
```
NODE_ENV=development
```
## Local dev server
- `yarn dev` - Run the local dev server.
## Building
- `yarn build` - Compile without a dev server, into `/dist` directory.
## Translations
- `yarn i18n` - Rebuilds app and updates English locale to prepare for translations in other languages. Should always be run after editing i18n strings.
- `yarn manage:translations` - A low-level translations manager utility.
## Tests
- `yarn test:all` - Runs all tests and linters.
- `yarn test` - Runs Jest for frontend unit tests.
- `yarn lint` - Runs all linters.
- `yarn lint:js` - Runs only JavaScript linter.
- `yarn lint:sass` - Runs only SASS linter.

51
docs/history.md
View file

@ -1,51 +0,0 @@
# History
In order to better understand soapbox-fe, this document tells the story of how it came to be.
## March 2016, Mastodon
Mastodon, a federated microblogging platform, was released.
Mastodon is built with Ruby on Rails and uses React.js for its frontend.
The React frontend uses [standardized API endpoints](https://docs.joinmastodon.org/methods/accounts/) to handle all actions.
## July 2019, gab.com relaunch
In July 2019, Gab forked Mastodon 2.8.4 and migrated to it.
They overhauled Mastodon's user interface into a streamlined single-column UI with a prettier stylesheet.
Like Mastodon, Gab's fork is [open source](https://code.gab.com/gab/social/gab-social).
## August 2019, spinster.xyz launch
Spinster is a feminist platform I helped launch, forked from Gab's Mastodon version.
I began to heavily customize it with additional themes, integrated Stripe donations, and more.
I created the fork early on, and did not adopt many of the features (and bugs) that Gab added later.
## December 2019, Soapbox
I decided to rebrand the Spinster codebase to be more neutral, calling it "Soapbox" (coined by `@grrrandma@spinster.xyz`).
I wanted Soapbox to be something others would use.
However, Mastodon still had fundamental problems, and I began eye alternatives like Pleroma.
My goal with Soapbox is to attract non-technical people to the Fediverse.
In order to do that, I need to experiment and run a lot of servers, but Mastodon makes that very expensive since it requires a lot of RAM to run.
Meanwhile Pleroma is worlds more efficient, and would make things a lot cheaper for me in the long run.
## February 2020, HYDRA Social
I began contracting with Gab to create HYDRA Social, a Node.js Fediverse backend.
Node.js is also more efficient than Ruby and could have solved the problem.
For reasons I still don't understand, I was removed from the project after only a month.
## March 2020, soapbox-fe
I was in a headspace of making big changes, and decided to take on the move of Soapbox to Pleroma.
To do this, I would separate the frontend into its own repo to run on top of Pleroma, greatly simplifying the system.
This is only possible because Pleroma implements most of Mastodon's API endpoints, allowing me to re-use the majority of Soapbox's frontend code.
At the time of writing, I'm still getting soapbox-fe off the ground by implementing the basic features it needs to power Spinster and other sites.

19
docs/installing.md
View file

@ -1,19 +0,0 @@
# Installing Soapbox
This guide is a step-by-step guide for installing Soapbox. These instructions assume that you're using a fresh, new VPS powered by a Debian-based OS such as Ubuntu.
## Install Pleroma
First, follow the instructions to [install Pleroma](https://docs-develop.pleroma.social/backend/installation/debian_based_en/) on a fresh VPS. We recommend using Ubuntu 20.04 LTS.
## Install Soapbox
The Soapbox frontend is the main component of Soapbox. Once you've installed Pleroma, installing Soapbox is a breeze.
First, ssh into the server and download a .zip of the latest build: `curl -O https://dl.soapbox.pub/main/soapbox.zip`
Then unpack it into Pleroma's `instance` directory: `busybox unzip soapbox.zip -o -d /opt/pleroma/instance/static`
**That's it! 🎉 Soapbox is installed.** The change will take effect immediately, just refresh your browser tab. It's not necessary to restart the Pleroma service.
***For OTP releases,*** *unpack to /var/lib/pleroma instead.*