Docker guide

← Documentation index · Quick install · Troubleshooting

LoRA Dataset Studio provides two beginner Windows launchers:

Each launcher remembers its own stack and data. Do not run two LDS containers against the same data folder: two Flask processes must not share one SQLite database and config.json.

1. On GitHub, choose Code → Download ZIP and extract the complete folder.
2. Start Docker Desktop and wait until it reports that Docker is running.
3. Double-click start-docker.bat.
4. On first launch, choose either the ComfyUI root containing main.py and models/, or the portable parent containing ComfyUI\main.py.
5. Start ComfyUI with your usual launcher. LDS opens automatically on the first free Studio port.

The selected folder is validated, mounted read/write at /external-comfyui, and remembered in a generated local override. If it moves, run configure-docker.bat. From Docker, LDS connects to the host API at http://host.docker.internal:8188.

On Docker Desktop for Windows a ComfyUI listening only on 127.0.0.1 is reachable as-is — Docker Desktop proxies that name from the host side, so the default portable launcher needs no change and no firewall hole. This was measured, not assumed. On a Linux host, host.docker.internal resolves to the host gateway and a loopback-only ComfyUI is genuinely unreachable: start it with --listen 0.0.0.0 and restrict port 8188 to Docker or your private network. If Studio reports it cannot reach ComfyUI, the launcher prints that same guidance.

1. On GitHub, choose Code → Download ZIP and extract the complete folder.
2. Start Docker Desktop and wait for it to report that Docker is running.
3. Double-click start-docker-gpu.bat.
4. Keep the first build/start open. The launcher prints both actual addresses and opens Studio as soon as Studio responds. Its batch window keeps working until ComfyUI becomes healthy; no second ComfyUI window needs to appear.

The launcher always forces the four repo-local folders ./run, ./basedir, ./data-docker-gpu and ./bank-images for ComfyUI, models, app data and bank sources. It does this even when .env contains custom LDS_COMFY_RUN, LDS_COMFY_BASEDIR, LDS_DATA or LDS_BANK_SOURCES values, specifically so a double-click can never touch an existing ComfyUI. To relocate or reuse storage, do not use the launcher; use the advanced CLI, which respects those .env values.

The double-click launcher picks both host ports itself, by testing them on the host: Studio between 5050 and 5149, ComfyUI between 8188 and 8287, taking the first that is genuinely free. The usual addresses therefore remain http://127.0.0.1:5050/ and http://127.0.0.1:8188/, but an existing LDS, ComfyUI or unrelated service can keep either default port: the launcher leaves it running and selects another one automatically. It prints both final addresses and opens the mapped Studio URL.

The launcher probes rather than handing Docker a port range, because Docker's allocator only tracks the ports it assigned itself: given a range it will still choose a port another program already holds and then fail to start with ports are not available. Each resolved port is published as a single fixed port, so docker stop followed by docker start keeps the address you bookmarked instead of moving it.

Re-running the launcher from the same checkout while its container is already running reuses the existing Docker mappings and opens Studio without recreating the container. If the fixed Compose container identity belongs to a different checkout, the launcher stops with a clear collision error rather than modifying or replacing it. It never stops an existing service and does not write the selected ports to .env; the allocation applies only to that launcher run.

On Windows, the double-click launcher also sets LDS_UID=0 and LDS_GID=0 for its Docker process only because Docker Desktop presents these bind mounts as owner 0:0; it does not edit .env. Advanced CLI and Linux launches keep the UID/GID values from .env, which should match the host folders as described under Linux, Unraid and permissions.

Windows needs Docker Desktop's WSL2 backend, GPU support and a compatible NVIDIA driver. Linux hosts need the NVIDIA Container Toolkit. For CUDA 12.x compatibility the minimum driver is 525.60.13 on Linux or 528.33 on Windows/WSL; the default CUDA 12.9 image is best paired with 575.51.03+ on Linux or 576.02+ on Windows. The optional CUDA 13 build requires an R580-series driver.

From the repository root:

cp .env.example .env
mkdir -p run basedir data-docker-gpu bank-images
docker compose -f docker-compose.gpu.yml up --build

Create bind-mount source folders before the first CLI start. Docker may otherwise create them as root while the container runs as your configured user, leaving the app unable to write.

When healthy, the advanced CLI defaults to:

• Studio: http://127.0.0.1:5050/
• ComfyUI: http://127.0.0.1:8188/

