Skip to main content

4.3.0 to 4.4.0

PlanDev 4.4.0 completes the rename from Aerie to PlanDev and includes several changes that will require updates to existing deployments, mission models and integrations.

If you are upgrading an existing 4.3.0 deployment, see Upgrading an existing 4.3.0 deployment for step-by-step deployment instructions.

The major upgrade considerations are:

Review the sections relevant to your deployment before upgrading.

PlanDev rebranding​

Java packages​

All Java packages and classes across PlanDev and SeqDev have moved from either of these:

gov.nasa.jpl.aerie.*
gov.nasa.ammos.aerie.*

to:

gov.nasa.ammos.plandev.*

This affects all user-provided Java code including Mission Models, procedural scheduling goals, procedural constraints, and other Java that references PlanDev classes.

If you maintain the source code, update and rebuild these projects for PlanDev 4.4.0 using the steps below. If you only maintain compiled JARs, see Migrating Existing JARs Without Source Code. Prepare either version before upgrading if desired, but upload it only after your deployment is running 4.4.0.

  1. Replace imports and other references from gov.nasa.jpl.aerie.* or gov.nasa.ammos.aerie.* to gov.nasa.ammos.plandev.*. For example:

    import gov.nasa.jpl.aerie.merlin.framework.annotations.ActivityType;

    becomes:

    import gov.nasa.ammos.plandev.merlin.framework.annotations.ActivityType;

    Apply these replacements throughout all Java source files, including package-info.java files and test sources.

  2. Rename any Java service-loader files under src/main/resources/META-INF/services that contain the old namespace. For Mission Models, this typically includes:

    gov.nasa.jpl.aerie.merlin.protocol.model.MerlinPlugin
    -> gov.nasa.ammos.plandev.merlin.protocol.model.MerlinPlugin

    gov.nasa.jpl.aerie.merlin.protocol.model.SchedulerPlugin
    -> gov.nasa.ammos.plandev.merlin.protocol.model.SchedulerPlugin

  3. Update your project's build.gradle files:

  • Replace both old dependency group prefixes:
    gov.nasa.jpl.aerie   → gov.nasa.ammos.plandev
    gov.nasa.ammos.aerie → gov.nasa.ammos.plandev
  • Change the maven repository url from https://maven.pkg.github.com/nasa-ammos/aerie to https://maven.pkg.github.com/nasa-ammos/plandev.
  • Review remaining aerie references. local names such as aerieVersion may stay unchanged; if you rename them, update their definitions and all usages together.
  1. Clean and rebuild the project against the PlanDev 4.4.0 libraries, then reupload the resulting JAR.
    ./gradlew clean build
  2. If you are updating procedural goals or constraints, make sure to recompile them as well, for example:
    ./gradlew :scheduling:buildAllProcedureJars :constraints:buildAllProcedureJars

Existing plans do not need to be recreated. After uploading an updated Mission Model, an existing plan can be changed to use the new model from the Plan Metadata pane by selecting the Edit icon next to Model Name.

Pre-4.4.0 versions of these packages remain available under their old names for use with older PlanDev releases.

NPM packages​

PlanDev-related NPM packages now use the plandev- prefix. For example:

aerie-actions            -> plandev-actions
aerie-sequence-languages -> plandev-sequence-languages

Existing uploaded Actions and Sequence Language Adaptations do not need to be rebuilt or reuploaded for PlanDev 4.4.0. However, their source projects should update renamed NPM dependencies before the next rebuild.

Docker images and deployment configuration​

Published Docker images now use plandev- names instead of aerie- names.

The deployment files included with 4.4.0 already contain these changes. Customized deployments and other tooling that directly reference PlanDev images, containers, services, or environment variables must be updated as part of the deployment upgrade.

See Upgrading an existing 4.3.0 deployment for the required changes.

GitHub repositories​

Remaining PlanDev-related repositories that used the old Aerie name have also been renamed.

GitHub redirects links and Git operations from renamed repositories, so no immediate action is normally required. References in documentation or tooling should be updated when practical.

TypeScript Command Expansion EDSL removal​

PlanDev 4.4.0 removes support for the TypeScript Command Expansion EDSL. Sequence Templates are now the supported command-expansion workflow.

The PUBLIC_COMMAND_EXPANSION_MODE environment variable has been removed, and Sequence Template behavior is now standard for all deployments.

