Projects

Mutagen’s project format is a lightweight orchestration mechanism that offers a way to declare and automate the creation and management of synchronization and forwarding sessions alongside other operations. Projects are a good alternative when Mutagen Compose doesn’t fit your use case.

By combining Mutagen’s project orchestration with scripts and container orchestration tools like Docker Compose or Kubernetes®, you can create reproducible development environments that can be shared across your development team and run on cloud-based infrastructure.

Getting started

The following sections provide information about using Mutagen’s project orchestration features, but the best way to experience this is simply to try it yourself. You can find an example web application in the Mutagen repository that combines a Docker Compose container setup with Mutagen project orchestration to create a reproducible, cloud-based, containerized development environment.

Usage

Project orchestration is managed by the mutagen project commands. These commands operate on a mutagen.yml file in the current directory (or a file specified using the -f/--project-file flag). They create a lock on this file (to ensure that only a single instance of a project is running) and then operate on the synchronization and forwarding sessions defined within the file. Certain project commands also have hooks associated with them that can be used to attach custom behavior.

The organization of the mutagen project commands mirrors that of individual session management commands, with commands like list, pause, resume, and so on. The only difference is that these commands operate on all of the sessions in a project at once. However, the sessions in a project are otherwise normal sessions (they just have a label that binds them to the project), so they can also be managed individually using their names or session identifiers and the relevant mutagen sync and mutagen forward commands.

Starting a project

To create and start the sessions associated with a Mutagen project, switch to the project directory and run:

# Start a Mutagen project.
mutagen project start

If the project file defines beforeCreate and/or afterCreate hooks containing commands, they will be run before/after all sessions are created, respectively.

Sessions that have flushOnCreate specified (see below) will be flushed after session creation and before the afterCreate hook. This doesn’t apply if the sessions are being created in a paused state by using the -p/--paused flag with mutagen project start, in which case the sessions won’t be flushed.

Running commands

If the mutagen.yml file defines custom commands in a commands section, they can be invoked by name using:

# Run a Mutagen project command.
mutagen project run <command-name>

Listing sessions

To list the sessions associated with a project, you can use:

# List the status of project sessions.
mutagen project list

This will show the status of individual sessions, including any problems or conflicts that may have arisen.

Flushing sessions

To flush the synchronization sessions associated with a project, you can use:

# Flush project synchronization sessions.
mutagen project flush

Pausing sessions

To pause the sessions associated with a project, you can use:

# Pause project synchronization and forwarding sessions.
mutagen project pause

If the project file defines beforePause and/or afterPause hooks containing commands, they will be run before/after all sessions are paused, respectively.

Resuming sessions

To resume or reconnect sessions associated with a project, you can use:

# Resume project synchronization and forwarding sessions.
mutagen project resume

If the project file defines beforeResume and/or afterResume hooks containing commands, they will be run before/after all sessions are resumed, respectively.

Resetting sessions

To reset the synchronization sessions associated with a project, you can use:

# Reset project synchronization sessions.
mutagen project reset

Terminating sessions

To terminate all sessions associated with a project and shut down the project itself, you can use:

# Terminate project synchronization and forwarding sessions.
mutagen project terminate

If the project file defines beforeTerminate and/or afterTerminate hooks containing commands, they will be run before/after all sessions are terminated, respectively.

Project file format

To best understand the Mutagen project file format, check out the example project’s mutagen.yml file.

Mutagen’s project file format is a simple extension of the global configuration file format described in the introduction. In addition to a defaults key for synchronization and forwarding, it allows you to define keys that refer to named sessions. Project sessions can also have endpoint-specific configuration options, which are specified using the configurationAlpha and configurationBeta keys for synchronization sessions and configurationSource and configurationDestination keys for forwarding sessions. Finally, synchronization sessions (including defaults) can have the flushOnCreate key specified, which indicates that they should have a full synchronization cycle forced right after creation. This is most useful when you need to start infrastructure in the afterCreate hook that relies on files existing remotely. The most general session configuration structure would look something like:

sync:
  defaults:
    ...default synchronization configuration...
    flushOnCreate: ...
  example-sync-session:
    alpha: ...
    beta: ...
    flushOnCreate: ...
    ...configuration...
    configurationAlpha:
      ...alpha-specific configuration...
    configurationBeta:
      ...beta-specific configuration...
  ...

forward:
  defaults:
    ...default forwarding configuration...
  example-forwarding-session:
    source: ...
    destination: ...
    ...configuration...
    configurationSource:
      ...source-specific configuration...
    configurationDestination:
      ...destination-specific configuration...
  ...

Setup and teardown

As previously mentioned, project files also allow you to define beforeCreate, afterCreate, beforeTerminate, and afterTerminate hooks, which run a series of commands before and after creation and termination of all sessions (not individual sessions). These are simply lists of commands that are run in the system shell, for example:

beforeCreate:
  - docker-compose up --build --detach

afterTerminate:
  - docker-compose down --rmi=all --volumes

Custom commands

Finally, to help with creating common workflows, you can also define commands in projects using the commands section. These commands can be run using the mutagen project run command, for example:

commands:
  web-shell: docker-compose exec web bash
  db-shell: docker-compose exec psql -U appuser -d appdb