Getting started: deploying to the platform (Preview)

This guide continues from Getting started: building a service, where you built the School Timetabling model as a service. It walks you through deploying that same model to Timefold Platform, so it can be reached through a managed, multi-tenant REST API instead of mvn quarkus:dev on your own machine.

For the reasoning behind why you’d want to do this, see Deploying to the Timefold Platform.

Deploying custom models to the platform is in preview.

This is currently only available to a limited set of partners. If you’re interested in joining this preview program, get in touch with the Timefold team to discuss access.

Prerequisites

To complete this guide, you need:

  • The School Timetabling service built in Getting started: building a service.

  • A Timefold Platform account with tenant-admin access to the tenant you want to register the model in.

  • A Personal Access Token (PAT), scoped to the tenant you want to register the model in, with Create, Read, Update, and Delete permissions on the Registered Model resource. See Generate a Personal Access Token below.

  • Push access to Timefold’s container registry, since the configure goal builds and pushes your model’s container image there. This access needs to be requested; get in touch with the Timefold team before you try to deploy.

Timefold Platform requires your model to be built with the Enterprise Edition of Timefold Solver, but building doesn’t require a license, only running it does, and the platform provides that license when your model runs there. See Build with the Enterprise Edition below.

1. Add the Maven plugin

The timefold-maven-plugin connects your build to the platform’s container registry and handles registering your model. Add it to your pom.xml, and configure it with your platformUrl, a registration key for your model, and the tenant(s) to register it under.

Your platformUrl will typically be https://app.timefold.ai. (See Integration scenarios if you’re deploying to a different installation, for example a self-hosted platform or a different data residency region.)

Also set handleSubscription to true, so your tenant gets subscribed to the model when you deploy it; see What happens on deploy below.

Follow the setup instructions in the Maven plugin documentation to add and configure it.

2. Build with the Enterprise Edition

Timefold Platform requires your model to be built with the Enterprise Edition of Timefold Solver; a Community Edition build cannot be deployed. By default, your build uses the Community Edition, so you need to opt in explicitly. This also gets you the Enterprise Edition features surfaced by the platform, such as score analysis.

Build with -Denterprise=true to activate the enterprise Maven profile defined in timefold-solver-service-parent, which pulls in the Enterprise Edition dependencies:

mvn clean package -Denterprise=true

The Enterprise Edition requires a license key to function at runtime, as described in Installation. Building with the Enterprise Edition does not require a license; a license is only checked when the model actually runs. When you deploy to Timefold Platform, the platform provides that license for you, so you don’t need one of your own just to follow this guide.

You still may want a license if you want to run your Enterprise Edition build locally, for example to test the model with mvn quarkus:dev before deploying it. Every new account on the Timefold License Manager starts with a free, time-limited Enterprise trial, so you can create and download fully functional Enterprise Edition license files without talking to sales first. We also offer free licenses to non-profit organizations and for academic research.

3. Authenticate

3.1. Generate a Personal Access Token

Generate a PAT from your user menu on the platform (User menu → Access tokens → Generate new token). When selecting its permissions, scope the token to the tenant you want to register the model in, and grant Create, Read, Update, and Delete on the Registered Model resource, since the plugin needs all four to register, update, and later undeploy your model.

See Authentication with Personal Access Tokens for the full walkthrough, including screenshots of the token generation dialog.

3.2. Export the token

The plugin reads your PAT from the TIMEFOLD_PAT environment variable. Export it before building:

export TIMEFOLD_PAT=<your-personal-access-token>

4. Build and deploy

Build and deploy your model in a single command. -Denterprise=true is required, since the platform only accepts models built with the Enterprise Edition; see Build with the Enterprise Edition above.

mvn clean package -Denterprise=true timefold:deploy

4.1. Preview without pushing container

To preview what would happen without actually pushing the container image or registering the model, add -Dtimefold.dryRun=true. This logs the requests that would have been made instead of sending them.

4.2. What happens on deploy

During package, the build generates a model descriptor (target/timefold/timefold-model-descriptor.json) and packages it together with the OpenAPI specification, JSON schemas, and default configuration profile into target/model-descriptor.zip.

The timefold:deploy goal uploads that archive and registers it against the platform’s model registration endpoint (POST /api/platform/v1/models), using the key and tenants from the plugin configuration.

If a model with the same key is already registered, the deploy fails with a conflict (HTTP 409) unless overwrite is enabled, in which case the existing registration is updated instead (PATCH /api/platform/v1/models/<key>). You can also set this from the command line with -Dtimefold.model.overwrite=true.

Registering a model does not automatically subscribe your tenant to it; with handleSubscription set to true, the plugin also subscribes your tenant when it registers the model. Without it, your tenant won’t see the model on the platform after you deploy it.

5. Verify on the platform

Log in to the platform UI at your platformUrl and find the model under your tenant. Before considering the model ready for review, confirm the following:

  • The model shows up in your tenant: go to Manage tenant → Models and confirm your model is listed, with the version details (major API version, and the current minor version’s build time, commit, and solver version) matching what you just deployed. If it’s missing, double check that handleSubscription is set to true in the Maven plugin configuration.

  • It solves: submit your demo dataset and confirm the solve completes with a reasonable score.

  • The output looks right: inspect the resulting schedule and check that lessons are assigned sensible timeslots and rooms.

  • Constraints show up by name in score analysis: the score analysis breakdown should show your constraints under human-readable names, not raw identifiers. This requires the richer constraint metadata described in Constraint descriptions and groups.

  • Input and output metrics show up: the dataset view should display the metrics you exposed, as described in Using metrics.

  • You can add a configuration profile: add a new configuration profile in the UI and override one of your constraint weights, then confirm a re-solve picks up the new weight. See Configuration profiles for the properties that define the default profile shipped with your model.

Next