Update README
This commit is contained in:
Alex Gleason
parent
5e60fe1954
commit
ffb61d136b
1 changed files with 25 additions and 55 deletions
80
README.md
80
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** 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 <https://www.gnu.org/licenses/>.
|
||||
along with Soapbox FE. If not, see <https://www.gnu.org/licenses/>.
|
||||
|
|
|
|||
Loading…
Reference in a new issue