> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visual-layer.com/llms.txt
> Use this file to discover all available pages before exploring further.
# General Settings
> Customize Visual Layer behavior through config.json, environment files, and environment variable overrides for self-hosted deployments.
**Visual Layer** uses two configuration mechanisms for self-hosted deployments: a JSON configuration file for application settings and feature flags, and an environment file for Docker Compose variables. Environment variables can override either source.
## Configuration Hierarchy
Settings are applied in the following order, where later sources override earlier ones:
1. **`defaults.json`** — Built-in defaults (do not edit)
2. **[`config.json`](#configuration-file-configjson)** — Your custom configuration
3. **[Environment variables](#environment-file-env)** — Override any JSON setting
## Configuration File (`config.json`)
The `config.json` file is located at `.vl/config.json` inside your **Visual Layer** installation directory. This file controls application behavior, feature flags, and pipeline settings. Include only the settings you want to change — any setting not present in `config.json` uses its default value from `defaults.json`.
To customize your deployment, create or edit `.vl/config.json`:
```json theme={"theme":"monokai"}
{
"ADD_MEDIA_ENABLED": true,
"DATASET_INGESTION_ONPREM_UI_ENABLED": true,
"DATASET_CREATION_V2": false,
"S3_VL_INGESTION_SERVICE_PROFILE": "",
"ENRICHMENT_PREVIEW_SERVICE_ENABLED": true,
"ENRICHMENT_INLINE_FLOW_ENABLED": true,
"PREPROCESS_ENABLED": true,
"FILE_FILTER_TREE_INCLUDE_FILES": true,
"SERVE_ORIGINAL_VIDEO": true,
"ENRICHMENT_DKMC2_ENABLED": true,
"FRAME_EXTRACTION_RESIZE_HEIGHT": 720
}
```
After modifying `config.json`, restart **Visual Layer** services for changes to take effect:
```bash theme={"theme":"monokai"}
./stop.sh && ./start.sh
```
### Feature Flags
The following feature flags control which capabilities are available in your deployment.
| Setting | Type | Default | Description |
| ------------------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `ADD_MEDIA_ENABLED` | boolean | `true` | Allow adding new media to existing datasets without a full reindex. |
| `DATASET_INGESTION_ONPREM_UI_ENABLED` | boolean | `false` | Enable dataset creation from the web interface. When disabled, datasets can only be created via the CLI profiler tool. |
| `DATASET_CREATION_V2` | boolean | `false` | Enable the updated dataset creation workflow with a step-by-step wizard. |
| `ENRICHMENT_PREVIEW_SERVICE_ENABLED` | boolean | `false` | Allow previewing enrichment model results on a sample before running on the full dataset. |
| `ENRICHMENT_INLINE_FLOW_ENABLED` | boolean | `false` | Run enrichment models within the same pipeline process instead of requiring a separate step. |
| `PREPROCESS_ENABLED` | boolean | `false` | Enable preprocessing (image resizing, frame extraction, cleaning) before indexing. |
| `ENRICHMENT_DKMC2_ENABLED` | boolean | `false` | Enable DKMC2 (Deep K-Means Clustering v2), which generates multiple embedding vectors per image for fine-grained instance retrieval. |
### Storage and Media Settings
These settings control how media files are stored, processed, and displayed.
| Setting | Type | Default | Description |
| --------------------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `S3_VL_INGESTION_SERVICE_PROFILE` | string | `""` | AWS credentials profile name for S3-based ingestion. Leave empty to use the default credential chain. |
| `FILE_FILTER_TREE_INCLUDE_FILES` | boolean | `true` | Show individual files in the file filter tree. Disabling this improves performance for datasets with many files. |
| `SERVE_ORIGINAL_VIDEO` | boolean | `false` | Serve videos from their original location instead of copying to the CDN directory. Reduces disk usage but requires original files to remain accessible. |
| `FRAME_EXTRACTION_RESIZE_HEIGHT` | integer | `0` | Target height in pixels for video frame extraction. `0` preserves original resolution. Common values: `576`, `720`. |
### General Settings
Additional settings for authentication, dataset limits, and data quality.
| Setting | Type | Default | Description |
| --------------------------------- | ------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DISABLE_AUTH` | boolean | `false` | Disable authentication. Typically set to `true` for single-user deployments. |
| `MAX_NUM_OF_IMAGES` | integer | `100000000` | Maximum number of images allowed per dataset. |
| `CLEAN_THRESHOLD` | float | `-1` | Similarity threshold for near-duplicate detection. Images above this threshold are flagged as near-duplicates. `-1` uses the automatic threshold. |
| `LOG_LEVEL` | string | `INFO` | Controls logging verbosity. Accepted values: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. At `DEBUG`, additional internal processing messages are logged including detailed diagnostics. |
| `SWAP_RGB_CHANNELS_FOR_TIFF_HEIC` | boolean | `false` | Correct color rendering for TIFF and HEIC images where red and blue channels appear reversed. |
## Environment File (`.env`)
The `.env` file is located at the root of the **Visual Layer** installation directory. Docker Compose reads this file when starting services. It controls hardware profile, image versions, and deployment options.
A typical `.env` file:
```bash theme={"theme":"monokai"}
REPO=visuallayer
IMAGE_PREFIX=onprem-
VL_VERSION=latest
VL_MODEL_VERSION=7.0
PG_VERSION=16
VL_PG_VERSION=latest
HARDWARE=cpu
HOST_OS=Linux
MODEL_PACK_FROM_IMAGE=false
```
### Key `.env` Variables
The following variables control the deployment environment.
| Variable | Description | Example Values |
| ----------------------- | ----------------------------------------------------- | ---------------------- |
| `HARDWARE` | Hardware profile for the deployment. | `cpu`, `gpu` |
| `VL_VERSION` | **Visual Layer** application version. | `latest`, `2.33.3-rc7` |
| `VL_MODEL_VERSION` | Version of bundled ML models. | `7.0` |
| `HOST_OS` | Host operating system. | `Linux`, `Darwin` |
| `MODEL_PACK_FROM_IMAGE` | Load models from Docker image instead of downloading. | `true`, `false` |
You can also add `config.json` settings as environment variables in the `.env` file. Environment variables take precedence over JSON configuration:
```bash theme={"theme":"monokai"}
LOG_LEVEL=10
SERVE_ORIGINAL_VIDEO=true
```
After modifying `.env`, restart the services for changes to take effect:
```bash theme={"theme":"monokai"}
./stop.sh && ./start.sh
```
### Environment Variable Overrides
Any `config.json` setting can also be set as an environment variable exported in the shell before starting **Visual Layer**. Environment variables always take the highest precedence.
```bash theme={"theme":"monokai"}
export LOG_LEVEL='10'
export SERVE_ORIGINAL_VIDEO=true
```
## Related Resources
Install and start Visual Layer on your infrastructure.
Configure S3 storage for self-hosted deployments.
Hardware and software prerequisites for self-hosted deployments.
Maintenance and administration scripts for self-hosted environments.