2020-03-28 21:06:29 +00:00
# soapbox-fe
2020-04-25 19:42:16 +00:00
> :warning: Not yet ready for production use.
**soapbox-fe** is an alternative frontend for Pleroma.
It's part of the [Soapbox ](https://soapbox.pub ) project.
2020-03-28 21:06:29 +00:00
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.
2020-04-25 19:42:16 +00:00
## 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.
2020-04-21 18:34:18 +00:00
2020-04-07 01:30:05 +00:00
# Running locally
To get it running, just clone the repo:
```
git clone https://gitlab.com/soapbox-pub/soapbox-fe.git
cd soapbox-fe
```
Ensure that Node.js and Yarn are installed, then install dependencies:
```
yarn
```
Finally, run the dev server:
```
2020-04-14 17:30:26 +00:00
yarn start
2020-04-07 01:30:05 +00:00
```
2020-04-21 18:34:18 +00:00
**That's it!** :tada:
2020-04-07 01:30:05 +00:00
It will serve at `http://localhost:3036` by default.
It will proxy requests to the backend for you.
2020-04-21 18:34:18 +00:00
For Pleroma running on `localhost:4000` (the default) no other changes are required, just start a local Pleroma server and it should begin working.
## Developing against a live backend
You can also run soapbox-fe locally with a live production server as the backend.
2020-04-21 18:39:30 +00:00
> **Note:** Whether or not this works depends on your production server. It does not seem to work with Cloudflare.
2020-04-21 18:34:18 +00:00
To do so, just copy the env file:
```sh
cp .env.example .env
```
And edit `.env` , setting the configuration like this:
```sh
BACKEND_URL="https://pleroma.example.com"
PROXY_HTTPS_INSECURE=true
```
You will need to restart the local development server for the changes to take effect.
2020-04-07 01:30:05 +00:00
## Using with Mastodon
2020-04-21 18:34:18 +00:00
Local Mastodon runs on port 3000 by default, so you will need to edit the `.env` as described above and set it like this:
```
BACKEND_URL="http://localhost:3000"
```
2020-04-07 01:30:05 +00:00
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.
2020-04-21 18:34:18 +00:00
Then open your browser to soapbox-fe (`http://localhost:3036`), open the console, and insert the following code:
2020-04-07 01:30:05 +00:00
```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.
2020-04-21 18:34:18 +00:00
## Local Dev Configuration
The following configuration variables are supported supported in local development.
Edit `.env` to set them.
All configuration is optional.
#### `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`
#### `PATRON_URL`
URL to the [Soapbox Patron ](https://gitlab.com/soapbox-pub/soapbox-patron ) server, if you have one.
2020-04-26 04:27:02 +00:00
This setting is not useful unless `"extensions": { "patron": true }` is also set in `public/instance/soapbox.json` .
2020-04-21 18:34:18 +00:00
**Default:** `http://localhost:5000`
#### `PROXY_HTTPS_INSECURE`
Allows using an HTTPS backend if set to `true` .
This is needed if `BACKEND_URL` or `PATRON_URL` are set to an `https://` value.
[More info ](https://stackoverflow.com/a/48624590/8811886 ).
**Default:** `false`
2020-04-14 17:30:26 +00:00
# Yarn Commands
The following commands are supported.
#### Local dev server
- `yarn start` - Run the local dev server. It will proxy requests to the backend for you.
2020-04-14 21:50:42 +00:00
- `yarn dev` - Exact same as above, aliased to `yarn start` for convenience.
2020-04-14 17:30:26 +00:00
#### Building
- `yarn build:development` - Build for development.
- `yarn build:production` - Build for production.
#### Translations
- `yarn manage:translations` - Normalizes translation files. Should always be run after editing i18n strings.
#### Tests
2020-04-14 18:07:40 +00:00
- `yarn test` - Runs all tests.
2020-04-14 17:30:26 +00:00
- `yarn test:lint` - Runs all linter tests.
- `yarn test:lint:js` - Runs only JavaScript linter.
- `yarn test:lint:sass` - Runs only SASS linter.
- `yarn test:jest` - Frontend unit tests.
2020-03-28 21:06:29 +00:00
# License
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,
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 / > .
