diff --git a/Configuration.md b/Configuration.md index 3104067..79ab3cd 100644 --- a/Configuration.md +++ b/Configuration.md @@ -1,46 +1,53 @@ -By default, **Loom Spinner** spins up a pretty powerful environment all by itself, without the need for further -configuration. +# Configuration -It is understandable, however, that you may need different settings for different projects. For example, maybe you're -building a CLI tool, so have no need for a webserver; you can pass the `--disable-server` option to the `spin:up` -command and the default server (Nginx) won't be installed alongside your PHP Container. +By default, **Loom Spinner** provides a powerful environment for your PHP projects—no extra configuration required. +However, Loom Spinner is designed to be flexible, so you can easily tailor your environment to suit different project needs. -This document explains the different ways to configure your project environments created with Spinner. +For example, if you're building a CLI tool and don’t need a web server, you can simply pass the `--disable-server` option to the `spin:up` command to exclude Nginx. -# Default Configuration +This page explains how to customize your environments using command line options or a project configuration file. -The default configuration for Spinner environments can be found at [config/spinner.yaml](https://forge.winningsoftware.co.uk/LoomLabs/spinner/src/branch/main/config/spinner.yaml) -in the Spinner repository. +> **Important:** +> **Configuration options and changes (including updates to `spinner.yaml` or CLI options) are only considered when you +> first build the environment with `spin:up`.** +> If you make changes to your configuration file or want to apply new settings after the containers have already been +> created, you must destroy (`spin:down`) and rebuild (`spin:up`) your environment for the changes to take effect. -# Custom Configuration +--- -On the page for the build command (`spin:up`), you will have seen that you can pass options to the command which allow -you to further configure your environment. +## Default Configuration -## Argument Priority +Every Loom Spinner environment starts with sensible defaults, defined in the [default configuration file](https://forge.winningsoftware.co.uk/LoomLabs/spinner/src/branch/main/config/spinner.yaml) in the repository. -Environment options and arguments are considered in the following priority order: +--- -- Those explicitly passed to the commands via the CLI -- Any set in the `spinner.yaml` file in your projects root directory -- Fallback to the default configuration found in this repository at `config/spinner.yaml` +## Custom Configuration -This means that if you were to set `environment.database.enabled: true` in your config file, but pass the -`--disable-database` flag when running the `spin:up` command, your projects settings would be overridden by -the flag you passed in. +You can adjust your environment by: -## Command Line Arguments +1. **Passing options to the CLI** + Override settings directly when you run commands. +2. **Creating a `spinner.yaml` config file** + Place this file in your project root to define project-wide defaults. -Please consult the table in the [All Configuration Options](#all-configuration-options) section for a list of all -available command line options. +### Configuration Priority -## Using Custom Configuration +When configuring, Loom Spinner checks for values in this order (highest to lowest): -As an alternative to passing lots of options to the `loom spin:up` command, `loom` allows you to create a configuration -file in the root of your project: `spinner.yaml` +1. Command line options +2. Values in your project's `spinner.yaml` +3. The global defaults from the repository + +For example: + +If your `spinner.yaml` sets `environment.database.enabled: true`, but you run `spin:up` with `--disable-database`, the CLI flag takes precedence. + +--- + +## Example: Disabling XDebug via YAML + +If you’re happy with most defaults but want to disable XDebug, your config might look like: -Your `spinner.yaml` file can contain as many or as few custom options as your project requires. For example, if you're -happy with the default settings, but you just don't need xdebug, your `spinner.yaml` file might look like this: ```yaml options: @@ -49,19 +56,32 @@ options: xdebug: false ``` -For a full example of available options, please consult the `config/spinner.yaml` file in this repository for whichever -version you are currently using. You can also consult the table below for a list of all current available configuration -options if you are using the latest version. -## All Configuration Options +You can specify as many or as few options in `spinner.yaml` as needed. + +--- + +## Command Line Arguments + +Most configuration options can also be supplied directly at the command line when creating your environment. + +--- + +## Available Options | Option | Config Key | Accepted Values | |----------------------|---------------------------------------|-------------------------------------------------------| -| `--php` | `environment.php.version` | Any PHP version with a valid PHP FPM Docker Image | -| `--disable-xdebug` | `environment.php.xdebug: false` | - None in CLI
- `true`/`false` in `spinner.yaml` | -| `--database` | - | Currently only accepts: `sqlite`/`sqlite3` | -| `--disable-database` | `environment.database.enabled: false` | - None in CLI
- `true`/`false` in `spinner.yaml` | -| `--disable-server` | `environment.server.enabled: false` | - None in CLI
- `true`/`false` in `spinner.yaml` | -| `--node` | `environment.node.version` | Any valid version of Node i.e. `20` | +| `--php` | `environment.php.version` | Any PHP version with a valid Docker FPM image | +| `--disable-xdebug` | `environment.php.xdebug: false` | CLI: none
YAML: `true`/`false` | +| `--database` | - | `sqlite` or `sqlite3` | +| `--disable-database` | `environment.database.enabled: false` | CLI: none
YAML: `true`/`false` | +| `--disable-server` | `environment.server.enabled: false` | CLI: none
YAML: `true`/`false` | +| `--node` | `environment.node.version` | Any valid Node.js version (e.g., `20`) | +For a comprehensive example of all options, see the [`config/spinner.yaml`](https://forge.winningsoftware.co.uk/LoomLabs/spinner/src/branch/main/config/spinner.yaml) +in the repository. +--- + +For more help with configuration, see the detailed [Commands](Commands) documentation and try different options to find +the setup that best fits your project.