Skip to content

Portal 1.21.0 Upgrade Guide

Overview

Portal 1.21.0 upgrades with the standard upgrade command, and no separate action is required:

cd portal-docker-setup/setup
./make.sh upgrade

This guide is for self-managed installations. It covers four changes to how the server is set up: a new container for the Portal MCP Server, where backups are stored, a new container used for backup and restore, and new limits on login attempts.

Portal MCP Server container

1.21.0 adds a portal-mcp service, which runs the Portal MCP Server. It is defined in setup/docker-compose.sample.yml alongside the portal, auth, and zwaf services, and it starts by default. The upgrade pulls its image automatically; the image is tagged with the Portal version, so it always matches the rest of the Portal.

The service needs no configuration. It reads the same environment file as the portal container and joins the same internal network. Its port is not published outside the server: AI assistants reach it through the Portal's own address, and every request is signed in with the caller's API key.

If you run the Portal from your own compose file instead of docker-compose.sample.yml (by setting DEFAULT_COMPOSE_YML_FILES or COMPOSE_YML_FILES), copy the portal-mcp service definition from docker-compose.sample.yml into it.

Backups

New backups folder

Backups are now stored in their own folder, portal-docker-setup/for_mounting/backups/, instead of portal-docker-setup/for_mounting/app/. The upgrade moves existing backup archives from app/ into backups/. It also deletes unfinished backup files left in setup/ by interrupted backup runs.

If you have scripts that copy, rotate, or delete backups, point them at the new folder.

./make.sh backup also changed: it no longer stops the Portal. The database and files are backed up while the Portal keeps running.

Restoring a backup from before 1.21.0

Backups taken with 1.21.0 or later come with a small manifest file that records the Portal version and a checksum. Older backups do not have one, so:

  • They are not listed on the new Backups page.
  • ./make.sh restore refuses them unless you add FORCE=1, because it cannot check their version:
cd portal-docker-setup/setup
FORCE=1 ./make.sh restore portal-backup-<timestamp>.tar.gz

FORCE=1 also skips the version check, so make sure the backup was taken by the same major and minor Portal version you are running.

Maintenance container

The Backups page takes backups and restores them by starting short-lived containers on the server. To do that, 1.21.0 adds a docker_socat service that gives the portal container access to the Docker engine. The service is defined in setup/compose_extra_confs/compose.maintenance.yml and is included by default.

Access to the Docker engine is equivalent to root access on the host. The service is limited to its own internal network, shared only with the portal container, and its port is never published outside the server.

./make.sh backup and ./make.sh restore use the same service. If you leave compose.maintenance.yml out of DEFAULT_COMPOSE_YML_FILES (or COMPOSE_YML_FILES), neither the Backups page nor these commands can take or restore a backup.

Login attempt limits

1.21.0 limits how often anyone can try to log in:

  • Each IP address can submit at most 5 login attempts per minute, with a short burst allowance. Further attempts get an HTTP 429 response.
  • After 10 failed password attempts in a row, a local account is locked for 15 minutes. SSO accounts are not affected.

If many users sign in from one IP address, such as behind a shared proxy, they share the per-IP limit. See Login attempt limits for how to change the per-account settings.