Chauffeur

Welcome to Chauffeur, deliverying changes to your Umbraco environment in style.

Who is Chauffeur?

Chauffeur is a CLI for Umbraco, it will sit with your Umbraco websites bin folder and give you an interface to which you can execute commands, known as Deliverables, against your installed Umbraco instance.

Chauffeur is developed for Umbraco 7.x as it is designed around the new Umbraco API.

Getting Started

To get started install Chauffeur and open up a command window and launch Chauffeur.Runner.exe, which is the entry point for Chauffeur. From the prompt you can get started running deliverables.

Build Status

Included Deliverables

Help

Aliases: h

umbraco> help

List all the Deliverables which are installed.

umbraco> help <deliverable>

Executes the help system for the specified Deliverable. If the deliverable doesn't implement IProvideDirections you won't get any additional documentation and I suggest you bug the author of the Deliverable.

Quit

Aliases: q

umbraco> quit

Exists Chauffeur

Install

Aliases: none

umbraco> install

Installs an empty Umbraco database. This is like running the Umbraco installer from the web UI.

While the installer runs it will create the User with the the 0 ID, the default user account. This account will have the default username and password as Umbraco provides (which is admin and default) but you probably won't be able to log in with it as the password is meant to be hashed but the SQL doesn't hash it. You should combine this with the user Deliverable to setup the correct user password.

If you're using SqlCE as the database then the Deliverable will prompt tp create the file as well as run the SQL scripts, if you don't want to be prompted pass y to the Deliverable when run. If you're using a different database provider make sure there is an empty database to connect to.

Note: The Deliverable expects the Umbraco connection string to be set in the web.config.

User

Aliases: u

umbraco> user <delivery> <arguments>

A series of sub-deliveries which can be undertaken against Umbraco users

Change-Password

umbraco> user change-password <id> <old password> <new password>
umbraco> user change-password 0 default password

Changes the password of a user, you generally want to combine this with the install Deliverable so you can setup a user that can log in.

Package

Aliases: p pkg

umbraco> package <package name>

A Deliverable that will look for a file with that name and a .xml extension in the Chauffeur directory with which it can import items from an Umbraco export and import the contents into the database. The XML can be either from the Umbraco packager (yes, you have to extract the XML file from the ZIP), by using the Export option in the back office or by using the files generated by usync.

The following types can be imported:

• Document (Content) Types
• Data Types
• Templates
• Macros

Note: There is an expectation that with Templates and Macros the files are on disk (eg: in your VCS), this just created the database entries so they appear in the back office.

Delivery

Aliases: d

umbraco> delivery

Tells Chauffeur to locate all .delivery files and run them in order. If a delivery is successfully delivered it will be tracked in the database as such and skipped next time you run the Deliverable.

Delivery Files

This is just a plain text file which contains a series of Deliverables to execute.

Let's assume we had one called 001-Setup.delivery

The contents might be:

install y
user change-password 0 default my-secret-password
package DataTypes
package Templates
package Macros
package DocumentTypes

Content-Type

Aliases: ct

umbraco> content-type <delivery> <arguments>

A series of sub-deliveries which can be undertaken against Umbraco ContentType's.

umbraco> content-type get-all

Lists all ContentType's in a quick summary.

umbraco> content-type get <id or alias>

Gets a specific ContentType and lists its properties.

umbraco> content-type export <id or alias>

Exports a specific ContentType which is then output to Chauffeur's directory.

umbraco> content-type import <exported file name>

Imports a ContentType from the specified file, you don't need to provide the .xml extension it is assumed.

Change Alias

Aliases: ca

umbraco> change-alias <type> <old> <new>

A deliverable which will change the alias of a particular Umbraco "type", such as a Document Type. This is useful as there's no way from the Umbraco packager to do an alias change.

FAQ

• Why do I see all this extra text when I run content-type commands?

This is a fun bug in 7.0.4, they included some Console.WriteLine statements in the source code which Chauffeur ends up receiving. This seems to have been resolved in 7.1.0.

• Can I make my own Deliverables?

Sure you can, you need to implement the Deliverable class and drop your assembly in the bin folder and it'll be loaded up.

• What doesn't work?

Keep in mind that this is running outside of the web context so there's no HttpContext. This means that some Umbraco API's simply won't work, things like the publishing. Also be aware of the pointy edges of the Umbraco API, there's a lot of internal classes and members that Umbraco will expect (have a look at the PropertyGroupId setup) so things might not be setup that you'd expect. Remember we're using the Umbraco APIs but we're bypassing the Umbraco "boot" process. At the moment you have to manage your own dependency chain, and if there are statics these can bleed across Deliverables so be aware.

• Where do I put the files for the delivery and package Deliverable?

Chauffeur expects these files to be on disk in the App_Data\Chauffeur folder, where App_Data is relative to the root of the website (where your umbraco.config lives).