From a330f612b7b51f0eb1af981204ffac2eaa083905 Mon Sep 17 00:00:00 2001
From: Alex Yarosh <alexandra@metabase.com>
Date: Thu, 2 May 2024 14:03:05 -0600
Subject: [PATCH] [docs] Add TOC to a few articles (#42181)

* add TOC to Jetty article

* add ToC for debian article

* vvariables

* Update docs/installation-and-operation/running-metabase-on-debian.md

Co-authored-by: Jeff Bruemmer <jeff.bruemmer@gmail.com>

---------

Co-authored-by: Jeff Bruemmer <jeff.bruemmer@gmail.com>
---
 .../customizing-jetty-webserver.md            | 18 ++++----
 .../running-metabase-on-debian.md             | 43 ++++++++++---------
 2 files changed, 31 insertions(+), 30 deletions(-)

diff --git a/docs/configuring-metabase/customizing-jetty-webserver.md b/docs/configuring-metabase/customizing-jetty-webserver.md
index 59d6cb107e6..d7dd416eded 100644
--- a/docs/configuring-metabase/customizing-jetty-webserver.md
+++ b/docs/configuring-metabase/customizing-jetty-webserver.md
@@ -8,7 +8,7 @@ redirect_from:
 
 In most cases there will be no reason to modify any of the settings around how Metabase runs its embedded Jetty webserver to host the application, but if you wish to run HTTPS directly with your Metabase server or if you need to run on another port, that's all configurable.
 
-### Running Metabase on another port
+## Running Metabase on another port
 
 By default Metabase will launch on port 3000, but if you prefer to run the application on another port you can do so by setting the following environment variable:
 
@@ -17,25 +17,23 @@ By default Metabase will launch on port 3000, but if you prefer to run the appli
 
 In this example once the application starts up you will access it on port `12345` instead of the default port of 3000.
 
+## Listening on a specific network interface
 
-### Listening on a specific network interface
-
-By default, Metabase will be listening on `localhost`.  In some production environments you may want to listen on a different interface, which can be done by using the `MB_JETTY_HOST` environment variable:
+By default, Metabase will be listening on `localhost`. In some production environments you may want to listen on a different interface, which can be done by using the `MB_JETTY_HOST` environment variable:
 
     export MB_JETTY_HOST=0.0.0.0
     java -jar metabase.jar
 
+## Using HTTPS with Metabase
 
-### Using HTTPS with Metabase
-
-If you have an SSL certificate and would prefer to have Metabase run over HTTPS directly using its webserver you can do so by using the following environment variables:
+If you have an SSL certificate and would prefer to have Metabase run over HTTPS directly using its webserver, you can do so by using the following environment variables:
 
     export MB_JETTY_SSL="true"
     export MB_JETTY_SSL_PORT="8443"
-    export MB_JETTY_SSL_KEYSTORE="path/to/keystore.jks" # replace these values with your own
-    export MB_JETTY_SSL_KEYSTORE_PASSWORD="storepass"
+    export MB_JETTY_SSL_KEYSTORE="path/to/keystore.jks" # replace this value with your own
+    export MB_JETTY_SSL_KEYSTORE_PASSWORD="storepass" # replace this value with your own
     java -jar metabase.jar
 
 Be sure to replace `path/to/keystore.jks` and `storepass` with the correct path to and password for your [Java KeyStore](https://www.digitalocean.com/community/tutorials/java-keytool-essentials-working-with-java-keystores). With the above settings applied you will be running Metabase on port 8443 over HTTPS using the supplied certificate.
 
-No idea how to generate a Java KeyStore yourself? This is sort of an advanced topic, but if you're feeling froggy you can read more about how to configure SSL in Jetty [in their own documentation](https://www.eclipse.org/jetty/documentation/jetty-9/index.html#configuring-ssl). Otherwise, you'll probably find it easiest to handle SSL termination outside of Metabase.
\ No newline at end of file
+No idea how to generate a Java KeyStore yourself? This is sort of an advanced topic, but if you're feeling froggy you can read more about how to configure SSL in Jetty [in their own documentation](https://www.eclipse.org/jetty/documentation/jetty-9/index.html#configuring-ssl). Otherwise, you'll probably find it easiest to handle SSL termination outside of Metabase.
diff --git a/docs/installation-and-operation/running-metabase-on-debian.md b/docs/installation-and-operation/running-metabase-on-debian.md
index 398e4e7713b..4a13407ee31 100644
--- a/docs/installation-and-operation/running-metabase-on-debian.md
+++ b/docs/installation-and-operation/running-metabase-on-debian.md
@@ -8,18 +8,18 @@ redirect_from:
 
 For those people who don't (or can't) use Docker in their infrastructure, there's still a need to easily setup and deploy Metabase in production. On Debian-based systems, this means registering Metabase as a service that can be started/stopped/uninstalled.
 
-**Note:** This is just a *bare-bones recipe* to get you started. Anyone can take it from here to do what they need to do on their systems, and should follow best practices for setting up and securing the rest of their server.
+**Note:** This is just a _bare-bones recipe_ to get you started. Anyone can take it from here to do what they need to do on their systems, and should follow best practices for setting up and securing the rest of their server.
 
-#### Assumptions
+## Assumptions
 
 The core assumption in this guide:
 
-* You will run Metabase using the `metabase.jar` file
-* You already have `nginx` and `postgres` (or another supported database) running on your server
-* You will use environment variables to configure your Metabase instance
-* You have `sudo` access on your server
+- You will run Metabase using the `metabase.jar` file
+- You already have `nginx` and `postgres` (or another supported database) running on your server
+- You will use environment variables to configure your Metabase instance
+- You have `sudo` access on your server
 
-### Create an unprivileged user to run Metabase and give him acces to app and logs
+## Create an unprivileged user to run Metabase and give the user access to app and logs
 
 For security reasons we want to have Metabase run as an unprivileged user. We will call the user simply `metabase`. Further we will create the files we will need later for logging and configuration of Metabase, and apply the correct security settings for our unprivileged user.
 
@@ -32,11 +32,12 @@ sudo chown syslog:adm /var/log/metabase.log
 sudo touch /etc/default/metabase
 sudo chmod 640 /etc/default/metabase
 ```
-### Create a Metabase Service
+
+## Create a Metabase Service
 
 Every service needs a script that tells `systemd` how to manage it, and what capabilities it supports. Services are typically registered at `/etc/systemd/system/<servicename>`. So, a Metabase service should live at `/etc/systemd/system/metabase.service`.
 
-#### The Metabase service file
+### The Metabase service file
 
 Create the `/etc/systemd/system/metabase.service` service file and open it in your editor:
 
@@ -70,7 +71,7 @@ Restart=always
 WantedBy=multi-user.target
 ```
 
-### Create syslog conf
+## Create syslog conf
 
 Next we need to create a syslog conf to make sure systemd can handle the logs properly.
 
@@ -88,11 +89,11 @@ Restart the syslog service to load the new config.
 sudo systemctl restart rsyslog.service
 ```
 
-### Environment Variables for Metabase
+## Environment variables for Metabase
 
-Environment variables provide a good way to customize and configure your Metabase instance on your server. On Debian systems, services typically expect to have accompanying configs inside `etc/default/<service-name>`.
+[Environment variables](../configuring-metabase/environment-variables.md) provide a good way to customize and configure your Metabase instance on your server. On Debian systems, services typically expect to have accompanying configs inside `etc/default/<service-name>`.
 
-#### The Metabase config file
+### The Metabase config file
 
 Open your `/etc/default/metabase` environment config file in your editor:
 
@@ -116,15 +117,16 @@ MB_DB_HOST=<localhost>
 MB_EMOJI_IN_LOGS=<true|false>
 # any other env vars you want available to Metabase
 ```
-### Final Steps
+
+## Final steps
 
 The best part of setting up Metabase as a service on a Debian-based system is to be confident it will start up at every system boot. We only have a few more quick steps to finish registering our service and having Metabase up and running.
 
-#### Ensure your database is ready
+### Ensure your database is ready
 
 If you're running `postgres` or some other database, you need to ensure you've already followed the instructions for your database system to create a database for Metabase, as well as a user that can access that database. These values should match what you've set in your Metabase config for the `MB_DB_TYPE`, `MB_DB_DBNAME`, `MB_DB_USER`, and `MB_DB_PASS` environment variables. If you don't have your database properly configured, Metabase won't be able to start.
 
-#### Ensure `nginx` is setup to proxy requests to Metabase
+### Ensure `nginx` is setup to proxy requests to Metabase
 
 Getting into too much detail about configuring `nginx` is well outside the scope of this guide, but here's a quick `nginx.conf` file that will get you up and running.
 
@@ -142,7 +144,8 @@ server {
   }
 }
 ```
-#### Register your Metabase service
+
+### Register your Metabase service
 
 Now, it's time to register our Metabase service with `systemd` so it will start up at system boot. We'll also ensure our log file is created and owned by the unprivileged user our service runs the `metabase.jar` as.
 
@@ -150,15 +153,15 @@ Now, it's time to register our Metabase service with `systemd` so it will start
 sudo systemctl daemon-reload
 sudo systemctl start metabase.service
 sudo systemctl status metabase.service
-````
+```
 
 Once we are ok here, enable the service to startup during boot.
 
 ```
 sudo systemctl enable metabase.service
-````
+```
 
-#### That's it!
+## Start, stop, or restart Metabase
 
 Now, whenever you need to start, stop, or restart Metabase, all you need to do is:
 
-- 
GitLab