Skip to main content
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 — Your custom configuration
  3. Environment variables — 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: 
{
  "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:
./stop.sh && ./start.sh

​
Feature Flags

The following feature flags control which capabilities are available in your deployment.
SettingTypeDefaultDescription
ADD_MEDIA_ENABLEDbooleantrueAllow adding new media to existing datasets without a full reindex.
DATASET_INGESTION_ONPREM_UI_ENABLEDbooleanfalseEnable dataset creation from the web interface. When disabled, datasets can only be created via the CLI profiler tool.
DATASET_CREATION_V2booleanfalseEnable the updated dataset creation workflow with a step-by-step wizard.
ENRICHMENT_PREVIEW_SERVICE_ENABLEDbooleanfalseAllow previewing enrichment model results on a sample before running on the full dataset.
ENRICHMENT_INLINE_FLOW_ENABLEDbooleanfalseRun enrichment models within the same pipeline process instead of requiring a separate step.
PREPROCESS_ENABLEDbooleanfalseEnable preprocessing (image resizing, frame extraction, cleaning) before indexing.
ENRICHMENT_DKMC2_ENABLEDbooleanfalseEnable 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.
SettingTypeDefaultDescription
S3_VL_INGESTION_SERVICE_PROFILEstring""AWS credentials profile name for S3-based ingestion. Leave empty to use the default credential chain.
FILE_FILTER_TREE_INCLUDE_FILESbooleantrueShow individual files in the file filter tree. Disabling this improves performance for datasets with many files.
SERVE_ORIGINAL_VIDEObooleanfalseServe 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_HEIGHTinteger0Target 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.
SettingTypeDefaultDescription
DISABLE_AUTHbooleanfalseDisable authentication. Typically set to true for single-user deployments.
MAX_NUM_OF_IMAGESinteger100000000Maximum number of images allowed per dataset.
CLEAN_THRESHOLDfloat-1Similarity threshold for near-duplicate detection. Images above this threshold are flagged as near-duplicates. -1 uses the automatic threshold.
LOG_LEVELstringINFOControls 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_HEICbooleanfalseCorrect 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: 
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.
VariableDescriptionExample Values
HARDWAREHardware profile for the deployment.cpu, gpu
VL_VERSIONVisual Layer application version.latest, 2.33.3-rc7
VL_MODEL_VERSIONVersion of bundled ML models.7.0
HOST_OSHost operating system.Linux, Darwin
MODEL_PACK_FROM_IMAGELoad 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: 
LOG_LEVEL=10
SERVE_ORIGINAL_VIDEO=true
After modifying .env, restart the services for changes to take effect:
./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. 
export LOG_LEVEL='10'
export SERVE_ORIGINAL_VIDEO=true

Installation

Install and start Visual Layer on your infrastructure.

S3 Configuration

Configure S3 storage for self-hosted deployments.

System Requirements

Hardware and software prerequisites for self-hosted deployments.

Useful Scripts

Maintenance and administration scripts for self-hosted environments.