Deploy an institutional learning service

1. Prepare the service and its operator

An institution gives a learning community a shared catalogue, controlled membership and individually tracked learning. Learners and authors use Tutor ACP; an operator runs the service and provisions its first owner.

Prepare PostgreSQL with verified TLS, a public HTTPS origin, a trusted reverse proxy, private server signing and integration-encryption keys, and separate API, worker and migrator credentials. Keep backups of the database and server keys together.

The ordered steps below link to the complete institutional installation procedure and operations requirements. Complete the private configuration and permissions described there before starting production processes. The operator bootstrap utility is built from the release source; use the Go version declared in that release.

2. Use a matching release and migrate the database

For a new installation, get the matching source checkout for the latest stable server release, v0.7.0. If you are upgrading an existing service, follow that release’s migration notes and back up first.

export TUTOR_VERSION=v0.7.0
git clone --branch "$TUTOR_VERSION" --depth 1 https://github.com/ArnaudGuiovanna/tutor-mcp.git
cd tutor-mcp

Keep this terminal open so TUTOR_VERSION stays pinned to that checkout. Prepare the separate private process configurations and PostgreSQL CA file, then build and run the one-off migrator:

export TUTOR_DOMAIN=tutor.example.org
docker compose -f deploy/compose.institution.yml build
docker compose -f deploy/compose.institution.yml run --rm migrator

Keep TUTOR_VERSION aligned with the release checkout rather than relying on the Compose default. A successful migration is one checkpoint; runtime permissions and institution provisioning come next.

PostgreSQL connections require sslmode=verify-full and an explicit CA file. The migrator uses its dedicated owner connection. Refer to the configuration and migration instructions for the full prerequisites.

3. Apply the separate database roles

1. On first installation, a PostgreSQL administrator grants the owner the ability to create the required group roles, or creates tutor_api, tutor_worker and tutor_restore directly.
2. As the database owner, apply deploy/postgres-roles.sql.
3. As a PostgreSQL superuser, apply deploy/postgres-roles-superuser.sql for logical tenant restoration.
4. Create a separate runtime login per process with its corresponding group role. Keep the owner credentials for migrations and operator bootstrap.

Runtime API and worker logins must not own the tables or have SUPERUSER or BYPASSRLS. The server checks these restrictions at startup. Reapply the documented grants after schema upgrades.

4. Provision the institution and its first owner

1. The future owner installs Tutor ACP, creates a local identity and confirms its encrypted backup.
2. The owner sends the operator the active and recovery npub values. The operator uses these public values for bootstrap.
3. Build the repository’s tutor-control-plane utility and use the dedicated owner connection to create an active plan, provision the tenant and bootstrap its owner.
4. Use the returned tenant ID as INSTITUTION_ID on the API. Set BASE_URL to the exact public HTTPS origin, without /mcp; optionally set INSTITUTION_NAME.

The owner bootstrap procedure provides the exact plan-upsert, provision, bootstrap-owner and add-key-member commands, their public-key arguments and request identifiers. Apply them with your institution’s plan and returned tenant ID.

New public identities cannot register themselves as owners. Institution registration is operator controlled in the documented native profile.

5. Start the API, worker and HTTPS proxy

Once migrations, grants and provisioning have succeeded, start the persistent processes:

docker compose -f deploy/compose.institution.yml up -d tutor worker caddy
curl --fail "https://$TUTOR_DOMAIN/ready"

The API and worker use their own restricted credentials; the migrator is a one-off process. Keep the application port private, preserve the public Host header and trust only the configured proxy. For systemd, follow the separate process procedure and its delivered service units.

Confirm that readiness succeeds over HTTPS and that the origin exposes /.well-known/tutor-institution with the expected institution identity. A valid TLS certificate and successful discovery are prerequisites for the desktop connection.

6. Verify owner, author and learner journeys

1. Give the owner the service’s HTTPS origin. In Tutor ACP, verify the institution and connect using the backed-up, authorised identity.
2. Grant the authoring permissions needed for course creation. Institution roles and the agent’s delegated tool permissions are checked separately.
3. Create a draft, review it and publish it to the intended institution audience.
4. Authorise a learner’s public identities, connect as that learner and verify that the permitted course can be found and joined.
5. Complete a short learning session and check that it resumes with the expected account and course.

Read institution roles and membership and sharing a course for everyday use. Learner progress access requires the appropriate role, assignments and explicit delegation. A tool permission does not confer an administrative role.

Plan the tenant restore procedure and upgrade checks before opening the service to a wider group.

Keep going.