Advanced CLI mode does not scan the launcher ranges. Set LDS_HOST_PORT and LDS_COMFY_HOST_PORT in .env when those defaults are unavailable; Compose continues to respect those explicit values.

Compose binds published ports to 127.0.0.1 by default. LAN access is an explicit opt-in: set LDS_BIND_ADDRESS=0.0.0.0, enable the LDS access token, and restrict the ports with Windows Firewall or another trusted-network boundary. ComfyUI's own port has no LDS token gate, so never expose it publicly.

In advanced CLI mode only, the GPU stack has four primary host paths, all relocatable in .env. The double-click launcher overrides these four variables with the repo-local defaults on every run:

Back up LDS_DATA for the app state and LDS_COMFY_BASEDIR for model/input/output assets. The large, reproducible ComfyUI environment and cache under LDS_COMFY_RUN can also be backed up when avoiding a rebuild matters.

This is an advanced CLI-only setup. Set absolute host paths in the Docker block of .env, then start with docker compose directly rather than start-docker-gpu.bat:

LDS_COMFY_RUN=D:/LDS-Docker/run
LDS_COMFY_BASEDIR=D:/LDS-Docker/basedir
LDS_DATA=D:/LDS-Docker/data
LDS_BANK_SOURCES=E:/ImageDumps

On Linux, use native absolute paths. Docker Desktop must have permission to share Windows drives used by a bind mount.

Use start-docker.bat to opt in to an existing ComfyUI. Select the ComfyUI root containing main.py and models/, or its portable parent; never select models/ itself. The launcher validates the path before generating its local Compose override.

Use start-docker-gpu.bat when you do not want Docker to touch that existing installation. Its run/ and basedir/ folders stay isolated beside the checkout.

For a bank, enter the container path in the UI: /images or a subfolder such as /images/telegram-export. The host path stored in LDS_BANK_SOURCES does not exist inside the container. Mount the source read-only if originals must be untouchable; Delete rejected is the bank action that otherwise removes source files.

Set the container identity to the owner of the mounted folders:

LDS_UID=1000
LDS_GID=1000

Use id -u and id -g on Linux. Unraid commonly uses 99/100. A mismatch usually appears as a writable-folder failure in the container log.

LDS_FORCE_CHOWN=true is a last-resort adoption switch. It recursively changes ownership of the LDS data mount only; it does not adopt the ComfyUI runtime, model tree or Image Bank sources. Do not enable it casually on a large or shared directory.

If an Unraid restart leaves the container with no network, inspect its attached networks and recreate the stack:

docker inspect -f '{{json .NetworkSettings.Networks}}' lora-dataset-studio-gpu
docker compose -f docker-compose.gpu.yml down
docker compose -f docker-compose.gpu.yml up -d --force-recreate

An empty {} network result means the old Compose network disappeared. On Unraid, Settings → Docker → Preserve user defined networks = Yes prevents the array stop/start cycle from removing it.

The upstream GPU image checks/updates its installer and ComfyUI at startup, so working DNS is required on every start rather than only during the first build. The Compose file uses:

LDS_DNS=1.1.1.1

Change that to a reachable router, corporate resolver or Pi-hole when Cloudflare DNS is inappropriate. A log sequence such as Could not resolve host: astral.sh followed by uv not found after installation is a DNS/network failure, not a GPU or LDS failure.

There is currently no offline startup mode for this image. A boot race can recover automatically under restart: unless-stopped; a container detached from every network cannot.

The stack is unlimited unless these optional variables are set:

LDS_MEM_LIMIT=32g
LDS_MEMSWAP_LIMIT=40g
LDS_CPUS=12

LDS_MEMSWAP_LIMIT is memory and swap combined, so it must be greater than or equal to LDS_MEM_LIMIT. Leave generous headroom during first boot: torch and the ComfyUI dependency tree are installed there, and an overly tight cap looks like a killed installer rather than a slow one.

GPU allocation is controlled by Docker/NVIDIA rather than these CPU/RAM variables. ComfyUI and LDS scoring share the selected GPU inside this container, so avoid overlapping large passes when VRAM is tight.

Both Docker images include the public Store configuration and trust root. No ./store bind mount is needed. If an older V2 image reports The store has not been connected to a trusted catalog yet, update the source and rebuild the image.

Docker forwards browser connections across its bridge, so even a browser opened on the host's localhost address can require plugin administrator authorization:

