What an update changes

Settings → Updates replaces two things: the app image and the web image. Everything else about your deployment stays exactly as it is.

What stays the same#

An in-app update does not change:

• the compose file, docker-compose.prod.yml;
• which services exist (postgres, app, web, dokku);
• volumes and published ports;
• the environment of the containers. The new app container starts with the environment the current app container already has, not with the current contents of .env. A line you added to .env reaches app through docker compose up -d, not through an update.

Your database is migrated by the new app when it starts, as described in How an update runs.

When a release changes the stack#

Some releases need more than a new image: a new service, a new volume or port, or a new required environment variable. The compose file that describes the stack ships inside the wi-server image, and install.sh is what applies it. So for such a release, run install.sh before you install the update from the Updates page:

cd /opt/wi          # the directory install.sh lives in
./install.sh

install.sh keeps your .env and secrets, adds any newly required value, extracts the docker-compose.prod.yml that matches the image it pulls, and starts anything that is new. See Upgrade the stack by re-running install.sh. It also moves app and web to the pulled images without the database backup that an in-app update takes first, so back up the database before you run it on a deployment that holds data.

What you see if you skip it#

If a release needs a stack change you have not applied, the new app container cannot start with the old container's environment. For example, a release can require a setting the old environment lacks, and the application refuses to start without it (see Production boot checks).

The install stops at the health check of the new container:

• The Updates page shows The install did not complete (health_check_blue), followed by a message that names the new container (<app container>-blue), says it exited or kept restarting instead of becoming healthy, and includes its last log lines. Those lines name the missing setting.
• The app and web you were running keep serving. Nothing was stopped, removed or renamed.
• The new container and the pulled images are left on the box for inspection, and the database dump taken at the start is kept. The new app applies its database migrations before it fails, so the database may be ahead of the version still serving.

To recover, dismiss the message, run install.sh as above, then check for updates and install again. See When an update fails for what is kept and how to read the new container's log.