Configuration

Magallanes allows you to deploy your application in any way you can dream up, and it’s thanks to the powerful and flexible configuration options that this is possible.

Initiating New Project

In order to use Magallanes we have to initialize a project. This is done with the init command. Similar to git this will create a .mage directory where all the configuration, environments, custom tasks, and logs are stored.

To understand about directory structure in this tool, please read here.

$ mage init --name="My fantastic app" --email="notifications@my.app" 

Right now the most important file is .mage/config/general.yml. In there is stored the project name and notification email, and also if notification delivery and logging are enabled. The log files store everything Magallanes does, all commands and results, so if you need to debug something that’s the place to start with. The maxlogs indicates how many logfiles are saved, when reached the older logs are deleted. These are quantity of files not days.

# global settings
name: My fantastic app
email: notifications@my.app
notifications: true
logging: true
maxlogs: 30

# These options are not enabled by default
composer_cmd: composer5.6-sp
# => This is composer command Magallanes going to use.
php_cmd: php5.6-sp
# => This is php command Magallanes going to use.

Add An Environment

Now the fun begins. We have our project initiated so now is it’s time to add an environment. An environment is to where we want to deploy our code and what to do with it. So an environment will store the configuration of to where to copy the application and what to do with it once deployed. Also we can configure our environment to work with releases, imagine it as a rudimentary versioning of our deployments. We will talk about releases later.

$ mage add environment --name="production" --enableReleases

With that last command we have just created a new environment named production. This will create the configuration file .mage/config/environments/production.yml. We must edit that file in order to configure the environment.

# production environment
deployment:
  strategy: rsync-remote-cache
  user: dummy
  from: ./
  to: /var/www/vhosts/example.com/www
  excludes:
    - app/cache/*
    - web/bundles/*
  excludes_file: .rsync_excludes
extras:
  enabled: true
  directory: shared
  vcs:
    enabled: true
    kind: git
    repository: git@github.com:example/example.git
    branch: master
    remote: origin
    directory: repo
  rsync:
    enabled: true
    from: ./
    local: .rsync_cache
    remote: cached-copy
releases:
  enabled: true
  max: 10
  symlink: current
  directory: releases
hosts:
  - 172.16.0.101
  - 172.16.0.102
  - 172.16.0.201:2222
tasks:
  pre-deploy:
    - scm/update
  on-deploy:
    - symfony2/cache-warmup: {env: prod}
  post-release:
    - purge-apc-cache
  post-deploy:
    - purge-varnish-cache

Also if you want to know which environments you have already configured, you can run the following command and it will display the existing environments.

$ mage list environments

Configuring An Environment

Following the previous example we will edit the .mage/config/environments/production.yml file to configure the environment. Let’s see the sections of the configuration file and what we can setup there.

Deployment

Setting	Options and Examples
Deployment Strategy Deployment strategy Magallanes going to use to deploy. List available strategies: disabled, git-rebase, git-remote-cache, rsync, rsync-remote-cache, tar-gz.	strategy: NAME strategy: rsync-remote-cache
Username This is the username used for SSH connections.	user: USERNAME user: dummy
Application Source The location of the application, usually is the same directory where Magallanes is, but it could be any other path. Eg: ./something or ../hello-world or /Users/YourUser/hello	from: DIR from: ./public
Application Destination The remote directory where the application is gonna be copied. If you are working with releases this should not be the document root.	to: DIR to: /var/www/app
Excludes Exclude directories and/or files when using `rsync` or `rsync-remote-cache`. These exclusions are relative to the site's source directory and cannot be outside the source directory. Magallanes always exclude `.mage` and `.git` directories.	excludes: [DIR, FILE, ...] excludes: .gitignore
Excludes File If you have a long list of files and directories need to be exclude. Please use this instead of `excludes`	excludes_file: FILE excludes: .rsync_excludes

Do not use tabs in configuration files

This will either lead to parsing errors, or Magallanes will revert to the default settings. Use spaces instead.

Hosts

In the hosts section we configure a list of hosts (IPs or hostnames) to where the rsync will run against. You can also specify a port number like in the example above. Also, note that you should be able to do an SSH connection to the host using ssh keys without passphrase, so you won’t be requested any password.

hosts:
  - 10.10.10.10
  - connect-to-me

Tasks

In the tasks section we configure which tasks to run and when. You can look a complete list of built-in tasks here. Each task is executed in the configured order and in a specific part of the deployment, these moments are these:

Setting	Options and Examples
Pre Deploy Before deployments begins. Useful for vendor installation and scm update tasks.	pre-deploy: TASK pre-deploy: scm/update
On Deploy Executed on each host after the code has been copied. Useful for cache warmup, symlinks creations, etc.	on-deploy: TASK on-deploy: symfony2/cache-warmup: {env: prod}
Post Release Executed on each host after the release has been executed.	post-release: TASK post-release: purge-apc-cache
Post Deploy After the deployment is completed. Useful for general tasks like cleanup a cache system.	post-deploy: TASK post-deploy: purge-varnish-cache

You can setup here your own tasks, bultin tasks always starts with a namespace of the task type it belongs (eg: scm, deployment, etc). On the other hand custom tasks don’t have a namespace.

(to be continue…)

Back

Next