191 lines
5.9 KiB
Markdown
191 lines
5.9 KiB
Markdown
# Build Configuration
|
|
|
|
Soapbox supports compile-time customizations in the form of environment variables and a gitignored `custom/` directory.
|
|
|
|
## `custom/` directory
|
|
|
|
You can place files into the `custom/` directory to customize the Soapbox build.
|
|
|
|
### Custom snippets (`custom/snippets.html`)
|
|
|
|
If you'd like to include analytics snippets, custom meta tags, or anything else in the `<head>` of the document, you may do so by creating a `custom/snippets.html` file.
|
|
|
|
For example:
|
|
|
|
```html
|
|
<link href='/icons/icon-57x57.png' rel='apple-touch-icon' sizes='57x57'>
|
|
<link href='/icons/icon-64x64.png' rel='apple-touch-icon' sizes='64x64'>
|
|
<link href='/icons/icon-72x72.png' rel='apple-touch-icon' sizes='72x72'>
|
|
<link href='/icons/icon-114x114.png' rel='apple-touch-icon' sizes='114x114'>
|
|
<link href='/icons/icon-120x120.png' rel='apple-touch-icon' sizes='120x120'>
|
|
<link href='/icons/icon-180x180.png' rel='apple-touch-icon' sizes='180x180'>
|
|
<link href='/icons/icon-192x192.png' rel='apple-touch-icon' sizes='192x192'>
|
|
<link href='/icons/icon-512x512.png' rel='apple-touch-icon' sizes='512x512'>
|
|
<!-- Matomo -->
|
|
<script>
|
|
var _paq = window._paq = window._paq || [];
|
|
/* tracker methods like "setCustomDimension" should be called before "trackPageView" */
|
|
_paq.push(['trackPageView']);
|
|
_paq.push(['enableLinkTracking']);
|
|
(function() {
|
|
var u="//trk.bonsa.net/";
|
|
_paq.push(['setTrackerUrl', u+'matomo.php']);
|
|
_paq.push(['setSiteId', '12345678']);
|
|
var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
|
|
g.async=true; g.src=u+'matomo.js'; s.parentNode.insertBefore(g,s);
|
|
})();
|
|
</script>
|
|
```
|
|
|
|
The snippet will be included **before** any Soapbox application code.
|
|
|
|
### Custom locales (`custom/locales/*.json`)
|
|
|
|
It is possible to override locale messages by creating a file for each language, eg `custom/locales/en.json`.
|
|
In this file, add only the messages you want to be overridden.
|
|
|
|
For example:
|
|
|
|
```json
|
|
{
|
|
"account.posts": "Poasts",
|
|
"account.posts_with_replies": "Poasts & Replies",
|
|
"compose.submit_success": "Your poast was sent!",
|
|
"compose_form.publish": "Poast"
|
|
}
|
|
```
|
|
|
|
These messages will be merged into the language file shipped with Soapbox.
|
|
|
|
### Feature overrides (`custom/features.json`)
|
|
|
|
You can create a file called `custom/features.json` to disable version-checking and force some features on or off.
|
|
|
|
For example:
|
|
|
|
```json
|
|
{
|
|
"bookmarks": false,
|
|
"lists": false,
|
|
"quotePosts": true
|
|
}
|
|
```
|
|
|
|
See `app/soapbox/utils/features.js` for the full list of features.
|
|
|
|
### Embedded app (`custom/app.json`)
|
|
|
|
By default, Soapbox will create a new OAuth app every time a user tries to register or log in.
|
|
This is usually the desired behavior, as it works "out of the box" without any additional configuration, and it is resistant to tampering and subtle client bugs.
|
|
However, some larger servers may wish to skip this step for performance reasons.
|
|
|
|
If an app is supplied in `custom/app.json`, it will be used for authorization.
|
|
The full app entity must be provided, for example:
|
|
|
|
```json
|
|
{
|
|
"client_id": "cf5yI6ffXH1UcDkEApEIrtHpwCi5Tv9xmju8IKdMAkE",
|
|
"client_secret": "vHmSDpm6BJGUvR4_qWzmqWjfHcSYlZumxpFfohRwNNQ",
|
|
"id": "7132",
|
|
"name": "Soapbox",
|
|
"redirect_uri": "urn:ietf:wg:oauth:2.0:oob",
|
|
"website": "https://soapbox.pub/",
|
|
"vapid_key": "BLElLQVJVmY_e4F5JoYxI5jXiVOYNsJ9p-amkykc9NcI-jwa9T1Y2GIbDqbY-HqC6ayPkfW4K4o9vgBFKYmkuS4"
|
|
}
|
|
```
|
|
|
|
It is crucial that the app has the expected scopes.
|
|
You can obtain one with the following curl command (replace `MY_DOMAIN`):
|
|
|
|
```sh
|
|
curl -X POST -H "Content-Type: application/json" -d '{"client_name": "Soapbox", "redirect_uris": "urn:ietf:wg:oauth:2.0:oob", "scopes": "read write follow push admin", "website": "https://soapbox.pub/"}' "https://MY_DOMAIN.com/api/v1/apps"
|
|
```
|
|
|
|
### Custom files (`custom/instance/*`)
|
|
|
|
You can place arbitrary files of any type in the `custom/instance/` directory.
|
|
They will be available on your website at `https://example.com/instance/{filename}`.
|
|
Subdirectories are supported, too.
|
|
|
|
Some use cases:
|
|
|
|
- Logos, which can then be referenced from `soapbox.json`
|
|
- About pages, available at `/about` on your website.
|
|
|
|
## Environment variables
|
|
|
|
When compiling Soapbox, environment variables may be passed to change the build itself.
|
|
For example:
|
|
|
|
```sh
|
|
NODE_ENV="production" FE_BUILD_DIR="public" FE_SUBDIRECTORY="/soapbox" yarn build
|
|
```
|
|
|
|
### `NODE_ENV`
|
|
|
|
The environment to build Soapbox for.
|
|
|
|
Options:
|
|
|
|
- `"production"` - For live sites
|
|
- `"development"` - For local development
|
|
- `"test"` - Bootstraps test environment
|
|
|
|
Default: `"development"`
|
|
|
|
It's recommended to always build in `"production"` mode for live sites.
|
|
|
|
### `BACKEND_URL`
|
|
|
|
The base URL for API calls.
|
|
You only need to set this if Soapbox is hosted in a different place than the backend.
|
|
|
|
Options:
|
|
|
|
- An absolute URL, eg `"https://gleasonator.com"`
|
|
- Empty string (`""`)`
|
|
|
|
Default: `""`
|
|
|
|
### `FE_BUILD_DIR`
|
|
|
|
The folder to put build files in. This is mostly useful for CI tasks like GitLab Pages.
|
|
|
|
Options:
|
|
|
|
- Any directory name, eg `"public"`
|
|
|
|
Default: `"static"`
|
|
|
|
### `FE_SUBDIRECTORY`
|
|
|
|
Subdirectory to host Soapbox out of.
|
|
When hosting on a subdirectory, you must create a custom build for it.
|
|
This option will set the imports in `index.html`, and the basename for routes in React.
|
|
|
|
Options:
|
|
|
|
- Any path, eg `"/soapbox"` or `"/fe/soapbox"`
|
|
|
|
Default: `"/"`
|
|
|
|
For example, if you want to host the build on `https://gleasonator.com/soapbox`, you can compile it like this:
|
|
|
|
```sh
|
|
NODE_ENV="production" FE_SUBDIRECTORY="/soapbox" yarn build
|
|
```
|
|
|
|
### `SENTRY_DSN`
|
|
|
|
[Sentry](https://sentry.io/) endpoint for this custom build.
|
|
|
|
Sentry is an error monitoring service that may be optionally included.
|
|
When an endpoint is not configured, it does nothing.
|
|
|
|
Sentry's backend was FOSS until 2019 when it moved to source-available, but a BSD-3 fork called [GlitchTip](https://glitchtip.com/) may also be used.
|
|
|
|
Options:
|
|
|
|
- Endpoint URL, eg `"https://abcdefg@app.glitchtip.com/123"`
|
|
|
|
Default: `""`
|