docs - rough serialization and config file updates (#26389)

docs/README.md

@@ -153,7 +153,8 @@ Metabase's reference documentation.
 - [Email](./configuring-metabase/email.md)
 - [Slack](./configuring-metabase/slack.md)
 - [Environment variables](./configuring-metabase/environment-variables.md)
-- [Metabase logs](./configuring-metabase/log-configuration.md)
+- [Configuration file](./configuring-metabase/config-file.md)
+- [Metabase log configuration](./configuring-metabase/log-configuration.md)
 - [Timezones](./configuring-metabase/timezones.md)
 - [Languages and localization](./configuring-metabase/localization.md)
 - [Appearance](./configuring-metabase/appearance.md)

docs/configuring-metabase/config-file.md

+---
+title: "Configuration file"
+---
+
+# Configuration file
+
+{% include plans-blockquote.html feature="Loading from a configuration file" self-hosted-only="true" %}
+
+On some paid, self-hosted plans, Metabase supports initialization on launch from a config file named `config.yml`. This file should either be in the current directory (the directory where the running Metabase JAR is located), or in a path specified by the `MB_CONFIG_FILE_PATH` [environment variable](./environment-variables.md). In this config file, you can specify:
+
+- Settings
+- Users
+- Databases
+
+The settings as defined in the config file work the same as if you set these settings in the Admin Settings in your Metabase. Settings defined in this configuration file will update any existing settings. If, for example, a database already exists (that is, you'd already added it via initial set up or **Admin settings** > **Databases**, Metabase will update the database entry based on the data in the config file). 
+
+The config file settings are not treated as a hardcoded source of truth like [environment variables](./environment-variables.md) are.
+
+## Example `config.yml` file
+
+This file sets up a user account and two database connections.
+
+```
+version: 1
+config:
+  users:
+    - first_name: Cam
+      last_name: Era
+      password: 2cans3cans4cans
+      email: cam@example.com
+  databases:
+    - name: test-data (Postgres)
+      engine: postgres
+      details:
+        host: localhost
+        port: 5432
+        password: {% raw %} "{{ env POSTGRES_TEST_DATA_PASSWORD }}" {% endraw %}
+        dbname: test-data
+    - name: Sample Dataset (Copy)
+      engine: h2
+      details:
+        db: "/home/cam/metabase/resources/sample-database.db;USER=GUEST;PASSWORD={{env SAMPLE_DATASET_PASSWORD}}"
+```
+
+To determine which keys you can specify, simply look at the fields available in Metabase itself.
+
+## Referring to environment variables in the `config.yml`
+
+Environment variables can be specified with `{% raw %}{{ template-tags }}{% endraw %}` like `{% raw %}{{ env POSTGRES_TEST_DATA_PASSWORD }}{% endraw %}` or `{% raw %}[[options {{template-tags}}]]{% endraw %}`.
+
+Metabase doesn't support recursive expansion, so if one of your environment variables references _another_ environment variable, you're going to have a bad time.
+
+## Disable initial database sync
+
+When loading a data model from a serialized dump, you want to disable the scheduler so that the Metabase doesn't try to sync.
+
+To disable the initial database sync, you can add `config-from-file-sync-database` to the `settings` list and set the value to `false`. The setting `config-from-file-sync-database` must come _before_ the databases list, like so:
+
+```
+version: 1
+config:
+  settings:
+    config-from-file-sync-databases: false
+  databases:
+    - name: my-database
+      engine: h2
+      details: ...
+```
+
+## List of settings
+
+In general, the settings you can set in the `settings` section of this config file map to the [environment variables](./environment-variables.md).
+
+The actual key that you include in the config file differs slightly from the format used for environment variables. For environment variables, the form is in screaming snake case, prefixed by an `MB`:
+
+```
+MB_NAME_OF_VARIABLE
+```
+
+Whereas in the config file, you'd translate that to:
+
+```
+name-of-variable
+```
+
+So for example, if you wanted to specify the `MB_EMAIL_FROM_NAME` not in an environment variable, but instead in the `config.yml` file:
+
+```
+version: 1
+config:
+  settings:
+    config-from-file-sync-databases: false
+    email-from-name: Stampy von Mails-a-lot
+  databases:
+    - name: my-database
+      engine: h2
+      details: ...
+```
+
+ 

docs/configuring-metabase/environment-variables.md

@@ -188,6 +188,13 @@ Default: `true`
 
 Color log lines. When set to `false` it will disable log line colors. This is disabled on Windows. Related to [MB_EMOJI_IN_LOGS](#mb_emoji_in_logs).
 
+### `MB_CONFIG_FILE_PATH`
+
+Type: string<br>
+Default: `config.yml`
+
+This feature requires the `advanced-config` feature flag on your token.
+
 ### `MB_CUSTOM_FORMATTING`
 
 Type: string<br>

docs/configuring-metabase/start.md

@@ -20,7 +20,23 @@ Set up email for [Alerts](../questions/sharing/alerts.md) and [Dashboard subscri
 
 Set up Slack for Alerts and Dashboard subscriptions.
 
-## [Localization](./localization.md)
+## [Environment variables](./environment-variables.md)
+
+Configure Metabase on launch via environment variables.
+
+## [Configuration file](./config-file.md)
+
+On self-hosted paid plans, you can configure Metabase via a configuration file.
+
+## [Metabase logs configuration](./log-configuration.md)
+
+Tell Metabase what to log.
+
+## [Timezones](./timezones.md)
+
+Guidance on timezone settings.
+
+## [Languages and localization](./localization.md)
 
 Set language, datetime, and currency settings.
 
@@ -28,10 +44,14 @@ Set language, datetime, and currency settings.
 
 Customize colors, fonts, and other visual elements.
 
-## [Caching](./caching.md)
+## [Caching query results](./caching.md)
 
 Cache query results for faster loading times.
 
-## [Metabase logs configuration](./log-configuration.md)
+## [Custom maps](./custom-maps.md)
 
-Tell Metabase what to log.
+Upload custom maps to your Metabase.
+
+## [Customizing the Metabase Jetty webserver](./customizing-jetty-webserver.md)
+
+Set SSL and port settings for the Jetty webserver.

docs/paid-features/overview.md

@@ -81,3 +81,7 @@ See which queries are failing to help keep your Metabase tidy.
 You can export Metabase application data and use that to spin up new instances preloaded with questions, dashboards, and collections.
 
 - [Serialization](../installation-and-operation/serialization.md)
+
+## Configuration file
+
+For self-hosted installations, you can load Metabase from a [configuration file](../configuring-metabase/config-file.md).