5556767ff7
* [docs] Change configuration creation instructions This changes the wording to push people towards creating their own configuration, without copying the whole example configuration. This makes it much easier to reconcile necessary configruation changes on upgrades. * [docs] Reword container version section This changes the wording in the Version section to make it more clear what the risks of a moving tag are. It pushes people to use an explicit release tag instead.
3.9 KiB
Configuration Overview
GoToSocial aims to be as configurable as possible, to fit lots of different use cases.
We try to provide sensible defaults wherever possible, but you can't run a GoToSocial instance without managing some configuration.
Configuration Methods
There are three different methods for configuring a GoToSocial instance, which can be combined depending on your setup.
Configuration File
The easiest way to configure GoToSocial is to pass a configuration file to to the gotosocial server start command, for example:
gotosocial --config-path ./config.yaml server start
The command expects a file in YAML or JSON format.
An example configuration file, with an explanation of each of the config fields, with default and example values, can be found here. This example file is also included in release downloads.
It's recommended to create your own configuration file with only the settings you need to change for your installation. This ensures you don't have to reconcile changes to defaults or adding/updating/removing settings from your configuration file that you haven't changed away from the defaults on every release.
Environment Variables
You can also configure GoToSocial by setting environment variables. These environment variables follow the format:
- Prepend
GTS_to the config flag. - Uppercase-all.
- Replace dash (
-) with underscore (_).
So for example, instead of setting media-image-max-size to 2097152 in your config.yaml, you could set the environment variable:
GTS_MEDIA_IMAGE_MAX_SIZE=2097152
If you're in doubt about any of the names of these environment variables, just check the --help for the subcommand you're using.
!!! tip "Environment variable arrays"
If you need to use an environment variable to set a configuration option that accepts an array, provide each value in a comma-separated list.
For example, `instance-languages` may be set in the config.yaml file as an array like so: `["nl", "de", "fr", "en"]`. To set the same values as an environment variable, use: `GTS_INSTANCE_LANGUAGES="nl,de,fr,en"`
Command Line Flags
Finally, you can set configuration values using command-line flags, which you pass directly when you're running a gotosocial command. For example, instead of setting media-image-max-size in your config.yaml, or with an environment variable, you can pass the value directly through the command line:
gotosocial server start --media-image-max-size 2097152
If you're in doubt about which flags are available, check gotosocial --help.
Priority
The above configuration methods override each other in the order in which they were listed.
command line flags > environment variables > config file
That is, if you set media-image-max-size to 2097152 in your config file, but then ALSO set the environment variable GTS_MEDIA_MAX_IMAGE_SIZE=9999999, then the final value will be 9999999, because environment variables have a higher priority than values set in config.yaml.
Command line flags have the highest priority, so if you set --media-image-max-size 13121312, then the final value will be 13121312 regardless of what you've set elsewhere.
This means in cases where you want to just try changing one thing, but don't want to edit your config file, you can temporarily use an environment variable or a command line flag to set that one thing.
Default Values
Reasonable default values are provided for most of the configuration parameters, except in cases where a custom value is absolutely required.
See the example config file for the default values, or run gotosocial --help.