Upgrading a self-hosted Parletto

This page is for an install set up with Self-hosting Parletto and the Compose file. It follows the README, docker-compose.yml, Dockerfile, bin/docker-entrypoint and CHANGELOG.md in the Parletto source, which is opening shortly under the MIT license. For an install started with docker run, see Upgrades in Running Parletto in production.

1. See what changed

Read CHANGELOG.md in the source, or the releases page of the GitHub repository, before you pull. Both open with the source. The changelog follows Keep a Changelog, and versions follow Semantic Versioning: vX.Y.Z tags are stable releases. Changes on main that are not in a release yet are listed under “Unreleased”.

Docker images are published only for releases. Each release is tagged with its version, such as ghcr.io/grafficmedia/parletto-core:v0.1.1, and with sha-<commit>. latest points at the newest release, and is what docker-compose.yml uses.

2. Back up the storage volume

The SQLite databases and uploaded files (when R2 is not configured) live in the parletto_storage volume, mounted at /rails/storage. The new release migrates those databases when it starts, so take a backup first. The commands are under Backups in the production guide. They use the container name parletto; use your container’s name instead.

3. Pull the new image

Once the image is public, run this next to your docker-compose.yml and .env:

docker compose pull && docker compose up -d

With the default latest tag, that moves you to the newest release. To stay on a specific release, set image: in docker-compose.yml to a version tag:

services:
  web:
    image: ghcr.io/grafficmedia/parletto-core:v0.1.1

A pinned install changes only when you change the tag. To upgrade it, set the new version’s tag (for example from v0.1.1 to v0.1.2), then run the same command.

Building from source

If you run Parletto from a clone of the source, as the quick start does while the image is private, pull and rebuild instead:

git pull origin main
docker compose up -d --build

This builds whatever is on main, including changes listed under “Unreleased” in the changelog.

4. How migrations run

There is no separate migration step. The image’s entrypoint is bin/docker-entrypoint and its default command is ./bin/thrust ./bin/rails server. When the command ends in ./bin/rails server, the entrypoint runs ./bin/rails db:prepare before starting the server. On an existing volume that applies any pending migrations; on an empty one it creates the databases. It runs on every start of the web container.

A container started with a different command, such as a separate bin/jobs container, does not run db:prepare. The web container migrates the databases for both.

The entrypoint runs with bash -e, so if db:prepare fails, the server does not start and the error is in the container’s logs.

5. Check that it worked

The Compose file health-checks the container by requesting /up inside it, which returns 200 once the app has booted. Docker allows 30 seconds for startup, then checks every 10 seconds and marks the container unhealthy after 5 failed checks in a row. When the container reports healthy, open your Parletto in a browser and sign in.

If it does not become healthy, read the container’s logs, then see Troubleshooting in Running Parletto in production.