Lagoon Scaffold

Lagoon Scaffold is a utility allowing for the quick setup of new projects on Lagoon.

It is a simple script that points to a number of git repos that contain scaffolding information.

Usage example

Lagoonizing a new Laravel 10 project

Install Laravel (see installation docs). If your installation is installed at, say, /home/myaccount/projects/example-app you can run the following

lagoon-scaffold --scaffold=laravel --targetdir=/home/myaccount/projects/example-app

Running the above will attempt to install the files required by a Laravel project into the target directory. Your Laravel project should now be ready to be pushed up to Lagoon.

Omitting the --scaffold option will prompt you to select a scaffold from a list.

Providing scaffolds

Primary scaffold manifest

The primary scaffold manifest is located in the main branch of the lagoon-scaffold repo.

At build time, the file is embedded in the lagoon-scaffold binary, which provides a fallback if the scaffolds.yml file cannot be downloaded from the repo.

Scaffold structure

Minimally a scaffold must contain a .lagoon directory and a .lagoon/flow.yml file. All other files are optional.

Given a selected scaffold, we check out the latest commit of the scaffold's branch and clone it into the target directory into a temporary directory (which is removed post lagoonization).

The .lagoon/flow.yml file is then opened and, if in interactive mode, the user is asked a series of questions.

.lagoon/flow.yml

Flow files contain three kinds of question types, test, select, and conditional, these are demonstrated below:

questions: # Marks the start of a list of questions
  - name: aSelectList # "name" fields should be simple, no spaces, no special characters - these are used in filling out templates
    help: Help text goes here
    options:
      - option1
      - option2
      - option3
    type: select # The type of question
    required: true # Whether the question is required
    prompt: Select one of these options # The prompt to show the user
    default: option1 # The default value
  - name: firstConditional
    help: This is a conditional question, under which we can have subquestions
    prompt: This is a conditional question
    type: conditional
    questions:
      - name: conditional1Text
        type: text
        required: true
        prompt: This is a sub text question
        default: default value
      - name: anotherConditional
        type: conditional
        required: true
        prompt: This is a sub question
        default: default value
        questions:
          - name: conditional_question3
            type: text
            required: true
            prompt: This is a sub question
            default: default value

Once the questions have been answered, we recursively search through the cloned scaffolding and apply the values to any .lgtmpl files we find. The flow file above will produce a data structure suitable for processing by template files, which would look like this:

{
  "aSelectList": "option1",
  "firstConditional": {
    "answer": false,
    "conditional1Text": "some text",
    "anotherConditional": {
      "answer": false,
      "conditional_question3": "default value"
    }
  }
}

Importantly, the values generated by "conditionals" contain a special field answer which contains the user's response to the conditional itself.

We then strip the .lgtmpl from the file name and copy the concretized data to disk. Once this is done, we copy all the files from the scaffold directory into the target directory.

If there is a .lagoon/post-message.txt file, this is shown to the user.

Finally, the temporary directory with the scaffolding is removed.