Existing TypeScript expansion rules, expansion sets, and expansion runs remain in the database for historical reference, but are no longer accessible through the PlanDev UI or supported for generating new expansions. Previously expanded sequences already sent to SeqDev workspaces remain unchanged.

Users of the TypeScript Expansion EDSL should migrate their expansion logic to Sequence Templates. See Removing TypeScript Command Expansion for additional details about this change.

Updated examples​

PlanDev 4.4.0 introduces a new combined repository of maintained examples. Several older standalone example repositories are deprecated in favor of it.

The new examples are located at: https://github.com/NASA-AMMOS/plandev-examples

The top-level README in this repository has general information about the collection of examples, and they each have their own descriptive README files in subfolders.

Security fixes​

PlanDev 4.4.0 includes fixes for two security vulnerabilities that will be documented in forthcoming security advisories.

User-code sandboxing​

PlanDev uses sandboxed JavaScript execution for user-provided code in features such as constraints and scheduling. Previous versions contained a sandbox isolation vulnerability that could allow untrusted user code to escape the intended execution environment.

PlanDev 4.4.0 uses a new isolated user-code runner to address this vulnerability. Users who allow untrusted or partially trusted users to provide constraint or scheduling code are strongly encouraged to upgrade.

Internal service ports​

PlanDev 4.4.0 also improves isolation of internal service APIs. The standard deployment now exposes dedicated health-check endpoints for Merlin, Scheduler, and Sequencing rather than publishing their application API ports directly.

Deployment operators should upgrade to the new configuration and ensure that only the ports documented as public-facing are accessible outside the deployment environment. Internal PlanDev service ports should be protected by the host or network firewall.

Links to the corresponding security advisories and CVEs will be added when they are publicly available.

Additional changes​

See the PlanDev 4.4.0 changelog for the complete list of fixes, improvements, and other changes included in this release.

Upgrading an Existing 4.3.0 Deployment​

PlanDev 4.4.0 completes our rename from Aerie to PlanDev. This affects container and image names, environment variables, Hasura configuration, and other deployment files.

These deployment instructions cover Docker Compose. The Kubernetes reference manifests have been refreshed for 4.4.0 on a best-effort basis but have not been tested; review and adapt them for your infrastructure before use.

This upgrade does not rename or recreate your existing databases or file-store volume, which may contain the old aerie name. Instead, the new PlanDev configuration adds environment variables to point to those existing resources.

If you do not need to preserve the data (plans, models, etc.) in your PlanDev deployment, it's easier to start from a fresh installation of v4.4.0. These instructions are for migrating an existing deployment.

1. Back up your deployment​

Back up your existing deployment before beginning. This includes your PostgreSQL database AND your existing PlanDev Docker volumes. Identify the deployment directory that your current PlanDev deployment is running from - this will be where you perform most of the upgrade steps below.

2. Update your environment​

Download and extract the 4.4.0 deployment.zip, but do not replace your existing deployment files yet. On MacOS, extracting the ZIP may produce an error. You can safely ignore it, just ensure that you extract the tar file within the zip as well.

Copy update_env.sh into your existing 4.3.0 deployment directory. With the 4.3.0 system still running, run:

bash update_env.sh

This script is intended for macOS and Linux. On other systems, review the script and perform the equivalent steps manually.

Verify that the script added the following new environment variables in your .env file:

VariableValue when upgrading
PLANDEV_USERNAMEExisting AERIE_USERNAME value
PLANDEV_PASSWORDExisting AERIE_PASSWORD value
PLANDEV_DATABASE_NAMEaerie
PLANDEV_METADATA_DATABASE_NAMEaerie_hasura
PLANDEV_FILE_STORE_NAMEExisting Aerie file-store Docker volume
PLANDEV_HOSTExisting AERIE_HOST, if configured

Other credentials should retain their existing values. Do not change the database or file-store values; the existing aerie, aerie_hasura, and file-store volume names are intentionally preserved. This script leaves the old AERIE_* variables in place for safety, but they can be removed after upgrading.

3. Stop 4.3.0​

Run this to bring down your 4.3.0 deployment (WITHOUT the -v flag):

docker compose down

4. Update the deployment files​

Keep your existing .env, including the changes made by update_env.sh.

Docker Compose​

If you have not customized docker-compose.yml, replace it with the 4.4.0 version.

If you have customized it, start by applying these replacements throughout your existing file (case-sensitive):

