kopia lustrzana https://gitlab.com/soapbox-pub/soapbox
Overhaul README
Alex Gleason
rodzic
34ae2e36d6
commit
c64b7d8ba9
209
README.md
209
README.md
|
|
@ -1,209 +1,82 @@
|
|||
# Soapbox
|
||||
|
||||
|
||||
|
||||
**Soapbox** is a frontend for Mastodon and Pleroma with a focus on custom branding and ease of use.
|
||||
**Soapbox** is customizable open-source software that puts the power of social media in the hands of the people. Feature-rich and hyper-focused on providing a user experience to rival Big Tech, Soapbox is already home to some of the biggest alternative social platforms.
|
||||
|
||||
## Try it out
|
||||
# On The Fediverse
|
||||
|
||||
Visit https://fe.soapbox.pub/ and point it to your favorite instance.
|
||||
You may have heard of **Mastodon**. Soapbox builds upon what Mastodon made great to make something even better.
|
||||
|
||||
## :rocket: Deploy on Pleroma
|
||||
You can run **Mastodon+Soapbox**, **Rebased+Soapbox**, and more.
|
||||
|
||||
Installing Soapbox on an existing Pleroma server is extremely easy.
|
||||
Just ssh into the server and download a .zip of the latest build:
|
||||
Soapbox is the **frontend** (what users see) while Mastodon is the **backend** (data, APIs). You can mix-and-match in the Fediverse ecosystem.
|
||||
|
||||
```sh
|
||||
curl -L https://gitlab.com/soapbox-pub/soapbox/-/jobs/artifacts/develop/download?job=build-production -o soapbox.zip
|
||||
```
|
||||
> 💡 If you're starting a new server, we highly recommend **Rebased+Soapbox**. Rebased is our custom-built backend just for Soapbox, providing important new features such as **quote posting** and **chats**.
|
||||
>
|
||||
> See: [Installing Rebased+Soapbox](https://soapbox.pub/install/)
|
||||
|
||||
Then unpack it into Pleroma's `instance` directory:
|
||||
# Try It Out
|
||||
|
||||
```sh
|
||||
busybox unzip soapbox.zip -o -d /opt/pleroma/instance
|
||||
```
|
||||
Want to give Soapbox a shot? Here are some suggested servers:
|
||||
|
||||
**That's it!** :tada:
|
||||
**Soapbox is installed.**
|
||||
The change will take effect immediately, just refresh your browser tab.
|
||||
It's not necessary to restart the Pleroma service.
|
||||
- [gleasonator.com](https://gleasonator.com/) - operated by the lead developer of Soapbox
|
||||
- [pl.fediverse.pl](https://pl.fediverse.pl/) - Polish server run by a Soapbox maintainer
|
||||
- [social.teci.world](https://social.teci.world/) - free speech server run by a Soapbox contributor
|
||||
- [spinster.xyz](https://spinster.xyz/) - one of the largest feminist communities on the internet
|
||||
- [poa.st](https://poa.st/) - the largest Soapbox server on the network
|
||||
|
||||
**_For OTP releases,_** _unpack to /var/lib/pleroma instead._
|
||||
Want to use Soapbox against **any existing Mastodon/Pleroma server?** Try:
|
||||
|
||||
To remove Soapbox 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).
|
||||
- [fe.soapbox.pub](https://fe.soapbox.pub) - enter your server's domain name to use Soapbox on any server!
|
||||
|
||||
## :elephant: Deploy on Mastodon
|
||||
# 🚀 Starting Your Own Server
|
||||
|
||||
See [Installing Soapbox over Mastodon](https://docs.soapbox.pub/frontend/administration/mastodon/).
|
||||
Starting your own server is one of the best ways to have freedom online! We recommend installing **Rebased+Soapbox**.
|
||||
|
||||
## How does it work?
|
||||
See here for a detailed setup guide: [Installing Rebased+Soapbox](https://soapbox.pub/install/)
|
||||
|
||||
Soapbox is a [single-page application (SPA)](https://en.wikipedia.org/wiki/Single-page_application) that runs entirely in the browser with JavaScript.
|
||||
# Adding Soapbox to an Existing Server
|
||||
|
||||
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).
|
||||
Already have a server? No problem — it is still possible to use Soapbox.
|
||||
|
||||
Here is a simplified example with Nginx:
|
||||
- [Deploying on Pleroma](https://docs.soapbox.pub/frontend/installing/#install-soapbox)
|
||||
- [Deploying on Mastodon](https://docs.soapbox.pub/frontend/administration/mastodon/)
|
||||
|
||||
```nginx
|
||||
location /api {
|
||||
proxy_pass http://backend;
|
||||
}
|
||||
> 💡 If using Pleroma, it's recommended to [upgrade it to Rebased](https://gitlab.com/-/snippets/2411739). This comes with better support and many new features, helping you get the most out of Soapbox.
|
||||
|
||||
location / {
|
||||
root /opt/soapbox;
|
||||
try_files $uri index.html;
|
||||
}
|
||||
```
|
||||
# Developing Soapbox
|
||||
|
||||
(See [`mastodon.conf`](https://gitlab.com/soapbox-pub/soapbox/-/blob/develop/installation/mastodon.conf) for a full example.)
|
||||
tl;dr — `git clone`, `yarn`, and `yarn dev`.
|
||||
|
||||
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.
|
||||
For detailed guides, see these pages:
|
||||
|
||||
# Running locally
|
||||
1. [Soapbox local development](https://docs.soapbox.pub/frontend/development/running-locally/)
|
||||
2. [yarn commands](https://docs.soapbox.pub/frontend/development/yarn-commands/)
|
||||
3. [How it works](https://docs.soapbox.pub/frontend/development/how-it-works/)
|
||||
4. [Environment variables](https://docs.soapbox.pub/frontend/development/local-config/)
|
||||
5. [Developing a backend](https://docs.soapbox.pub/frontend/development/developing-backend/)
|
||||
|
||||
To get it running, just clone the repo:
|
||||
|
||||
```sh
|
||||
git clone https://gitlab.com/soapbox-pub/soapbox.git
|
||||
cd soapbox
|
||||
```
|
||||
|
||||
Ensure that Node.js and Yarn are installed, then install dependencies:
|
||||
|
||||
```sh
|
||||
yarn
|
||||
```
|
||||
|
||||
Finally, run the dev server:
|
||||
|
||||
```sh
|
||||
yarn dev
|
||||
```
|
||||
|
||||
**That's it!** :tada:
|
||||
|
||||
It will serve at `http://localhost:3036` by default.
|
||||
|
||||
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`!
|
||||
|
||||
### 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.
|
||||
|
||||
### Troubleshooting: it's not working!
|
||||
|
||||
Run `node -V` and compare your Node.js version with the version in [`.tool-versions`](https://gitlab.com/soapbox-pub/soapbox/-/blob/develop/.tool-versions).
|
||||
If they don't match, try installing [asdf](https://asdf-vm.com/).
|
||||
|
||||
## Local Dev Configuration
|
||||
|
||||
The following configuration variables are supported supported in local development.
|
||||
Edit `.env` to set them.
|
||||
|
||||
All configuration is optional, except `NODE_ENV`.
|
||||
|
||||
#### `NODE_ENV`
|
||||
|
||||
The Node environment.
|
||||
Soapbox checks for the following options:
|
||||
|
||||
- `development` - What you should use while developing Soapbox.
|
||||
- `production` - Use when compiling to deploy to a live server.
|
||||
- `test` - Use when running automated tests.
|
||||
|
||||
#### `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`.
|
||||
|
||||
This is needed if `BACKEND_URL` is set to an `https://` value.
|
||||
[More info](https://stackoverflow.com/a/48624590/8811886).
|
||||
|
||||
**Default:** `false`
|
||||
|
||||
# Yarn Commands
|
||||
|
||||
The following commands are supported.
|
||||
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
|
||||
```
|
||||
|
||||
#### Local dev server
|
||||
|
||||
- `yarn dev` - Run the local dev server.
|
||||
|
||||
#### Building
|
||||
|
||||
- `yarn build` - Compile without a dev server, into `/static` directory.
|
||||
|
||||
#### Translations
|
||||
|
||||
- `yarn manage:translations` - Normalizes translation files. Should always be run after editing i18n strings.
|
||||
|
||||
#### Tests
|
||||
|
||||
- `yarn test:all` - Runs all tests and linters.
|
||||
|
||||
- `yarn test` - Runs Jest for frontend unit tests.
|
||||
|
||||
- `yarn lint` - Runs all linters.
|
||||
|
||||
- `yarn lint:js` - Runs only JavaScript linter.
|
||||
|
||||
- `yarn lint:sass` - Runs only SASS linter.
|
||||
|
||||
# Contributing
|
||||
## Contributing
|
||||
|
||||
We welcome contributions to this project.
|
||||
To contribute, see [Contributing to Soapbox](docs/contributing.md).
|
||||
|
||||
Translators can help by providing [translations through Weblate](http://hosted.weblate.org/soapbox-pub/soapbox/).
|
||||
Translators can help by providing [translations through Weblate](https://hosted.weblate.org/projects/soapbox-pub/soapbox/).
|
||||
Native speakers from all around the world are welcome!
|
||||
|
||||
# Customization
|
||||
# Project Philosophy
|
||||
|
||||
Soapbox supports customization of the user interface, to allow per-instance branding and other features.
|
||||
Some examples include:
|
||||
Soapbox was born out of the need to build independent platforms with **a unique identity and brand**.
|
||||
|
||||
- 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
|
||||
This is in contrast to Mastodon's idea, where all servers are called "Mastodon" and use the Mastodon colors and logo. Users won't see the word "Soapbox" throughout the UI, they'll see the name of **your website** and your logo. To facilitate this, Soapbox has a robust customization UI and integrated moderation tools. Large servers are a priority.
|
||||
|
||||
More details can be found in [Customizing Soapbox](docs/customization.md).
|
||||
One disadvantage of this approach is that it does not help the software spread. Some of the biggest servers on the network and running Soapbox and people don't even know it!
|
||||
|
||||
# License & Credits
|
||||
|
||||
Soapbox 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.
|
||||
|
||||
- `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.
|
||||
- `app/assets/sounds/chat.mp3` and `app/assets/sounds/chat.oga` are from [notificationsounds.com](https://notificationsounds.com/notification-sounds/intuition-561), licensed under CC BY 4.0.
|
||||
- `soapbox-screenshot.png` was created using [Vectary 3D](https://help.vectary.com/figma-plugin) with assets licensed under CC0. The resulting file is licensed under CC BY 4.0.
|
||||
|
||||
Soapbox is free software: you can redistribute it and/or modify
|
||||
it under the terms of the GNU Affero General Public License as published by
|
||||
|
|
|
|||
Plik binarny nie jest wyświetlany.
|
Przed Szerokość: | Wysokość: | Rozmiar: 512 KiB Po Szerokość: | Wysokość: | Rozmiar: 469 KiB |
Ładowanie…
Reference in New Issue