> Please take a look at the [list of open issues](https://gitlab.com/soapbox-pub/soapbox-fe/-/issues).
> 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 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'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
# :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:
Just ssh into the server and download a .zip of the latest build:
The change will take effect immediately, just refresh your browser tab.
The change will take effect immediately, just refresh your browser tab.
It's not necessary to restart the Pleroma service.
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
# Running locally
@ -82,7 +80,7 @@ Try again.
## Developing against a live backend
## 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.
> **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.
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:
Soapbox supports customization of the user interface, to allow per instance branding and other features. Current customization features include:
Soapbox supports customization of the user interface, to allow per instance branding and other features. Current customization features include:
* Instance name
* Instance name
* Site logo
* Site logo
* Favicon
* 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)
Customization details can be found in the [Customization doc](docs/customization.md)
# License
# License & Credits
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
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
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
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
(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
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.
GNU Affero General Public License for more details.
You should have received a copy of the GNU Affero General Public License
You should have received a copy of the GNU Affero General Public License
along with soapbox-fe. If not, see <https://www.gnu.org/licenses/>.
along with Soapbox FE. If not, see <https://www.gnu.org/licenses/>.