aerie  -> plandev
AERIE  -> PLANDEV

This updates most service names, container names, image names, environment-variable names, internal service URLs, and the Compose network.

These replacements apply to configuration names and references. Do not rename the existing databases or physical file-store volume that contain your 4.3.0 data. If your Compose file contains custom values that include aerie, review those replacements individually.

After applying the replacements, make the following additional changes.

Database configuration​

For all services that connect to the DB (any service that specifies PLANDEV_DB_HOST), add PLANDEV_DB alongside the existing host and port configuration:

PLANDEV_DB: "${PLANDEV_DATABASE_NAME}"
PLANDEV_DB_HOST: postgres
PLANDEV_DB_PORT: 5432

This includes Action Server, Gateway, Merlin and Merlin Worker, Scheduler and Scheduler Worker, Sequencing Server and Workspace Server.

The host and port values have not changed. PLANDEV_DB is new and allows upgraded deployments to continue using the existing aerie database.

In the postgres service's environment section, add or update the following entries:

PLANDEV_DB: "${PLANDEV_DATABASE_NAME:?Database name is not set.}"
PLANDEV_METADATA_DB: "${PLANDEV_METADATA_DATABASE_NAME:?Metadata database name is not set.}"
PLANDEV_USERNAME: "${PLANDEV_USERNAME:?PLANDEV_USERNAME has not been set.}"
PLANDEV_PASSWORD: "${PLANDEV_PASSWORD:?PLANDEV_PASSWORD has not been set.}"
Hasura service database URLs​

In the hasura service section, update these two variables to use the following new values:

PLANDEV_DATABASE_URL: "postgres://${PLANDEV_USERNAME:?PLANDEV_USERNAME has not been set}:${PLANDEV_PASSWORD:?PLANDEV_PASSWORD has not been set}@postgres:5432/${PLANDEV_DATABASE_NAME:?PLANDEV_DATABASE_NAME is not set}?options=-c%20search_path%3Dutil_functions%2Chasura%2Cpermissions%2Ctags%2Cmerlin%2Cscheduler%2Csequencing%2Cactions%2Cui%2Cpublic"

HASURA_GRAPHQL_METADATA_DATABASE_URL: "postgres://${PLANDEV_USERNAME:?PLANDEV_USERNAME has not been set}:${PLANDEV_PASSWORD:?PLANDEV_PASSWORD has not been set}@postgres:5432/${PLANDEV_METADATA_DATABASE_NAME:?PLANDEV_METADATA_DATABASE_NAME is not set}"
UI configuration​

If present, remove PUBLIC_COMMAND_EXPANSION_MODE from the plandev_ui service’s environment configuration, and/or from your .env. Sequence templates are now the only supported expansion mode.

File store​

In the volumes section, define plandev_file_store as follows so that it points to your existing file-store volume:

volumes:
  plandev_file_store:
    name: ${PLANDEV_FILE_STORE_NAME:?Name of the Mission Model file store volume has not been set.}
Health-check ports​

Change the container-side port for Merlin, Scheduler, and Sequencing to 8080:

plandev_merlin:
  ports: ["27183:8080"]

plandev_scheduler:
  ports: ["27185:8080"]

plandev_sequencing:
  ports: ["27184:8080"]

If you use custom host ports (first half), you may keep them. Only the container-side port (second half) changes.

Sequencing configuration​

Remove the following obsolete Sequencing settings if they are present:

SEQUENCING_WORKER_NUM: 8
SEQUENCING_MAX_WORKER_NUM: 8
SEQUENCING_MAX_WORKER_HEAP_MB: 1000
TRANSPILER_ENABLED: "true"

After these changes, validate the resulting configuration:

docker compose config >/dev/null

This should complete without errors and return nothing. For a standard 4.3.0 docker-compose.yml, these are all the required changes.

Hasura​

Replace the hasura/metadata directory in your deployment folder with the new 4.4.0 version from deployment.zip.

This updates the Hasura source name from Aerie to PlanDev, updates renamed environment variables and service URLs, and removes actions associated with the removed Expansion EDSL. If you maintain custom Hasura metadata, reapply those customizations carefully instead of blindly replacing them (this does not apply to the vast majority of users). The Hasura source rename does not rename the underlying database.

Also, copy hasura/migrations/PlanDev into your hasura/migrations folder, and remove the old hasura/migrations/Aerie folder.

Database migration script​

