Updating Your Container

Local Docker projects run the PhantomWP runtime (dev server, terminal, git, and file operations) inside a container built from a released image. When a new release fixes something in that runtime, you pick it up by recreating your container on the newer image.

Your project files are not stored inside the container. They live in a Docker volume or in a folder on your machine, so recreating the container keeps them.

When to Update

PhantomWP does not prompt you. Nothing compares your running container against the latest release, so updating is always something you choose to do rather than something you are told about.

Update when:

• The changelog mentions a new local development Docker image version
• Release notes describe a fix "in the container runtime" or say it "requires the updated container image"
• You are troubleshooting an issue and want to rule out an old runtime

If you are on GitHub Codespaces, none of this applies. Hosted projects receive runtime updates through the editor's Infrastructure dialog instead, and never need a container update.

How to Update

1. Open your Dashboard
2. Find the project card and open its ⋯ menu
3. Click Update container
4. Copy the command from the dialog
5. Paste it into your terminal and run it

The dialog states the version you are moving to, and the command is generated for your specific project, using its ports and its existing storage.

What the Command Does

It is three steps:

docker pull ghcr.io/phantomwp/local-dev:<version>
docker rm -f phantomwp-my-site
docker run -d --name phantomwp-my-site -p 14321:4321 -p 14322:8080 -v 'phantomwp-my-site:/app' ...

1. Downloads the new image
2. Removes the old container
3. Starts a new container on the same ports, pointed at the same /app storage

docker rm -f looks alarming, but it removes only the container. Your project lives in the volume or bind mount named in the third line, which is reused as-is, so your files, your git history, and any uncommitted work are all preserved.

After It Runs

• docker ps should list the container with the new image tag
• Open the project from the dashboard; the IDE reconnects on its own
• The first load can take a few seconds while the dev server starts

To confirm which version you are on:

docker ps --filter name=phantomwp-my-site --format '{{.Image}}'

If "Update Container" Is Missing

The menu item only appears for local Docker projects whose ports PhantomWP has on record, since the generated command needs them to map the right ports.

• Confirm the project actually runs locally. Codespaces projects do not show this item.
• If the project was never finished setting up locally, use Start Locally first to complete setup, then the item appears.

Projects Created Before Mount Tracking

Projects created on older release candidates, including rc5, may warn that PhantomWP did not record where /app was stored when the container was created. Choose the storage before copying the update command:

• If you used the original generated command unchanged, leave Map to a local folder unchecked and click Save mount choice. PhantomWP reuses the default named Docker volume, such as phantomwp-my-site:/app.
• If you edited the command to mount a local folder, check Map to a local folder, enter the exact folder path you used, then click Save mount choice.

There is no automatic volume discovery, so this has to be correct. For a standard setup it is safe, because the volume name matches the container name. Do not delete the Docker volume unless you intend to erase the project files.

Troubleshooting

"The container name is already in use"

The old container was not removed. Remove it and re-run the last line of the command:

docker rm -f phantomwp-my-site

"Port is already allocated"

Something else is using the project's ports. Find it, or stop other PhantomWP containers:

docker ps

Each local site gets its own port pair starting at 14321, so several sites can run at once, but only one container can hold a given port.

The IDE will not reconnect

1. Check the container is running: docker ps
2. Check health: curl http://localhost:<ws-port>/health
3. Read the logs: docker logs phantomwp-my-site
4. In Chrome or Edge, make sure you allowed local network access when prompted. Without it the browser blocks phantomwp.com from reaching localhost.

My files are gone

Almost always this means the new container was started against different storage, not that anything was deleted. Check that the -v part of the command you ran matches the one you originally used, then re-run with the correct mount. List your volumes with:

docker volume ls

Rolling Back

If a new runtime causes a problem, run the same three commands with the previous version tag in the docker pull and docker run lines. Your files are untouched by the swap.

Next Steps

• Docker Local Development: full guide to running locally
• Changelog: what changed in each release
• Troubleshooting: general issue catalog