Keep Zotonic in Ubuntu's Linux filesystem and use Windows launchers for everyday\nwork. This avoids the slow Windows bind mounts and missed file-change events\nthat can affect a checkout under Install Docker Desktop for Windows<\/a>.\nUse its WSL 2 backend<\/strong> for this workflow. Docker VMM and Windows containers do\nnot provide the Ubuntu filesystem integration this setup needs.<\/p>\n If Ubuntu is not installed, open PowerShell as Administrator<\/strong>:<\/p>\n Restart Windows if requested. Open Ubuntu from the Windows Start menu<\/strong> and\ncreate a normal Linux username and password. Do not use root for development.\nIn that Ubuntu shell<\/strong>, install Git:<\/p>\n In PowerShell<\/strong>, check:<\/p>\n Ubuntu must show version Start Docker Desktop. Under Settings → Resources → WSL Integration<\/strong>, enable\nthat Ubuntu distribution and apply the settings. Enable Use WSL 2 based\nengine<\/strong> under General if shown. Switch to Linux containers<\/strong> is a conditional\nmenu item, not an option every installation shows.<\/p>\n See Microsoft's WSL instructions<\/a>\nand Docker's WSL setup<\/a>.<\/p>\n Obtain a current Zotonic checkout or extract the repository archive on Windows.\nThis Windows copy is only used to run setup; it is not mounted into the container.\nWindows Git is not required when using an extracted archive.<\/p>\n In Explorer, double-click setup-wsl.cmd<\/strong>. No administrator shell is needed.\nIt asks for:<\/p>\n Setup clones Zotonic with Linux Git if that directory does not exist. It can\nreuse an existing Zotonic Git checkout without pulling, resetting, or replacing\nits files. It rejects Windows-mounted paths, even if reached through a symlink.\nThe initial clone uses the Zotonic repository's default branch.<\/p>\n Setup checks Docker's Ubuntu integration, starts Docker Desktop if it can find\nit, and offers Enter to retry<\/strong> or Q to quit<\/strong> if Docker is unavailable.\nIt installs a launcher folder under The folder remembers the distribution, Linux user and checkout path. Rerun\nSetup Zotonic<\/strong> there to change them. This setup manages one selected checkout\nat a time. Running setup again does not stop a previously selected project;\nstop it before switching profiles. To install newer launcher code, rerun\n Open the desktop Zotonic<\/strong> folder and double-click Start Zotonic<\/strong>.<\/p>\n The launcher starts Docker Desktop when needed, builds the development image,\nstarts PostgreSQL, and starts Zotonic automatically. Compilation on the first\nrun can take several minutes. The sources and The launcher checks the HTTP endpoint inside the Zotonic container. When it is\nready, it opens the local status site<\/a> in your Windows\nbrowser. No Use Logs Zotonic<\/strong> to see compilation and server output. Closing the log\nwindow does not stop Zotonic. Startup errors stay visible. If readiness times\nout, the containers are left available for inspection; use Logs or Stop.<\/p>\n Ports If the browser redirects to HTTPS, the development certificate is self-signed.<\/p>\n Double-click Shell Zotonic<\/strong>. This opens a shell inside the running Zotonic\ncontainer<\/strong>, as the Zotonic user, with the correct configuration paths.\nRun:<\/p>\n The command creates On Windows, open Notepad as Administrator and edit:<\/p>\n Select All files<\/strong> in the file picker to see Open your site<\/a> or\nits admin<\/a>. Log in as Type Install VS Code for Windows with its WSL extension<\/strong> and the Double-click Open Zotonic Folder<\/strong> to browse the checkout in Explorer. Its\naddress looks like:<\/p>\n Keep the working files there rather than copying them back to a Windows drive.\nSite templates are under Double-click Stop Zotonic<\/strong>. It stops and removes the managed project's\ncontainers and network, allowing up to 60 seconds for shutdown. The PostgreSQL\nvolume, source files, uploaded files and configuration remain saved. Docker\nDesktop stays running; it can be quit separately from its system-tray menu.<\/p>\n Next time, double-click Start Zotonic<\/strong>. Your site and database remain.<\/p>\n The repository's Windows Avoid First stop the old containers. If using the previous interactive setup, run\n Keep the old checkout and database volume until migration is complete. Setup\ncreates a separate Compose project whose name starts with Setup does not reset local edits or delete the old project. Moving or renaming\nthe Linux checkout changes its managed Compose project identity, so keep its\npath stable once it contains data.<\/p>\n The retry prompt waits for you to resolve Docker Desktop startup or integration\nerrors. Press Enter to check again, or Q to leave. In PowerShell, open the exact\nUbuntu distribution and user selected during setup:<\/p>\n Then, in Ubuntu:<\/p>\n The engine type must be Rerun setup and choose the normal Linux user created during Ubuntu installation.\nThe managed launchers use that user's IDs and ignore stale UID\/GID overrides.<\/p>\n For A script has Windows CRLF endings. Fresh clones made by setup use Linux Git\nwith The launcher shell logic and Compose configuration can be tested without\nWindows. Full Windows Desktop\/WSL integration still needs verification on a\nWindows machine.<\/p>","slug":"local-development-with-docker-on-windows","is_protected":false,"visible_for":0,"tz":"UTC","language":["en"],"doc_source_hash":"69b15b51a5cd2bad5d3dc9f6d2350e45f438cf1b5097f06dfcfe66ab33da340b","is_featured":false,"content_group_id":{"id":2551,"is_a":["meta","content_group"],"name":"content_group_imported_docs","title":"Imported documentation","uri":"https:\/\/zotonic.com\/id\/content_group_imported_docs"},"category_id":{"id":317,"is_a":["meta","category"],"name":"developerguide","title":"Developer guide","uri":"https:\/\/zotonic.com\/id\/developerguide"},"doc_source_path":"doc\/guides\/docker-windows.md","publication_start":"2026-11-10T10:15:30Z","github_url":"https:\/\/github.com\/zotonic\/zotonic\/blob\/master\/doc\/guides\/docker-windows.md","pivot_location_lng":null,"doc_source_kind":"guide","name":"doc_guide_docker_windows","is_unfindable":false,"is_published":true,"pivot_geocode":null,"created":"2026-11-10T10:15:30Z","uri":null,"doc_status":"current","is_dependent":false,"publication_end":"9999-06-01T00:00:00Z","modifier_id":{"id":1,"is_a":["person"],"name":"administrator","title":"Site Administrator","uri":"https:\/\/zotonic.com\/id\/1"},"privacy":0,"doc_source_commit":"8e6aad17c4d86dee983db46a656ed6f6a930bcbb\n","creator_id":{"id":1,"is_a":["person"],"name":"administrator","title":"Site Administrator","uri":"https:\/\/zotonic.com\/id\/1"},"modified":"2026-11-11T14:07:34Z","title_slug":"local-development-with-docker-on-windows"},"uri":"https:\/\/zotonic.com\/id\/3153","uri_template":"https:\/\/zotonic.com\/id\/:id","version":28,"websub":{"hub":"https:\/\/zotonic.com\/.zotonic\/websub","topic":"https:\/\/zotonic.com\/.zotonic\/websub\/topic\/3153"}},"status":"ok"}C:\\projects<\/code>. Erlang, PostgreSQL and the media\ntools run in Linux containers; your editor connects to Ubuntu through WSL.<\/p>\n1. Prepare Ubuntu and Docker Desktop<\/h2>\n
wsl --install -d Ubuntu\n<\/code><\/pre>\nsudo apt update\nsudo apt install -y git\n<\/code><\/pre>\nwsl --update\nwsl --list --verbose\n<\/code><\/pre>\n2<\/code>. If necessary, use wsl --set-version Ubuntu 2<\/code>,\nsubstituting the exact distribution name shown in the list.<\/p>\n2. Run the Windows setup once<\/h2>\n
Ubuntu<\/code> or Ubuntu-24.04<\/code>.<\/li>\/home\/YOUR_USERNAME\/projects\/zotonic<\/code>.\nKeep it inside your Linux home directory, without spaces or special characters.<\/li><\/ul>\n%LOCALAPPDATA%\\Zotonic\\WSL<\/code> and creates a\nZotonic<\/strong> shortcut to that folder on your Windows desktop.<\/p>\nsetup-wsl.cmd<\/code> from an updated repository copy.<\/p>\n3. Start Zotonic<\/h2>\n
_build<\/code> remain inside Ubuntu.<\/p>\nbin\/zotonic start<\/code> command is needed. The server continues running\nin its container after the launcher window closes.<\/p>\n8000<\/code>, 8443<\/code>, and the database forwarding port 5432<\/code> must be available.\nIf 5432<\/code> is occupied, add DB_FORWARD_PORT=5433<\/code> to the Linux checkout's .env<\/code>\nfile, preserving any existing settings. Zotonic still connects to postgres:5432<\/code>\ninside Docker. Do not change its database host to localhost<\/code>.<\/p>\n4. Create your development site<\/h2>\n
bin\/zotonic addsite -s blog -H mysite.test mysite\n<\/code><\/pre>\napps_user\/mysite<\/code>, initializes its database schema and\nstarts the site. Save the generated admin password printed in the terminal.<\/p>\nC:\\Windows\\System32\\drivers\\etc\\hosts\n<\/code><\/pre>\nhosts<\/code>. Add:<\/p>\n127.0.0.1 mysite.test\n<\/code><\/pre>\nadmin<\/code> with the generated\npassword. The status site has separate credentials.<\/p>\nexit<\/code> to close the container shell. This leaves the server running.<\/p>\n5. Edit files<\/h2>\n
code<\/code> command\non your Windows PATH. Double-click Edit Zotonic<\/strong> to open the Linux checkout\nthrough VS Code's WSL connection.<\/p>\n\\\\wsl.localhost\\Ubuntu\\home\\YOUR_USERNAME\\projects\\zotonic\n<\/code><\/pre>\napps_user\/mysite\/priv\/templates<\/code>. Zotonic receives\nLinux file-change notifications for the checkout. To explicitly rebuild, open\nShell Zotonic<\/strong> and run make<\/code>.<\/p>\n6. Stop and return later<\/h2>\n
start-docker.cmd<\/code> and stop-docker.cmd<\/code> also use this\nsaved WSL setup. They no longer mount the Windows checkout. The standalone\n.\/start-docker.sh<\/code> and .\/stop-docker.sh<\/code> are for the separate manual container\nworkflow; use the Windows launchers together for this managed setup.<\/p>\ndocker compose down -v<\/code>: -v<\/code> removes database volumes.<\/p>\nMoving from the old Windows checkout<\/h2>\n
bin\/zotonic stop<\/code> and exit<\/code> in its container, then run docker compose down<\/code>\nfrom PowerShell in the old Windows checkout. Do not add -v<\/code>.<\/p>\nzotonic-wsl-<\/code> and is\nbased on the distribution and Linux checkout path. Existing Windows project\ndatabases are not automatically migrated<\/strong>. Copy your site source files and\ntransfer the database with PostgreSQL backup\/restore; preserve uploaded files\nand any needed configuration under docker-data<\/code> as well. Do not copy _build<\/code>\nfrom the old checkout.<\/p>\nTroubleshooting<\/h2>\n
Docker is unavailable<\/h3>\n
wsl -d Ubuntu -u YOUR_USERNAME\n<\/code><\/pre>\ndocker version\ndocker compose version\ndocker info --format '{{.OSType}}'\n<\/code><\/pre>\nlinux<\/code>. A missing docker<\/code> command usually means Ubuntu\nWSL integration is disabled. Do not install a second Docker Engine with apt<\/code>.<\/p>\nUser or group ID is zero<\/h3>\n
The credential helper fails<\/h3>\n
docker-credential-desktop.exe: Invalid argument<\/code>, save your WSL work, quit\nDocker Desktop, and run wsl --shutdown<\/code> in PowerShell. This stops all WSL\ndistributions. Start Docker Desktop and retry Start Zotonic. If it still fails,\ncheck cmd.exe \/c ver<\/code> and command -v docker-credential-desktop.exe<\/code> in Ubuntu;\nkeep the diagnostic output rather than deleting Docker credential settings.<\/p>\nA script reports
bash\\r<\/code> or sh\\r<\/code><\/h3>\ncore.autocrlf=false<\/code>. If you copied scripts from the old Windows checkout,\nchange their line endings to LF in VS Code and retry. Git attributes do not\nrewrite existing files automatically.<\/p>\nValidation status<\/h3>\n