Remove your old migration script, aerie_db_migration.py, and copy the new plandev_db_migration.py into your deployment folder from deployment.zip

PostgreSQL initialization files​

Remove the old postgres-init-db directory in your deployment and replace it with the 4.4.0 version from deployment.zip.

HTTPS/TLS proxy​

If you use the bundled proxy, use the 4.4.0 proxy configuration or make the equivalent changes:

AERIE_HOST -> PLANDEV_HOST
aerie_ui   -> plandev_ui
aerie_gateway -> plandev_gateway

5. Get the updated Docker images​

In your deployment .env file, set DOCKER_TAG=v4.4.0 to get the updated images. Save it, then run:

docker compose pull

You should see the new v4.4.0 images pulled from the repository.

6. Start Postgres and Hasura​

Start only the Postgres and Hasura services:

docker compose up -d --force-recreate postgres hasura

Verify that both are running:

docker compose ps postgres hasura

7. Migrate the existing database​

Run the migration script to apply all migrations:

python3 plandev_db_migration.py migrate --apply --all --env-path .env

The script uses the updated hasura metadata and hasura/migrations/PlanDev directory. it may take a minute or two to finish; let it complete before continuing.

8. Start PlanDev 4.4.0​

After the migration completes successfully:

docker compose up -d --force-recreate
docker compose ps

Once the containers are healthy, you can open the UI at http://localhost (or your domain). If you have an existing user session, logout and login again before continuing. Verify that your existing plans, uploaded Mission Models, workspaces, and sequencing files are still available.

Existing Java Mission Models, scheduling goals, and constraints will require changes for the 4.4.0 Java package rename. See the Java Packages section for instructions for updating Java source projects, or the Migrating JARs section for migration options for existing compiled JAR files.

Troubleshooting​

update_env.sh cannot find the existing file store​

Run update_env.sh from your existing 4.3.0 deployment directory while the 4.3.0 system is still running. The script uses the running Gateway container to identify the existing file-store volume.

The database migration cannot connect to Hasura​

Make sure PostgreSQL and Hasura are running:

docker compose ps postgres hasura

Also verify that hasura/migrations/PlanDev exists, the 4.4.0 Hasura metadata is in place, and your existing HASURA_GRAPHQL_ADMIN_SECRET is still set correctly.

PlanDev starts, but existing data or files are missing​

Stop before creating or uploading replacement data. Verify that your .env still points to the existing resources:

PLANDEV_DATABASE_NAME=aerie
PLANDEV_METADATA_DATABASE_NAME=aerie_hasura
PLANDEV_FILE_STORE_NAME=<existing 4.3.0 file-store volume>

If the deployment directory or Docker Compose project changed during the upgrade, verify that PostgreSQL and workspace volumes are also using the original project.

Contact Us​

If you encounter an upgrade problem not covered here, contact the PlanDev team at plandev-support@googlegroups.com or in the #plandev-users channel on NASA-AMMOS Slack.

Migrating Existing JARs Without Source Code​

If you maintain compiled JARs without their source code, use Eclipse Transformer to migrate v4.3.0 Mission Models, procedural scheduling goals, and procedural constraints to v4.4.0. If you maintain the source, prefer updating and rebuilding it as described above.

1. Install Eclipse Transformer​

With Java 21 installed, download and extract Eclipse Transformer 1.0.0:

mkdir -p transformer

curl -fL \
  https://repo.maven.apache.org/maven2/org/eclipse/transformer/org.eclipse.transformer.cli/1.0.0/org.eclipse.transformer.cli-1.0.0-distribution.jar \
  -o transformer/transformer-distribution.jar

unzip -q transformer/transformer-distribution.jar -d transformer

2. Transform Your JARs​

Copy plandev-4.4-renames.properties from the deployment directory included in deployment.zip into your working directory. Use this file unchanged.

Run the following with your input and output filenames:

java -jar transformer/org.eclipse.transformer.cli-1.0.0.jar \
  original.jar transformed-4.4.jar \
  -tr plandev-4.4-renames.properties

Repeat for each JAR, retaining the originals. You can transform JARs before upgrading, but upload them only after the deployment is running 4.4.0.

3. Upload and Verify​

Upload the transformed models, goals, and constraints through their usual interfaces. For an existing plan, select the updated model under Plan Metadata → Model Name and update its goal and constraint versions.

Verify simulation, scheduling, and constraint execution before using the transformed JARs operationally.