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 * address review feedback * Update docker/example.env Co-authored-by: Jason Rasmussen * add section for docker compose envs --------- Co-authored-by: Jason Rasmussen --- 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 |