diff --git a/README.md b/README.md index cdb798328..5c7e14474 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,16 @@ -# soapbox-fe +# Soapbox FE -> :warning: soapbox-fe is BETA software. +> :warning: Soapbox FE is BETA software. > Please take a look at the [list of open issues](https://gitlab.com/soapbox-pub/soapbox-fe/-/issues). ![Soapbox FE Screenshot](soapbox-screenshot.png) -**soapbox-fe** is an alternative frontend for Pleroma. +**Soapbox FE** is a frontend for Pleroma with a focus on custom branding and ease of use. It's part of the [Soapbox](https://soapbox.pub) project. -It is based on [Gab Social](https://code.gab.com/gab/social/gab-social)'s frontend which is in turn based on [Mastodon](https://github.com/tootsuite/mastodon/)'s frontend. - -## How does it work? - -soapbox-fe 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). - -It incorporates much of the [Mastodon API](https://docs.joinmastodon.org/methods/) used by Pleroma and Mastodon, but requires many [Pleroma-specific features](https://docs-develop.pleroma.social/backend/API/differences_in_mastoapi_responses/) in order to function. - # :rocket: Deploy on Pleroma -Installing soapbox-fe on an existing Pleroma server is extremely easy. +Installing Soapbox FE on an existing Pleroma server is extremely easy. Just ssh into the server and download a .zip of the latest build: ```sh @@ -35,11 +24,20 @@ busybox unzip soapbox-fe.zip -o -d /opt/pleroma/instance ``` **That's it!** :tada: -**soapbox-fe is installed.** +**Soapbox FE is installed.** The change will take effect immediately, just refresh your browser tab. It's not necessary to restart the Pleroma service. -To remove soapbox-fe and revert to the default pleroma-fe, simply `rm -r /opt/pleroma/instance/index.html` (you can delete other stuff in there too, but be careful not to delete your own HTML files). +To remove Soapbox FE and revert to the default pleroma-fe, simply `rm /opt/pleroma/instance/index.html` (you can delete other stuff in there too, but be careful not to delete your own HTML files). + +## How does it work? + +Soapbox FE 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). + +It incorporates much of the [Mastodon API](https://docs.joinmastodon.org/methods/) used by Pleroma and Mastodon, but requires many [Pleroma-specific features](https://docs-develop.pleroma.social/backend/API/differences_in_mastoapi_responses/) in order to function. # Running locally @@ -82,7 +80,7 @@ Try again. ## Developing against a live backend -You can also run soapbox-fe locally with a live production server as the backend. +You can also run Soapbox FE locally with a live production server as the backend. > **Note:** Whether or not this works depends on your production server. It does not seem to work with Cloudflare. @@ -101,27 +99,6 @@ PROXY_HTTPS_INSECURE=true You will need to restart the local development server for the changes to take effect. -## Using with Mastodon - -Local Mastodon runs on port 3000 by default, so you will need to edit the `.env` as described above and set it like this: - -```sh -BACKEND_URL="http://localhost:3000" -``` - -Streaming will not work properly without extra effort. - -Due to Mastodon not supporting authentication through the API, you will also need to authenticate manually. -First log in through the Mastodon interface, view the source of the page, and extract your access_token from the markup. -Then open your browser to soapbox-fe (`http://localhost:3036`), open the console, and insert the following code: - -```js -window.localStorage.setItem('soapbox:auth:user', JSON.stringify({access_token: "XXX"})); -``` - -Replace `XXX` with your access token. -Finally, refresh the page, and you should be logged in. - ## Local Dev Configuration The following configuration variables are supported supported in local development. @@ -132,9 +109,9 @@ All configuration is optional, except `NODE_ENV`. #### `NODE_ENV` The Node environment. -soapbox-fe checks for the following options: +Soapbox FE checks for the following options: -- `development` - What you should use while developing soapbox-fe. +- `development` - What you should use while developing Soapbox FE. - `production` - Use when compiling to deploy to a live server. - `test` - Use when running automated tests. @@ -146,14 +123,6 @@ For https, be sure to also set `PROXY_HTTPS_INSECURE=true`. **Default:** `http://localhost:4000` -#### `PATRON_URL` - -URL to the [Soapbox Patron](https://gitlab.com/soapbox-pub/soapbox-patron) server, if you have one. - -This setting is not useful unless `"extensions": { "patron": true }` is also set in `static/instance/soapbox.json`. - -**Default:** `http://localhost:5000` - #### `PROXY_HTTPS_INSECURE` Allows using an HTTPS backend if set to `true`. @@ -174,8 +143,6 @@ NODE_ENV=development ``` #### Local dev server -- `yarn start` - Run the local dev server. It will proxy requests to the backend for you. - - `yarn dev` - Exact same as above, aliased to `yarn start` for convenience. #### Building @@ -206,6 +173,7 @@ Additional supporting documents include: # Customization Soapbox supports customization of the user interface, to allow per instance branding and other features. Current customization features include: + * Instance name * Site logo * Favicon @@ -219,17 +187,19 @@ Soapbox supports customization of the user interface, to allow per instance bran Customization details can be found in the [Customization doc](docs/customization.md) -# License +# License & Credits -soapbox-fe is free software: you can redistribute it and/or modify +Soapbox FE is based on [Gab Social](https://code.gab.com/gab/social/gab-social)'s frontend which is in turn based on [Mastodon](https://github.com/tootsuite/mastodon/)'s frontend. + +Soapbox FE is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. -soapbox-fe is distributed in the hope that it will be useful, +Soapbox FE is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License -along with soapbox-fe. If not, see . +along with Soapbox FE. If not, see .