diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..071fa9c8f --- /dev/null +++ b/docs/README.md @@ -0,0 +1,3 @@ +# Soapbox Docs + +Read the Soapbox documentation here: https://docs.soapbox.pub/soapbox/ \ No newline at end of file diff --git a/docs/administration/deploy-at-scale.md b/docs/administration/deploy-at-scale.md deleted file mode 100644 index 4280a82b2..000000000 --- a/docs/administration/deploy-at-scale.md +++ /dev/null @@ -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. diff --git a/docs/administration/install-subdomain.md b/docs/administration/install-subdomain.md deleted file mode 100644 index 34a8cb37b..000000000 --- a/docs/administration/install-subdomain.md +++ /dev/null @@ -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. diff --git a/docs/administration/install-yunohost.md b/docs/administration/install-yunohost.md deleted file mode 100644 index 83a96d800..000000000 --- a/docs/administration/install-yunohost.md +++ /dev/null @@ -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. diff --git a/docs/administration/mastodon.md b/docs/administration/mastodon.md deleted file mode 100644 index 8f0914461..000000000 --- a/docs/administration/mastodon.md +++ /dev/null @@ -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/). diff --git a/docs/administration/removing.md b/docs/administration/removing.md deleted file mode 100644 index 2b84de919..000000000 --- a/docs/administration/removing.md +++ /dev/null @@ -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. diff --git a/docs/administration/updating.md b/docs/administration/updating.md deleted file mode 100644 index 21eb8ffa0..000000000 --- a/docs/administration/updating.md +++ /dev/null @@ -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. diff --git a/docs/contributing.md b/docs/contributing.md deleted file mode 100644 index 2d6aed726..000000000 --- a/docs/contributing.md +++ /dev/null @@ -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. diff --git a/docs/customization.md b/docs/customization.md deleted file mode 100644 index e857c149c..000000000 --- a/docs/customization.md +++ /dev/null @@ -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! diff --git a/docs/development/build-config.md b/docs/development/build-config.md deleted file mode 100644 index b4236d39d..000000000 --- a/docs/development/build-config.md +++ /dev/null @@ -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 `` of the document, you may do so by creating a `custom/snippets.html` file. - -For example: - -```html - - - - - - - - - - -``` - -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: `""` diff --git a/docs/development/developing-backend.md b/docs/development/developing-backend.md deleted file mode 100644 index 7896323ce..000000000 --- a/docs/development/developing-backend.md +++ /dev/null @@ -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! diff --git a/docs/development/how-it-works.md b/docs/development/how-it-works.md deleted file mode 100644 index f8578d893..000000000 --- a/docs/development/how-it-works.md +++ /dev/null @@ -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. diff --git a/docs/development/local-config.md b/docs/development/local-config.md deleted file mode 100644 index d1168e9e0..000000000 --- a/docs/development/local-config.md +++ /dev/null @@ -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` diff --git a/docs/development/running-locally.md b/docs/development/running-locally.md deleted file mode 100644 index f37282ac8..000000000 --- a/docs/development/running-locally.md +++ /dev/null @@ -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/). diff --git a/docs/development/yarn-commands.md b/docs/development/yarn-commands.md deleted file mode 100644 index 6838706fc..000000000 --- a/docs/development/yarn-commands.md +++ /dev/null @@ -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. diff --git a/docs/history.md b/docs/history.md deleted file mode 100644 index 010dcb1ad..000000000 --- a/docs/history.md +++ /dev/null @@ -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. diff --git a/docs/installing.md b/docs/installing.md deleted file mode 100644 index c70448b70..000000000 --- a/docs/installing.md +++ /dev/null @@ -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.*