Operations

Run the commands on this page from protomap, the root of your clone of hounddogai/protomap.

Upgrade

Upgrading keeps your configuration and data, and also upgrades the CLI on the computer it runs on. Back up your database first, because ProtoMap Server is briefly unavailable while the upgrade runs.

bash

git pull && ./self-hosted/scripts/upgrade.sh

ProtoMap Server runs the latest release unless PROTOMAP_VERSION in self-hosted/.env names another, such as 1.2.3. If the upgrade fails, the previous version starts again: fix the reported error and run ./self-hosted/scripts/upgrade.sh again.

Upgrade the CLI on other computers too, by running its install command again. A CLI of a different release than the server warns you when it logs in.

Go Back to an Earlier Release

The upgrade refuses a release older than the one running. To go back to one:

1. Restore the database backup you made before upgrading from that release.
2. Set PROTOMAP_VERSION in self-hosted/.env to that release.
3. Run:

bash

docker compose --file self-hosted/compose.yaml down
./self-hosted/scripts/upgrade.sh

Back Up

Back up two things together:

• self-hosted/.env — above all PROTOMAP_SECRET_KEY, which encrypts the AI provider API keys the server stores. They cannot be read without it.
• The database — with the bundled PostgreSQL, use pg_dump through Docker Compose, with the POSTGRES_USER and POSTGRES_DB from self-hosted/.env; with your own PostgreSQL, use your usual backups.

bash

docker compose --file self-hosted/compose.yaml exec postgres \
  pg_dump --username=protomap protomap > protomap-backup.sql

Logs and Troubleshooting

bash

# The services and their health
docker compose --file self-hosted/compose.yaml ps

# Logs of the whole stack, or of one service
docker compose --file self-hosted/compose.yaml logs
docker compose --file self-hosted/compose.yaml logs server

The stack is healthy when the platform opens at its address and /health answers.

Uninstall

Uninstalling removes ProtoMap Server and its data. It keeps the CLI, configuration backups, the clone, and your own PostgreSQL database.

bash

./self-hosted/scripts/uninstall.sh

To start over with a fresh installation, uninstall, then run ./self-hosted/scripts/install.sh again. With your own PostgreSQL, use a new or empty database.