Merge branch 'new_docs' into 'develop'

Additional docs for new Soapbox Docs site

See merge request soapbox-pub/soapbox-fe!181

docs/administration/administration/removing.md

@@ -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.

docs/administration/administration/updating.md

@@ -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.

docs/administration/development/how-it-works.md

@@ -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.

docs/administration/development/live-backend.md

@@ -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.

docs/administration/development/local-config.md

@@ -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`

docs/administration/development/running-locally.md

@@ -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.

docs/administration/development/yarn-commands.md

@@ -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.

docs/administration/removing.md

@@ -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.

docs/administration/updating.md

@@ -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.

docs/customization.md

@@ -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
-

docs/installing.md

@@ -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.