WP Instances

FAQ and troubleshooting

Frequently asked questions

Do I need to know Docker?

No. WP Instances starts Docker Desktop, builds what it needs and runs your sites. You only need Docker Desktop installed.

Why does it need Docker Desktop and WSL?

Your sites run in Linux containers (nginx, PHP and MariaDB), like on real hosting. On Windows, Docker Desktop runs them, and Docker Desktop needs WSL (Windows Subsystem for Linux).

Does it change my Docker Desktop settings?

Only one: before starting Docker Desktop, WP Instances turns off Docker's option to open its dashboard window on start, so Docker starts quietly in the tray. Nothing else is changed.

Will it interfere with my other Docker projects?

No. WP Instances uses its own containers and volumes, all named wpx. When you quit, Stop My Sites stops only those. Only Stop Sites & Docker Desktop stops other containers, because it stops Docker Desktop itself.

Do I need to edit the hosts file?

No. Sites use <name>.127.0.0.1.nip.io addresses. nip.io is a public DNS name that always points to your own PC (127.0.0.1), so no hosts file and no admin rights are needed.

Can other people on my network open my sites?

No. The sites, the database, the inbox, phpMyAdmin and the dashboard only accept connections from your own computer.

What's the login for a new site?

admin / admin. It's shown under Admin login on the Overview tab. You rarely need it: Open admin signs you in without a password. See Working with sites.

I restored a backup and admin / admin doesn't work

The restore brought the live site's users and passwords with it. Use Open admin (or press U) to sign in as any of those users without a password.

Can my local copy email real customers?

No. Every email is caught on your PC. See Mail.

Does closing the window stop my sites?

No. WP Instances keeps running in the tray and your sites stay up. To stop them, right-click the tray icon, choose Quit WP Instances, then Stop My Sites. See Settings reference.

Can it start with Windows?

Yes. Right-click the tray icon and tick Start with Windows. It then starts in the tray at sign-in, without opening a window.

What happens to my sites when the trial ends?

They keep working. You need a license to create, import or duplicate sites. See License and trial.

Troubleshooting

"Docker Desktop is needed"

Docker Desktop isn't installed. Click Get Docker Desktop, install it, then open WP Instances again.

"WSL is needed"

Docker Desktop is installed, but WSL isn't. This is common on a new PC.

  1. Click Install WSL and approve the Windows prompt. It runs Microsoft's own installer.
  2. When it finishes, restart your PC.
  3. Open WP Instances again.

"Docker Desktop didn't start within 10 minutes"

Open Docker Desktop yourself to see what it needs: an update, WSL, or a restart. Then click Try again on the start screen.

"WP Instances couldn't start"

The start screen shows the reason. Fix it if you can, then click Try again. The details are in the log file, %APPDATA%\WP Instances\logs\main.log.

"The Docker stack isn't running"

This bar appears when the sites' containers aren't running, for example after Docker Desktop was stopped. Start Docker Desktop, then click Try again in the bar.

"Port 8080 is used by another program"

Another program has the site port, so your sites can't start on it.

  1. Click Change port… in the bar at the top. The Settings dialog suggests the next free port.
  2. Click Apply. Every site's URLs are rewritten to the new port.

Or close the other program and click Try again.

The database, the mail inbox, phpMyAdmin and the dashboard move to a free port by themselves when theirs is taken. Only the site port waits for you, because it's part of every site's address.

"WP Instances is already running on port …"

Another copy of WP Instances is already running. Close it first, because two copies would manage the same sites. If you open WP Instances while it's already running in the tray, the running copy's window just comes to the front.

Windows SmartScreen blocks the installer

The installer isn't code-signed, so SmartScreen shows Windows protected your PC. Click More info, then Run anyway. It only asks once.

A site doesn't open in the browser

  1. Check the status bar says docker running. If it says stack stopped, see above.
  2. Check the address and port in the status bar (http :8080).
  3. nip.io addresses are looked up through public DNS. If your PC has no working DNS, the name can't be found.
  4. A page saying wp-instances: no instance named '…' means there is no site with that name.

A site shows "There has been a critical error on this website"

WP Instances has probably found the cause already. Select the site: a banner names the plugin or theme and offers a one-click fix. See Debugging and critical errors.

A site broke after switching PHP

A plugin or theme doesn't support that PHP version. Switch back on the Overview tab's PHP menu, or read the error on the Debug tab. See PHP versions.

"Busy: … is still running"

Only one job runs on a site at a time. Wait until it finishes; click the job in the status bar to watch it.

"Couldn't find where Docker Desktop keeps the site files"

Show files, Open in VS Code and file links look for the site files in Docker Desktop's WSL share. If your Docker Desktop keeps them somewhere else:

  1. Find the wpx_sites volume folder, usually \\wsl.localhost\docker-desktop\mnt\docker-desktop-disk\data\docker\volumes\wpx_sites\_data.
  2. Open %APPDATA%\WP Instances\.env in a text editor.
  3. Set SITES_HOST_PATH= to that folder.
  4. Quit and restart WP Instances.

Open in VS Code does nothing

WP Instances opens VS Code with the code command. Make sure VS Code is installed and that typing code in a new command prompt opens it. The VS Code installer adds it to your PATH by default.

Copying a big backup into the site folder fails with "not enough space"

Dragging large files into the \\wsl.localhost folder can fail with that message even when there's room. Use Import backup… instead: Restore Now or Only Copy for the Plugin copies the files through Docker. See Importing backups.

A restore says the backup is encrypted or password-protected

Decrypt an UpdraftPlus .crypt backup with your UpdraftPlus key first. For All-in-One WP Migration, create a backup without a password.

The live address couldn't be read from the backup, and the job log said so. Run the import again with Live site URL filled in.

A preview is missing or out of date

Press R on the site. Previews need Microsoft Edge. If the homepage answers with a server error, the old preview is kept.

An email doesn't show up

Click Send test email. If the test arrives, catching works and the plugin that should send isn't sending; check its settings or the Debug console. Code that sends through an email service's API directly, without WordPress, isn't caught.

The dashboard shows "Something went wrong"

Click Reload. Your sites aren't affected.

Where things are

What Where
App log %APPDATA%\WP Instances\logs\main.log
A job's log Show Details in the job's progress window
A site's PHP and WordPress errors The site's Debug tab
Settings, license and app data %APPDATA%\WP Instances
Site previews %APPDATA%\WP Instances\data\thumbs
Site files The Docker volume wpx_sites. Use Show files to open them.
Databases The Docker volume wpx_db_data
Caught emails The Docker volume wpx_mail_data
Cached WordPress downloads The Docker volume wpx_core_cache

Uninstalling

Uninstall WP Instances from Windows Settings → Apps. Your sites, databases and settings are kept, so reinstalling brings everything back.

To remove everything:

  1. Before uninstalling, delete your sites in WP Instances, or later remove the wpx containers and the wpx_ volumes in Docker Desktop.
  2. Delete the folder %APPDATA%\WP Instances.

Still stuck?

Contact support via warcal.dev/contact. Include:

  • your WP Instances version (About WP Instances)
  • what you did and the message you saw
  • the job log (Show Details) or the end of %APPDATA%\WP Instances\logs\main.log