kopia lustrzana https://gitlab.com/soapbox-pub/soapbox
Additional docs for new Soapbox Docs site
Sean King
rodzic
84b8afa73c
commit
c5296fb411
|
|
@ -0,0 +1,10 @@
|
|||
# Removing Soapbox
|
||||
|
||||
Removing Soapbox FE and reverting to Pleroma FE is really easy. Just run the following:
|
||||
```
|
||||
rm /opt/pleroma/instance/static/index.html
|
||||
rm -R /opt/pleroma/instance/static/packs
|
||||
rm -R /opt/pleroma/instance/static/sounds
|
||||
```
|
||||
|
||||
If you need to remove other stuff, feel free to do so. But be careful not to remove your own HTML files.
|
||||
|
|
@ -0,0 +1,37 @@
|
|||
# Updating Soapbox
|
||||
|
||||
You should always check the [release notes/changelog](https://gitlab.com/soapbox-pub/soapbox-fe/-/blob/develop/CHANGELOG.md) in case there are deprecations, special update changes, etc.
|
||||
|
||||
Besides that, it's relatively pretty easy to update Soapbox FE. There's two ways to go about it: with the command line or with an unofficial script.
|
||||
|
||||
## Updating with the command line
|
||||
|
||||
To update Soapbox FE via the command line, do the following:
|
||||
|
||||
```
|
||||
# Download the build.
|
||||
|
||||
curl -L https://gitlab.com/soapbox-pub/soapbox-fe/-/jobs/artifacts/v(latest.version.here)/download?job=build-production -o soapbox-fe.zip
|
||||
|
||||
# Remove all the current Soapbox FE build in Pleroma's instance directory.
|
||||
sudo rm -R /opt/pleroma/instance/static/packs
|
||||
sudo rm /opt/pleroma/instance/static/index.html
|
||||
sudo rm -R /opt/pleroma/instance/static/sounds
|
||||
|
||||
# Unzip the new build to Pleroma's instance directory.
|
||||
busybox unzip soapbox-fe.zip -o -d /opt/pleroma/instance
|
||||
```
|
||||
|
||||
## Updating with an unofficial script
|
||||
|
||||
You can also update Soapbox using [Sandia Mesa's updater bash script for Soapbox FE](https://code.sandiamesa.com/traboone/soapbox-update).
|
||||
|
||||
First, download the updater script if you haven't yet: ``curl -O https://code.sandiamesa.com/traboone/soapbox-update/raw/branch/master/soapbox-update.sh``
|
||||
|
||||
Then, set the permissions of the updater script so that it can be executed: ``chmod u+x soapbox-update.sh``
|
||||
|
||||
Finally, run ``sudo ./soapbox-update.sh``.
|
||||
|
||||
## After updating Soapbox
|
||||
|
||||
The changes take effect immediately, just refresh your browser tab. It's not necessary to restart the Pleroma service.
|
||||
|
|
@ -0,0 +1,8 @@
|
|||
# How it works
|
||||
|
||||
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.
|
||||
|
|
@ -0,0 +1,20 @@
|
|||
# Developing against a live 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 or VanwaNet.
|
||||
|
||||
To do so, just copy the env file:
|
||||
|
||||
```
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
And edit `.env`, setting the configuration like this:
|
||||
|
||||
```
|
||||
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.
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
# 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 FE checks for the following options:
|
||||
|
||||
- `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.
|
||||
|
||||
## `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`
|
||||
|
|
@ -0,0 +1,38 @@
|
|||
# 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:
|
||||
|
||||
```
|
||||
yarn dev
|
||||
```
|
||||
|
||||
**That's it!** 🎉
|
||||
|
||||
It will serve at `http://localhost:3036` by default.
|
||||
|
||||
It will proxy requests to the backend for you.
|
||||
For Pleroma running on `localhost:4000` (the default) no other changes are required, just start a local Pleroma server and it should begin working.
|
||||
|
||||
## Troubleshooting: `ERROR: NODE_ENV must be set`
|
||||
|
||||
Create a `.env` file if you haven't already.
|
||||
|
||||
```
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
And ensure that it contains `NODE_ENV=development`.
|
||||
Try again.
|
||||
|
|
@ -0,0 +1,29 @@
|
|||
# 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:
|
||||
|
||||
```
|
||||
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` - Runs all tests.
|
||||
|
||||
- `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.
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
# Removing Soapbox
|
||||
|
||||
Removing Soapbox FE and reverting to Pleroma FE is really easy. Just run the following:
|
||||
```
|
||||
rm /opt/pleroma/instance/static/index.html
|
||||
rm -R /opt/pleroma/instance/static/packs
|
||||
rm -R /opt/pleroma/instance/static/sounds
|
||||
```
|
||||
|
||||
If you need to remove other stuff, feel free to do so. But be careful not to remove your own HTML files.
|
||||
|
|
@ -0,0 +1,37 @@
|
|||
# Updating Soapbox
|
||||
|
||||
You should always check the [release notes/changelog](https://gitlab.com/soapbox-pub/soapbox-fe/-/blob/develop/CHANGELOG.md) in case there are deprecations, special update changes, etc.
|
||||
|
||||
Besides that, it's relatively pretty easy to update Soapbox FE. There's two ways to go about it: with the command line or with an unofficial script.
|
||||
|
||||
## Updating with the command line
|
||||
|
||||
To update Soapbox FE via the command line, do the following:
|
||||
|
||||
```
|
||||
# Download the build.
|
||||
|
||||
curl -L https://gitlab.com/soapbox-pub/soapbox-fe/-/jobs/artifacts/v(latest.version.here)/download?job=build-production -o soapbox-fe.zip
|
||||
|
||||
# Remove all the current Soapbox FE build in Pleroma's instance directory.
|
||||
sudo rm -R /opt/pleroma/instance/static/packs
|
||||
sudo rm /opt/pleroma/instance/static/index.html
|
||||
sudo rm -R /opt/pleroma/instance/static/sounds
|
||||
|
||||
# Unzip the new build to Pleroma's instance directory.
|
||||
busybox unzip soapbox-fe.zip -o -d /opt/pleroma/instance
|
||||
```
|
||||
|
||||
## Updating with an unofficial script
|
||||
|
||||
You can also update Soapbox using [Sandia Mesa's updater bash script for Soapbox FE](https://code.sandiamesa.com/traboone/soapbox-update).
|
||||
|
||||
First, download the updater script if you haven't yet: ``curl -O https://code.sandiamesa.com/traboone/soapbox-update/raw/branch/master/soapbox-update.sh``
|
||||
|
||||
Then, set the permissions of the updater script so that it can be executed: ``chmod u+x soapbox-update.sh``
|
||||
|
||||
Finally, run ``sudo ./soapbox-update.sh``.
|
||||
|
||||
## After updating Soapbox
|
||||
|
||||
The changes take effect immediately, just refresh your browser tab. It's not necessary to restart the Pleroma service.
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# Customizing Soapbox
|
||||
|
||||
If you haven't already, [install Soapbox](https://soapbox.pub/). But before you install soapbox, you should consider how Soapbox is installed, by default.
|
||||
If you haven't already, [install Soapbox](../installing). But before you install soapbox, you should consider how Soapbox is installed, by default.
|
||||
|
||||
Soapbox, by default, is installed to replace the default Pleroma front end. By extension, the Pleroma Masto front end continues to be available at the `/web` sub-URL, which you can reference, if you'd like, in the `promoPanel` section of `soapbox.json`
|
||||
|
||||
|
|
@ -104,4 +104,3 @@ These four template files have placeholders in them, e.g. "Your_Instance", that
|
|||
If you want to install Soapbox at an alternate URL, allowing you to potentially run more than 2 front ends on a Pleroma server, you can consider deploying the Nginx config created by @a1batross, available [here](https://git.mentality.rip/a1batross/soapbox-nginx-config/src/branch/master/soapbox.nginx)
|
||||
|
||||
Tech support is limited for this level of customization
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,20 @@
|
|||
# Installing Soapbox
|
||||
|
||||
This guide is a step-by-step guide for installing Soapbox. These instructions assume that you're using a fresh, new VPS powered by a Debian-based OS such as Ubuntu.
|
||||
|
||||
## Install Pleroma
|
||||
|
||||
First, follow the instructions to [install Pleroma](https://docs-develop.pleroma.social/backend/installation/debian_based_en/) on a fresh VPS. We recommend using Ubuntu 20.04 LTS.
|
||||
|
||||
**Note:** If you followed the directions for installing on Linux with OTP Releases, create the following symlink in the pleroma user's home:
|
||||
``su pleroma -s $SHELL -lc "ln -s /var/lib/pleroma /opt/pleroma/instance"``
|
||||
|
||||
## Install Soapbox
|
||||
|
||||
The Soapbox frontend is the main component of Soapbox. Once you've installed Pleroma, installing Soapbox FE is a breeze.
|
||||
|
||||
First, ssh into the server and download a .zip of the latest build: ``curl -L https://gitlab.com/soapbox-pub/soapbox-fe/-/jobs/artifacts/v1.0.0/download?job=build-production -o soapbox-fe.zip``
|
||||
|
||||
Then unpack it into Pleroma's ``instance`` directory: ``busybox unzip soapbox-fe.zip -o -d /opt/pleroma/instance``
|
||||
|
||||
**That's it! 🎉 Soapbox FE is installed.** The change will take effect immediately, just refresh your browser tab. It's not necessary to restart the Pleroma service.
|
||||
Ładowanie…
Reference in New Issue