1. Generate a random secret of at least 32 characters, for example with python -c "import secrets; print(secrets.token_urlsafe(32))".
2. Set LDS_PLUGIN_ADMIN_TOKEN=<your generated secret> in the host .env file mounted at /app/.env, then restart LDS when no work is running. If you pass it as container environment instead, recreate the container to apply it.
3. In Plugins, choose Unlock installation and enter the same secret.

The installed packages, their data and the verified catalog cache live under /data, so keep that volume when rebuilding or recreating the container. In Plugins → Store, tick the plugins you want and choose Review selected. Confirm the shared plan to prepare the whole selection, then apply it in one restart. Apply or cancel this pending plan before preparing another selection. In the GPU image, Apply changes and restart restarts only LDS through its supervisor, after checking for active work. In the API-only/external-ComfyUI image, restart the Studio service with your usual Compose files (for the default stack: docker compose restart studio).

In the GPU image, an in-app restart exits back to the container supervisor, which respawns LDS on the fixed container bind. It does not create a second loopback-only process. The API-only image requires a container restart to apply plugin changes.

The in-app source updater cannot replace the immutable /app files in an image. For a GitHub ZIP installation, double-click update-docker.bat: it downloads the latest stable Release, keeps the previously selected launcher, rebuilds the image, and preserves .env, app data, ComfyUI folders, bank sources, ollama-data/ and the generated external-ComfyUI override. Pass v2 to follow the maintained branch; main remains an alias for v2 for older commands. Patreon members (LDS Member) run update-docker.bat patreon to install the latest Patreon release, as the Updates card shows; see Patreon access. This command is for installations from the Windows ZIP only, and unlike the in-app updates it cannot wait for running work: stop generations, training and other jobs first, because the rebuild restarts LDS. No channel installs an older version than the installed one. After a Patreon install, update-docker.bat and its v2/main channels refuse public releases, which would remove the Patreon changes; add force (for example update-docker.bat stable force) to install the public release anyway.

The code swap is transactional. The updater keeps the previous code aside, then calls the launcher with --update-rebuild, which returns only once Docker reports the Studio container healthy. On that confirmation the update is committed and the backup is removed; on any failure the previous code is put back and its launcher is restarted, so a failed update leaves you on the version you already had.

A git checkout is never reset or merged by the updater. Run git pull --ff-only yourself, then rerun the same Docker launcher with --update-rebuild. Rebuilding replaces containers and code, not bind-mounted user data.

Rebuilding the image does not delete bind-mounted data. docker compose down removes containers and the Compose network, not the host folders listed above.

• Budget roughly 20 GB before model downloads: the CUDA image and its persistent ComfyUI environment are both large. Model stacks add substantially more.
• Building the LDS-side torch dependencies from the CPU wheel index can save several gigabytes, but Image Bank Score then runs on CPU; ComfyUI still owns the GPU.
• Ollama is optional and selected inside LDS Setup. Choose no Ollama, an existing host Ollama, or the isolated official Docker companion. No model is pulled automatically; start the explicit model download in LDS to see progress or cancel it. The companion publishes no host port and keeps models in ./ollama-data.
• Local training is not included. Connect ai-toolkit on the host where its filesystem is visible, or use cloud training. ComfyUI inside this image is for generation, Studio, Canvas generation and deployment.
• Watermark inpainting is currently listed as unsupported in this Docker lane; model-free crop remains available. Track this and other boundaries in Known limitations.
• Immediately after a container recreate, an extra install can briefly fail while the launcher adopts the large internal virtual environment. The image already ships the ML extras; wait for the adoption message in the log before repairing an optional package.
• Mounting your own /userscripts_dir shadows the LDS launcher shipped there. If only ComfyUI starts, remove that override.
• Both published ports are unauthenticated at the container layer. LDS can gate its own remote UI; ComfyUI needs its own firewall, VPN or authenticated proxy if it is exposed.

The smaller start-docker.bat stack runs LDS in Docker and connects to the ComfyUI you already maintain on the host. It does not install or launch a second ComfyUI. Its first-run folder picker creates the strict local mount override required for model discovery and shared input/output files.

The image installs backend/requirements.txt only. Optional scraping and ML extras can be installed from LDS; local ai-toolkit training remains a separate host/cloud tool.

docker compose -f docker-compose.gpu.yml ps
docker compose -f docker-compose.gpu.yml logs --tail=200
nvidia-smi

Use the app's Guide → Getting help report for LDS capability state. For model/path failures, continue with Troubleshooting; for every Docker variable and default, read the Docker block in .env.example.