Jump to heading # Introduction and overall architecture

Jump to heading # Introduction

Phabalicious stores all project related configuration for tooling and setup in a single place per project, the so-called fabfile.yaml which lives in the root-folder of a project. It documents all available installations of a given application (e.g. local, dev-, stage- and prod-instances)

Phabalicious "knows" how to interact with certain types of applications like drupal, laravel etc. and offers the developer a handful of useful commands to interact with these applications like deploying a new version of the application to a remote instance, getting a database from a dev-environment or getting a shell on a remote instance regardless where the application is hosted.

Phabalicious knows also how to handle the evironment which is hosting the application, be it your local computer, a dockerized environment, a remote server or a Kubernetes cluster. That helps the developer to control the application.

Phabalicious' open architecture and its flexibility makes it easy to extend the core functionality to support hard-to-integrate environments e.g. ssh jump hosts, docker on remote instances, etc. The scaffolding system helps generating host-specific configuration files e.g. for docker-compose or Kubernetes or by scaffolding whole new projects.

Phabalicious can be used with a multitude of applications, hosting environments and can be tightly integrated with e.g. Continuous Deployment Tooling.

Inheritance and remote configuration files allow teams to store configuration centrally and override and extend it on a per project- and host-level which helps in minimizing outdated configuration.

Jump to heading # Architecture

Jump to heading # Naming things

Phabalicous uses a custom naming convention to differentiate things better. Here's a short explanation:

• A host is an entry in the fabfile under the hosts-section which encapsulates all configuration under a unique name.
• A command is the command you execute by running phab, e.g. phab list:hosts. Here the command is list:hosts. A command is usually executed against a given host-configuration
• Every host declares a list of needs. A need will be fullfilled by an existing method implemented by phabalicious. One host might need the functionality of the script-method, and of the ssh-method. Here's a list of all implemented methods
• Some methods provide a shell-provider. A shell provider knows "how" to get a shell for a host, e.g. by starting a ssh-connection.
• Every method requires different config-parameters from the host-configuration, which will be validated on startup.
• Every command will execute one or multiple tasks. Every needed method can now react to a given task and do its work. Every enabled method will also be consulted when preparing the execution of a task, and when the task is finished.

Jump to heading # How a command is executed

Here's a series of diagrams showcasing what happens exactly behind the scenes when executing the command deploy with the following host-config:

hosts:
  test:
    needs:
	  - ssh
	  - git
	  - mysql
	  - script
    ...

1. Check if a backup is required
2. Run the task deploy and reset against all needed methods

A closer look into how tasks are executed with methods.

1. First run the deployPrepare-task against all needed methods
2. Run the deploy-task against all needed methods
3. Finally run the deployFinished-task against all needed methods
4. Do the same for the reset-task

Let's zoom into the deploy-task:

This should give you an overall idea how things are connected in phabalicious. Also with this approach it is very easy to combine different methods together (e.g. a laravel-application with a sqlite-database) and to extend the functionality with custom scripts.

Jump to heading # The fabfile.yaml

The fabfile is the central place for all project related configurations. It can inherit configuration from local and remote files to include centralized configuration very easily which helps a team to prevent copy-paste which leads to outdated configurations on the long run. Local overrides allow the developer to adapt the global project configuration to his particular needs.

The fabfile contains also all custom scripts which can use pattern-replacements to inject configuration values into the running script to enhance reusability of code. Scripts can also be invoked before, on, or after the execution of specific tasks.

Jump to heading # The scaffolder

Phabalicious contains a powerful scaffolder, which can support the developer in creating new projects from scratch, alter existing projects in a given way or create tailored configuration- or definition-files for other tools like docker-compose or kubectl. The twig-template-engine allow the developer to inject specifc configuration into the scaffolded files.