kopia lustrzana https://gitlab.com/soapbox-pub/soapbox
Remove docs, point to docs.soapbox.pub
Alex Gleason
rodzic
c0849e7250
commit
a3c4c7646a
|
|
@ -0,0 +1,3 @@
|
|||
# Soapbox Docs
|
||||
|
||||
Read the Soapbox documentation here: https://docs.soapbox.pub/soapbox/
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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/).
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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!
|
||||
|
|
@ -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: `""`
|
||||
|
|
@ -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!
|
||||
|
|
@ -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.
|
||||
|
|
@ -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`
|
||||
|
|
@ -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/).
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.*
|
||||
Ładowanie…
Reference in New Issue