Project Configuration

spm works with projects. A project is a collection of libraries and services. The project configuration defines what libraries and services make up the project and the repositories where they can be located.

A library is a package / bundle that is used by multiple services. Typically libraries are things like API clients for the services but can include project skeletons or other repos.

A service is an application that will be run within docker. Typically this will be a micro service, but it could be the data services, a web site etc. Essentially anything that will run in Docker.

In the case of services; spm can provide an overview of what is currently running and what ports / domains have been exposed. This requires Docker CLI be installed. Provided your Docker environment is correctly configured, spm will work with remote docker hosts.

To create a new project run: spm project:create or spm create. You will be prompted for the name (basically the folder the config will be stored in) and then if you have a remote Git repository already. If you do, provide it and it will be checked out immediately; otherwise leave it blank and then provide the global docker compose project name. This is important as it will be the prefix used to determine the container names of the services. It should be relatively unique but not overly long e.g.: the company name, or project name.

For example:

 bin/console create
 Q  What is your projects name? Use lowercase and underscores: example
 ▲  You provided "example", is this correct? [y/n] y
 Q  What is your remote git repo to load config data from? Leave blank to skip:   
 ▲  You provided "", is this correct? [y/n] y
 Q  What will be your Docker Compose name? Use lowercase and hyphens: example
 ▲  You provided "example", is this correct? [y/n] y
 ▲  created configuration directory at /Users/dave/.spm_projects.d/example
 ▲  created configuration file at /Users/dave/.spm_projects.d/example/project.yaml
 ▲  creating git repository at /Users/dave/.spm_projects.d/example
 ✔  created git repository at /Users/dave/.spm_projects.d/example
 ✔  project created successfully, enable the project by running: use example

Standard Project Config

The generated config file has the following default structure:

somnambulist:
    project:
        name: 'example'
        repository: ~
        working_dir: '${HOME}/Projects/example'
        libraries_dirname: ~
        services_dirname: ~

    docker:
        compose_project_name: 'example'

    libraries:

    services:
    
    templates:
        libraries:
        
        services:

The config file will expand any configured env args using ${ENV_NAME} notation. Note that these may be committed back so be careful. The home path will automatically be replaced with ${HOME} provided it is available.

Project

The project section contains the top level information about the project itself. The repository is the remote repo of the project data and should be set if you wish to share the project configuration.

Libraries and Services by default are stored together within the project working directory. If you have many libraries and/or services you may wish to separate them logically into sub-folders. Specify the folder name you wish to use, and then any service/library will be added to that folder if installed or created.

Docker

The docker config contains various settings for docker. Currently this is only the project name however any other key: value pairs can be provided.

Note: in a future version this configuration may be used when creating services.

Libraries

Lists the configured libraries that are part of this project. A library config has:

• name - the name within the project (must be unique)
• repository - the remote git repository (can be null)
• dirname - the local checkout folder name

For example:

somnambulist:
    libraries:
        api_client:
            repository: 'some git repo'
            dirname: 'api-client'

Services

Services is the set of docker applications that belong to this project. A service has:

• name - the name within the project (must be unique)
• repository - the remote git repository (can be null)
• dirname - the local checkout folder name
• app_container - the name of the primary application container (should be relatively unique)
• dependencies - an array of service names this service depends on

For example:

somnambulist:
    services:
        cms-service:
            repository: 'some git repo'
            dirname: 'cms-service'
            app_container: 'cms-app'
            dependencies: ['data']

Templates

Templates allow for rapidly scaffolding new libraries / services. By default the following services templates are pre-configured globally:

• data - Data Service
• logging - Logging Service
• service - Symfony Micro Service
• web - Symfony Skeleton

Templates are grouped by type: library and service. Only library types are displayed when making new libraries, and the same goes for services.

These can be overridden globally (in the main ~/.spm_projects.d/project_manager.yaml) or on a per-project basis in the templates section.

The source can be one of:

• composer:
• git:
• in the project config templates folder
• empty

Composer Templates

composer: will use composer create-project and requires that the source be a valid installation project either registered with packagist.org or with private packagist.com.

To use a custom repository like with Private Packagist add ?repository=https://repo/source.

To specify a specific version to use add &version=XXX. To use the latest version set the version to dev-master.

The full template source would then look like: composer:namespace/project-name?repository=https://some.repo/somewhere&version=2.0.2.

Git Templates

git: will clone and remove the .git folder, essentially using the git repo as a template.

Static Templates

<folder_name> will copy all files in that folder to the new source. Additionally, if the template folder contains a post_copy.php file, this will be run after the files have been copied. This script can perform any actions needed for setup. Further: if a post_copy_args.php exists, then for each argument, a question will be asked for input that is then provided to the script. The format of the args is to return an array of key => values that. For example:

<?php
return [
    'name' => 'What is your name? ',
    'dob'  => 'What is your date of birth (CCYY-mm-dd)? ',
];

The post_copy.php file will be executed in a separate process in the context of the folder that was created. If the return type of the args is not an array nothing will be asked.

The post_copy.php file should check the arg inputs before running.

Generic Template (fallback)

If the template is left empty then a very basic folder is created with some general defaults including:

• .gitignore
• readme.md
• src/tests folder
• composer.json
• phpunit.xml.dist

A blank service template includes a few more files for docker settings.

Adding libraries / services

First ensure you have created a project, then switch to that project using spm use <project>.

Now you can run spm services:create or spm libraries:create to create one of those types. Once completed the library will be automatically registered in the project config and it will be updated.

By default a new git repository is initialised in the library folder and all files committed to the master branch.

If you have existing libraries, manually configure them in the project.yaml file or you can try the auto-importer: spm project:import. This will attempt to allocate folders to either a library or service and will try to match an active container name for the app. The rules for container names are:

• name contains -app
• the labels contain traefik.frontend.rule and the traefik.port is 8080

The import does not try to determine dependencies and will use the folder name as the project and dirname values.