2020-06-10 18:32:03 +00:00
# Soapbox FE
2020-03-28 21:06:29 +00:00
2020-05-24 13:57:41 +00:00
![Soapbox FE Screenshot ](soapbox-screenshot.png )
2022-03-17 19:45:40 +00:00
**Soapbox FE** is a frontend for Mastodon and Pleroma with a focus on custom branding and ease of use.
2020-04-25 19:42:16 +00:00
It's part of the [Soapbox ](https://soapbox.pub ) project.
2022-03-17 19:45:40 +00:00
## Try it out
Visit https://fe.soapbox.pub/ and point it to your favorite instance.
## :rocket: Deploy on Pleroma
2020-04-26 21:30:39 +00:00
2020-06-10 18:32:03 +00:00
Installing Soapbox FE on an existing Pleroma server is extremely easy.
2020-04-26 21:30:39 +00:00
Just ssh into the server and download a .zip of the latest build:
```sh
2022-05-10 17:03:16 +00:00
curl -L https://gitlab.com/soapbox-pub/soapbox-fe/-/jobs/artifacts/v2.0.0/download?job=build-production -o soapbox-fe.zip
2020-04-26 21:30:39 +00:00
```
Then unpack it into Pleroma's `instance` directory:
```sh
busybox unzip soapbox-fe.zip -o -d /opt/pleroma/instance
```
**That's it!** :tada:
2020-06-10 18:32:03 +00:00
**Soapbox FE is installed.**
2020-04-26 21:30:39 +00:00
The change will take effect immediately, just refresh your browser tab.
It's not necessary to restart the Pleroma service.
2021-01-20 01:00:28 +00:00
To remove Soapbox FE and revert to the default pleroma-fe, simply `rm /opt/pleroma/instance/static/index.html` (you can delete other stuff in there too, but be careful not to delete your own HTML files).
2020-06-10 18:32:03 +00:00
2022-07-18 16:28:29 +00:00
## :elephant: Deploy on Mastodon
See [Installing Soapbox over Mastodon ](https://docs.soapbox.pub/frontend/administration/mastodon/ ).
2020-06-10 18:32:03 +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 ).
2022-07-18 16:28:29 +00:00
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-fe/-/blob/develop/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.
2020-04-26 21:30:39 +00:00
2020-04-30 16:42:09 +00:00
# Running locally
2020-04-07 01:30:05 +00:00
To get it running, just clone the repo:
2020-04-26 17:49:20 +00:00
```sh
2020-04-07 01:30:05 +00:00
git clone https://gitlab.com/soapbox-pub/soapbox-fe.git
cd soapbox-fe
```
Ensure that Node.js and Yarn are installed, then install dependencies:
2020-04-26 17:49:20 +00:00
```sh
2020-04-07 01:30:05 +00:00
yarn
```
Finally, run the dev server:
2020-04-26 17:49:20 +00:00
```sh
2020-07-26 20:09:45 +00:00
yarn dev
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.
2022-07-18 16:28:29 +00:00
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` !
2020-04-21 18:34:18 +00:00
2020-04-26 17:49:20 +00:00
### 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.
2022-07-18 16:28:29 +00:00
### Troubleshooting: it's not working!
2020-04-21 18:34:18 +00:00
2022-07-18 16:28:29 +00:00
Run `node -V` and compare your Node.js version with the version in [`.tool-versions` ](https://gitlab.com/soapbox-pub/soapbox-fe/-/blob/develop/.tool-versions ).
If they don't match, try installing [asdf ](https://asdf-vm.com/ ).
2020-04-07 01:30:05 +00:00
2020-04-30 16:42:09 +00:00
## Local Dev Configuration
2020-04-21 18:34:18 +00:00
The following configuration variables are supported supported in local development.
Edit `.env` to set them.
2020-04-26 17:49:20 +00:00
All configuration is optional, except `NODE_ENV` .
#### `NODE_ENV`
The Node environment.
2020-06-10 18:32:03 +00:00
Soapbox FE checks for the following options:
2020-04-26 17:49:20 +00:00
2020-06-10 18:32:03 +00:00
- `development` - What you should use while developing Soapbox FE.
2020-04-26 17:49:20 +00:00
- `production` - Use when compiling to deploy to a live server.
- `test` - Use when running automated tests.
2020-04-21 18:34:18 +00:00
#### `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` .
2020-06-30 22:33:21 +00:00
This is needed if `BACKEND_URL` is set to an `https://` value.
2020-04-21 18:34:18 +00:00
[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.
2020-04-26 17:49:20 +00:00
You must set `NODE_ENV` to use these commands.
To do so, you can add the following line to your `.env` file:
```sh
NODE_ENV=development
```
2020-04-14 17:30:26 +00:00
#### Local dev server
2020-07-26 20:09:45 +00:00
- `yarn dev` - Run the local dev server.
2020-04-14 21:50:42 +00:00
2020-04-14 17:30:26 +00:00
#### Building
2020-04-26 19:41:04 +00:00
- `yarn build` - Compile without a dev server, into `/static` directory.
2020-04-14 17:30:26 +00:00
#### Translations
- `yarn manage:translations` - Normalizes translation files. Should always be run after editing i18n strings.
#### Tests
2022-04-04 15:50:14 +00:00
- `yarn test:all` - Runs all tests and linters.
2020-04-14 17:30:26 +00:00
2022-04-04 15:50:14 +00:00
- `yarn test` - Runs Jest for frontend unit tests.
2020-04-14 17:30:26 +00:00
2022-04-04 15:50:14 +00:00
- `yarn lint` - Runs all linters.
2020-04-14 17:30:26 +00:00
2022-04-04 15:50:14 +00:00
- `yarn lint:js` - Runs only JavaScript linter.
2020-04-14 17:30:26 +00:00
2022-04-04 15:50:14 +00:00
- `yarn lint:sass` - Runs only SASS linter.
2020-04-14 17:30:26 +00:00
2020-05-01 20:12:02 +00:00
# Contributing
2022-07-18 16:48:55 +00:00
We welcome contributions to this project.
To contribute, see [Contributing to Soapbox ](docs/contributing.md ).
2020-05-01 20:12:02 +00:00
# Customization
2022-07-18 17:12:50 +00:00
Soapbox supports customization of the user interface, to allow per-instance branding and other features.
Some examples include:
- Instance name
- Site logo
- Favicon
- About page
- Terms of Service page
- Privacy Policy page
- Copyright Policy (DMCA) page
- Promo panel list items, e.g. blog site link
- Soapbox extensions, e.g. Patron module
- Default settings, e.g. default theme
More details can be found in [Customizing Soapbox ](docs/customization.md ).
2020-05-01 20:12:02 +00:00
2020-06-10 18:32:03 +00:00
# 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.
2020-03-28 21:06:29 +00:00
2020-09-18 04:10:58 +00:00
- `static/sounds/chat.mp3` and `static/sounds/chat.oga` are from [notificationsounds.com ](https://notificationsounds.com/notification-sounds/intuition-561 ) licensed under CC BY 4.0.
2020-06-10 18:32:03 +00:00
Soapbox FE is free software: you can redistribute it and/or modify
2020-03-28 21:06:29 +00:00
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.
2020-06-10 18:32:03 +00:00
Soapbox FE is distributed in the hope that it will be useful,
2020-03-28 21:06:29 +00:00
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
2020-06-10 18:32:03 +00:00
along with Soapbox FE. If not, see < https: / / www . gnu . org / licenses / > .