How to upgrade Strapi in Docker container?

Question

I launched Strapi with Docker-compose. After reading the Migration Guide, I still don't know if I wanna upgrade to the next version, what method should I choose:

1. Under to the Strapi project directory, execute npm install strapi@<next version> -g and npm install strapi@<next version> --save
2. docker exec -it <strapi container> sh, navigate to Strapi project directory, then execute npm install strapi@<next version> -g and npm install strapi@<next version> --save
3. Neither?

Answer 1

TLDR: 3, while 2 was going in the right direction.

Official documentation wasn't clear for the first time for me either. Below is a spin-off step-by-step guide from 3.0.5 to 3.1.5 in docker-compose context.

It tries to follow official documentation as close as possible, but includes a some extra (mandatory in my case) steps.

Upgrade Strapi

• Following relates to strapi/strapi (not strapi/base) docker image used via docker-compose
• Important! Upgrading Docker image versions DOES NOT upgrade Strapi version.
  • Strapi NodeJS application builds itself during first startup only, if detects empty folder and is normally stored in mounted volume. See docker-entrypoint.sh.
• To upgrade, first follow the guides (general and version-specific) to rebuild actual Strapi NodeJS application. Secondly, update docker tag to match the version to avoid confusion.

Example of upgrading from 3.0.5 to 3.1.5:

# https://strapi.io/documentation/developer-docs/latest/guides/update-version.html

# Make sure your server is not running until the end of the migration
## That is unclear instruction. Stopped Nginx to prevent access to application, without stopping Strapi itself. 
docker-compose exec strapi bash # enter running container
## Alternative way would be `docker-compose stop strapi` and manually reconstruct container options using `docker`, overriding entrypoint with `--entrypoint /bin/bash`

# Few checks
yarn strapi version # current version installed
yarn info strapi #npm info strapi@3.1.x version # available versions
yarn --version #npm --version
yarn list #npm list
cat package.json

# Upgrade your dependencies
sed -i 's|"3.0.5"|"3.1.5"|g' package.json && cat package.json
yarn install #npm install
yarn strapi version

  # Breaking changes? See version-specific migration guide!

  ## https://strapi.io/documentation/developer-docs/latest/migration-guide/migration-guide-3.0.x-to-3.1.x.html
    ## Define the admin JWT Token
    ## Update username constraint for administrators
    docker-compose exec db bash
    psql strapi strapi
      -- show tables and describe one
      \dt
      \d strapi_administrator
    ## Migrate your custom admin panel plugins

# Rebuild your administration panel
rm -rf node_modules # workaround for "Error: Module not found: Error: Can't resolve"
yarn build --clean #npm run build -- --clean

  # Extensions?

# Start your application
yarn develop #npm run develop
# Confirm & test, visit URL

  # Errors?

  ## Error: ENOSPC: System limit for number of file watchers reached, ...
  # Can be solved by modifying kernel parameter at docker HOST system
  sudo vi /etc/sysctl.conf # fs.inotify.max_user_watches=524288
  sudo sysctl -p

# Modify docker-compose to reflect version changed and avoid confusion !
docker ps
vi docker-compose.yml # e.g. 3.0.5 > 3.1.5
docker-compose up --force-recreate --no-deps -d strapi
# ... and remove old docker image, when no longer required.

P.S. We may together improve documentation via https://github.com/strapi/documentation. Made a pull request https://github.com/strapi/strapi-docker/pull/276

Answer 2

1. In your local developer tree, update the package version in your package.json file. Run npm install or yarn install locally. Start your application. Verify that it works. Run your tests. Fix any compatibility issues from the upgrade. Do all of this without Docker involved at all.

2. Re-run docker build . to rebuild your Docker image with the new package dependencies.

3. Stop the old container, delete it, and run a new container with the new image.

As a general rule you should never install anything in a running container. It's extremely routine to delete containers, and when you do, anything in the container will be lost.

There's a common "pattern" of running Node in Docker, bind-mounting your application into it, and then mounting an anonymous volume over your node_modules directory. For routine development I've found it vastly simpler to just install Node on my host (it is literally a single apt-get install or brew install command). If you're using this Docker-oriented setup, the anonymous volume for node_modules won't notice that you've changed your node_modules directory, and you have to re-run docker build and delete and recreate your containers.