From 93c35efe67ed6d2487f533f284a012ee39a15bfa Mon Sep 17 00:00:00 2001
From: Stavros Kois <47820033+stavros-k@users.noreply.github.com>
Date: Mon, 19 Jun 2023 23:55:12 +0300
Subject: [PATCH] [docs]: Document environment variables (#2814)

* draft env vars

* remove mapbox refs, fixes #2535

* formatting and add some notes

* add examples for redis and typesense url

* [skipci] add note for redis socket

* do some formatting

* update md

* fix url

* fix variable

* add web for NODE_ENV

* fix variable name

* Apply suggestions from code review

Co-authored-by: Jason Rasmussen <jrasm91@gmail.com>

* address review feedback

* Update docker/example.env

Co-authored-by: Jason Rasmussen <jrasm91@gmail.com>

* add section for docker compose envs

---------

Co-authored-by: Jason Rasmussen <jrasm91@gmail.com>
---
 docker/.env.test                           |   5 -
 docker/example.env                         |  12 +-
 docs/docs/install/environment-variables.md | 186 +++++++++++++++++++++
 3 files changed, 192 insertions(+), 11 deletions(-)
 create mode 100644 docs/docs/install/environment-variables.md

diff --git a/docker/.env.test b/docker/.env.test
index 82311b7d58..68c179b42d 100644
--- a/docker/.env.test
+++ b/docker/.env.test
@@ -10,12 +10,7 @@ REDIS_HOSTNAME=immich-redis-test
 # Upload File Config
 UPLOAD_LOCATION=./upload
 
-# MAPBOX
-## ENABLE_MAPBOX is either true of false -> if true, you have to provide MAPBOX_KEY
-ENABLE_MAPBOX=false
-
 # WEB
-MAPBOX_KEY=
 VITE_SERVER_ENDPOINT=http://localhost:2283/api
 
 TYPESENSE_ENABLED=false
diff --git a/docker/example.env b/docker/example.env
index eef325b1f8..5697a97ce0 100644
--- a/docker/example.env
+++ b/docker/example.env
@@ -52,11 +52,11 @@ TYPESENSE_API_KEY=some-random-text
 # TYPESENSE_URL uses base64 encoding for the nodes json.
 # Example JSON that was used:
 # [
-#      { 'host': 'typesense-1.example.net', 'port': '443', 'protocol': 'https' },
-#      { 'host': 'typesense-2.example.net', 'port': '443', 'protocol': 'https' },
-#      { 'host': 'typesense-3.example.net', 'port': '443', 'protocol': 'https' },
-#  ]
-# TYPESENSE_URL=ha://WwogICAgeyAnaG9zdCc6ICd0eXBlc2Vuc2UtMS5leGFtcGxlLm5ldCcsICdwb3J0JzogJzQ0MycsICdwcm90b2NvbCc6ICdodHRwcycgfSwKICAgIHsgJ2hvc3QnOiAndHlwZXNlbnNlLTIuZXhhbXBsZS5uZXQnLCAncG9ydCc6ICc0NDMnLCAncHJvdG9jb2wnOiAnaHR0cHMnIH0sCiAgICB7ICdob3N0JzogJ3R5cGVzZW5zZS0zLmV4YW1wbGUubmV0JywgJ3BvcnQnOiAnNDQzJywgJ3Byb3RvY29sJzogJ2h0dHBzJyB9LApd
+#      { "host": "typesense-1.example.net", "port": "443", "protocol": "https" },
+#      { "host": "typesense-2.example.net", "port": "443", "protocol": "https" },
+#      { "host": "typesense-3.example.net", "port": "443", "protocol": "https" },
+# ]
+# TYPESENSE_URL=ha://WwogIHsgImhvc3QiOiAidHlwZXNlbnNlLTEuZXhhbXBsZS5uZXQiLCAicG9ydCI6ICI0NDMiLCAicHJvdG9jb2wiOiAiaHR0cHMiIH0sCiAgeyAiaG9zdCI6ICJ0eXBlc2Vuc2UtMi5leGFtcGxlLm5ldCIsICJwb3J0IjogIjQ0MyIsICJwcm90b2NvbCI6ICJodHRwcyIgfSwKICB7ICJob3N0IjogInR5cGVzZW5zZS0zLmV4YW1wbGUubmV0IiwgInBvcnQiOiAiNDQzIiwgInByb3RvY29sIjogImh0dHBzIiB9Cl0=
 
 ###################################################################################
 # Reverse Geocoding
@@ -109,7 +109,7 @@ IMMICH_MACHINE_LEARNING_URL=http://immich-machine-learning:3003
 ###################################################################################
 # Immich Version - Optional
 #
-# This allows all immich docker images to be pinned to a specific version. By default, 
+# This allows all immich docker images to be pinned to a specific version. By default,
 # the version is "release" but could be a specific version, like "v1.59.0".
 ###################################################################################
 
diff --git a/docs/docs/install/environment-variables.md b/docs/docs/install/environment-variables.md
new file mode 100644
index 0000000000..a8c07980b7
--- /dev/null
+++ b/docs/docs/install/environment-variables.md
@@ -0,0 +1,186 @@
+# Environment Variables
+
+## Docker Compose
+
+| Variable          | Description           |  Default  | Services                                                       |
+| :---------------- | :-------------------- | :-------: | :------------------------------------------------------------- |
+| `IMMICH_VERSION`  | Image tags            | `release` | server, microservices, machine learning, web, proxy, typesense |
+| `UPLOAD_LOCATION` | Host Path for uploads |           | server, microservices                                          |
+
+:::tip
+
+These environment variables are used by the `docker-compose.yml` file and do **NOT** affect the containers directly.
+
+:::
+
+## General
+
+| Variable                | Description                                  |   Default    | Services                                     |
+| :---------------------- | :------------------------------------------- | :----------: | :------------------------------------------- |
+| `TZ`                    | Timezone                                     |              | microservices                                |
+| `NODE_ENV`              | Environment (production, development)        | `production` | server, microservices, machine learning, web |
+| `LOG_LEVEL`             | Log Level (verbose, debug, log, warn, error) |    `log`     | server, microservices                        |
+| `IMMICH_MEDIA_LOCATION` | Media Location                               |  `./upload`  | server, microservices                        |
+
+:::tip
+
+`TZ` is only used by the `exiftool` as a fallback in case the timezone cannot be determined from the image metadata.
+
+`exiftool` is only present in the microservices container.
+
+:::
+
+## Geocoding
+
+| Variable                           | Description                         |           Default            | Services      |
+| :--------------------------------- | :---------------------------------- | :--------------------------: | :------------ |
+| `DISABLE_REVERSE_GEOCODING`        | Disable Reverse Geocoding Precision |           `false`            | microservices |
+| `REVERSE_GEOCODING_PRECISION`      | Reverse Geocoding Precision         |             `3`              | microservices |
+| `PUBLIC_LOGIN_PAGE_MESSAGE`        | Public Login Page Message           |                              | web           |
+| `REVERSE_GEOCODING_DUMP_DIRECTORY` | Reverse Geocoding Dump Directory    | `./.reverse-geocoding-dump/` | microservices |
+
+## Ports
+
+| Variable                | Description           | Default | Services         |
+| :---------------------- | :-------------------- | :-----: | :--------------- |
+| `PORT`                  | Web Port              | `3000`  | web              |
+| `SERVER_PORT`           | Server Port           | `3001`  | server           |
+| `MICROSERVICES_PORT`    | Microservices Port    | `3002`  | microservices    |
+| `MACHINE_LEARNING_PORT` | Machine Learning Port | `3003`  | machine learning |
+
+## URLs
+
+| Variable                      | Description                                              |                Default                | Services              |
+| :---------------------------- | :------------------------------------------------------- | :-----------------------------------: | :-------------------- |
+| `IMMICH_WEB_URL`              | Immich Web URL                                           |       `http://immich-web:3000`        | proxy                 |
+| `IMMICH_SERVER_URL`           | Immich Server URL                                        |      `http://immich-server:3001`      | web, proxy            |
+| `IMMICH_MACHINE_LEARNING_URL` | Immich Machine Learning URL, set `"false"` to disable ML | `http://immich-machine-learning:3003` | server, microservices |
+| `PUBLIC_IMMICH_SERVER_URL`    | Public Immich URL                                        |      `http://immich-server:3001`      | web                   |
+| `IMMICH_API_URL_EXTERNAL`     | Immich API URL External                                  |                `/api`                 | web                   |
+
+:::info
+
+The above paths are modifying the internal paths of the containers.
+
+:::
+
+## Database
+
+| Variable      | Description       |   Default   | Services              |
+| :------------ | :---------------- | :---------: | :-------------------- |
+| `DB_URL`      | Database URL      |             | server, microservices |
+| `DB_HOSTNAME` | Database Host     | `localhost` | server, microservices |
+| `DB_PORT`     | Database Port     |   `5432`    | server, microservices |
+| `DB_USERNAME` | Database User     | `postgres`  | server, microservices |
+| `DB_PASSWORD` | Database Password | `postgres`  | server, microservices |
+| `DB_DATABASE` | Database Name     |  `immich`   | server, microservices |
+
+:::info
+
+When `DB_URL` is defined, the other database (`DB_*`) variables are ignored.
+
+:::
+
+## Redis
+
+| Variable         | Description    |    Default     | Services              |
+| :--------------- | :------------- | :------------: | :-------------------- |
+| `REDIS_URL`      | Redis URL      |                | server, microservices |
+| `REDIS_HOSTNAME` | Redis Host     | `immich_redis` | server, microservices |
+| `REDIS_PORT`     | Redis Port     |     `6379`     | server, microservices |
+| `REDIS_DBINDEX`  | Redis DB Index |      `0`       | server, microservices |
+| `REDIS_USERNAME` | Redis Username |                | server, microservices |
+| `REDIS_PASSWORD` | Redis Password |                | server, microservices |
+| `REDIS_SOCKET`   | Redis Socket   |                | server, microservices |
+
+:::info
+
+`REDIS_URL` must start with `ioredis://` and then include a `base64` encoded JSON string for the configuration.
+More info can be found in the upstream [ioredis](https://ioredis.readthedocs.io/en/latest/API/) documentation.
+
+- When `REDIS_URL` is defined, the other redis (`REDIS_*`) variables are ignored.
+- When `REDIS_SOCKET` is defined, the other redis (`REDIS_*`) variables are ignored.
+
+:::
+
+Redis (Sentinel) URL example JSON before encoding:
+
+```json
+{
+  "sentinels": [
+    {
+      "host": "redis-sentinel-node-0",
+      "port": 26379
+    },
+    {
+      "host": "redis-sentinel-node-1",
+      "port": 26379
+    },
+    {
+      "host": "redis-sentinel-node-2",
+      "port": 26379
+    }
+  ],
+  "name": "redis-sentinel"
+}
+```
+
+## Typesense
+
+| Variable             | Description              |   Default   | Services                         |
+| :------------------- | :----------------------- | :---------: | :------------------------------- |
+| `TYPESENSE_ENABLED`  | Enable Typesense         |             | server, microservices            |
+| `TYPESENSE_URL`      | Typesense URL            |             | server, microservices            |
+| `TYPESENSE_HOST`     | Typesense Host           | `typesense` | server, microservices            |
+| `TYPESENSE_PORT`     | Typesense Port           |   `8108`    | server, microservices            |
+| `TYPESENSE_PROTOCOL` | Typesense Protocol       |   `http`    | server, microservices            |
+| `TYPESENSE_API_KEY`  | Typesense API Key        |             | server, microservices, typesense |
+| `TYPESENSE_DATA_DIR` | Typesense Data Directory |   `/data`   | typesense                        |
+
+:::info
+
+`TYPESENSE_URL` must start with `ha://` and then include a `base64` encoded JSON string for the configuration.
+
+`TYPESENSE_ENABLED`: Anything other than `false`, behaves as `true`.
+Even undefined is treated as `true`.
+
+- When `TYPESENSE_URL` is defined, the other typesense (`TYPESENSE_*`) variables are ignored.
+
+:::
+
+Typesense URL example JSON before encoding:
+
+```json
+[
+  {
+    "host": "typesense-1.example.net",
+    "port": "443",
+    "protocol": "https"
+  },
+  {
+    "host": "typesense-2.example.net",
+    "port": "443",
+    "protocol": "https"
+  },
+  {
+    "host": "typesense-3.example.net",
+    "port": "443",
+    "protocol": "https"
+  }
+]
+```
+
+## Machine Learning
+
+| Variable                                    | Description                    |        Default        | Services         |
+| :------------------------------------------ | :----------------------------- | :-------------------: | :--------------- |
+| `MACHINE_LEARNING_MIN_FACE_SCORE`           | Minimum Face Score             |         `0.7`         | machine learning |
+| `MACHINE_LEARNING_MODEL_TTL`                | Model TTL                      |         `300`         | machine learning |
+| `MACHINE_LEARNING_EAGER_STARTUP`            | Eager Startup                  |        `true`         | machine learning |
+| `MACHINE_LEARNING_MIN_TAG_SCORE`            | Minimum Tag Score              |         `0.9`         | machine learning |
+| `MACHINE_LEARNING_FACIAL_RECOGNITION_MODEL` | Facial Recognition Model       |      `buffalo_l`      | machine learning |
+| `MACHINE_LEARNING_CLIP_TEXT_MODEL`          | Clip Text Model                |    `clip-ViT-B-32`    | machine learning |
+| `MACHINE_LEARNING_CLIP_IMAGE_MODEL`         | Clip Image Model               |    `clip-ViT-B-32`    | machine learning |
+| `MACHINE_LEARNING_CLASSIFICATION_MODEL`     | Classification Model           | `microsoft/resnet-50` | machine learning |
+| `MACHINE_LEARNING_CACHE_FOLDER`             | ML Cache Location              |       `/cache`        | machine learning |
+| `TRANSFORMERS_CACHE`                        | ML Transformers Cache Location |       `/cache`        | machine learning |