Skip to content

movefile.yml configurations explained

Jump to bottom Edit New page
Alessandro Fazzi edited this page Apr 6, 2018 · 24 revisions

First of all: movefile.yml is a YAML file. If you really have no idea take a look at this cookbook. It is abused in the ruby world, but YAML is used as well in the PHP frameworks world.

Just some notes before the rude doc

2 space indentation delines the data structure!

It's not optional nor coincidental!

Wordmove's configuration file naming is valid in different flavours:

  • movefile.yml (default)
  • movefile.yaml
  • movefile (backward compatibility)
  • Movefile (backward compatibility ref)

If this is clear, let's go.

Doctor

The doctor command will harldy try to do formal validation on your movefile.yml. Please, use it when something blows up, at least as source of information to report an issue on the tracker.

First level keys: the environments

global:
  ...
local:
  ...
production:
  ...

These are the default first level keys and denotes your environments. global ad local are mandatory. global is not really an environment, but is the place where we put options which change global behaviours. production is a convention for naming the remote env, but you can rename it as you like:

global:
  ...
local:
  ...
mycoolremotehost:
  ...

You can add as many new environments as you need:

global:
  ...
local:
  ...
test:
  ...
production:
  ...

More about environments can be found in the wiki article Multiple environments explained

Global options

global:
  sql_adapter: "wpcli"

mandatory

@since 2.1.0

sql_adapter introduces support to wp-cli's search-replace command as DB adapter. If you want to switch back to the old built-in adapter, you can set this option to default.

Funny is that default adapter is no more the default, but it retains its old naming. Sorry for the confusion.

No futher options could be passed to wp command through Wordmove. We use wp as per https://codex.wordpress.org/Changing_The_Site_URL#wp-cli, adding the —all-tables and --allow-root options.

You'll see the exact executed command in STDOUT

Per environment options: local

local:
  vhost: "http://localhost:8080"

mandatory

vhost is the url you use to get to your site. If you work using wp server - as I wish - the vhost will be the one in the above snippet. Keep in mind that if you install wordpress in subdirectories, the subdirectory should be part of the vhost. Possibly you should also configure accordingly the wp-config.php file

define( 'WP_HOME', 'http://myproject.local' );
define( 'WP_SITEURL', 'http://myproject.local/wp' );

but it's up to you knowing how to configure your WP ;)

local:
  wordpress_path: "/home/me/dev/site"

mandatory

Is simply the absolute path of you installation. With or without heading slash should work the same.

local:
  database:
    name: "mydatabase"
    user: "root"
    password: "toor"
    host: "localhost"
    port: 3306
    mysqldump_options: "--max_allowed_packet=50MB" # Only available if using SSH
    mysql_options: --protocol=TCP # mysql command is used to import db

mandatory keys: name, user, password, host

@since 3.0.0 database.charset option is no more supported. Pass the '--default-charecter-set' flag into database.mysqldump_options or to database.mysql_options instead, if you need to set the same option.

Here we point to our local database; I think it self-explaining. In other situations you can alter port to suite your needs, otherwise we'll use the default as per the above snippet.

You can pass as a string any mysqldump accepted option inside the mysqldump_options key.

You can pass as a string any mysql accepted option inside the mysql_options key.

mysqldump_options: "--max_allowed_packet=50MB --ignore-table=dbname.wp_cf7dbplugin_submits --ignore-table=dbname.wp_cf7dbplugin_st"

Per environment options: remotes

As stated before you can have any number of remote configured and named as you need. Each of the remotes accepts the same set of configurations.

production:
  vhost:
  wordpress_path:
  database:
    ...

These work exactly as per the local environment. Read the previous section, but the following exceptions:

  1. If you use FTP as transfer protocol, the wordpress_path will be the relative path as you'll see inside your user's FTP jail. Usually it's something like /html or /htdocs. It's up to you to know how your hosting works ;)

  2. A note: you have always to configure the database credential based on how you configured wp-config.php; when working on a remote, Wordmove will firstly connect to it and within there it will connect to the database. So do not imagine to connect from your laptop to the database, but think from the WP install perspective. We think it's even easier to simply copy credential from the wp-config.php, isn't it?

production:
  exclude:
    - ".git/"
    - ".gitignore"
    - ".sass-cache/"
    - "node_modules/"
    - "bin/"
    - "tmp/*"
    - "Gemfile*"
    - "Movefile"
    - "movefile"
    - "movefile.yml"
    - "movefile.yaml"
    - "wp-config.php"
    - "wp-content/*.sql"

optional

The list of files listed under the exclude key will be ignored during push and pull operations. This let you do not push some files or folders or let you do not delete files which exist on the remote only. In the snippet above are listed the default options.

paths:
  wp_content: "wp-content-custom"
  wp_config: "wp-config-custom.php"
  uploads: "wp-content-custom/uploads"
  plugins: "wp-content-custom/plugins"
  mu_plugins: "wp-content-custom/plugins"
  themes: "wp-content-custom/themes"
  languages: "wp-content-custom/languages"

optional

With this option you can customize Wordpress internal paths if you put/name them in non standard ways. This must be displayed in the Wordmove file for both local and external environments; for example, staging and production.

production:
  ssh:
  # ftp:

mutual and mandatory

These two keys configure Wordmove with the desired protocol. We wish and recommend you use SSH over FTP. You can't have both the protocols present inside a single remote, but you can have multiple remotes with different protocols.

production:
  ssh:
    host: "host"
    user: "user"
    password: "password" # password is optional, will use public keys if available.
    port: 22 # Port is optional
    rsync_options: "--verbose" # Additional rsync options, optional
    gateway: # Gateway is optional
      host: "host"
      user: "user"
      password: "password" # password is optional, will use public keys if available.

mandatory key: host

  • user the user on the remote host
  • port is self-explanatory
  • password is a deprecated option which lets you hardcode your ssh password inside the movefile.yml. Read here for more informations.
  • rsync_options lets you pass any rsync valid option to the underlying rsync (you bet). This is just a proxy/command builder, so keep in mind that options are accepted based on the rsync version installed on your machine
  • gateway lets you use another ssh server as a proxy to your final destination. Also here password is depracated.

Please note that the only mandatory key is host, because you can configure SSH connections in ~/.ssh/config, thus using the specified host will call in all the options expressed there. For example, having a ~/.ssh/config with

Host client_X_staging
  Hostname 79.99.8.94
  User welaika
  Port 1337
  ProxyCommand ssh code -W %h:%p

you can fill movefile.yml just like this

staging:
  ssh:
    host: client_X_staging
production:
  ftp:
    user: "user"
    password: "password"
    host: "host"
    passive: true
    scheme: "ftps" # default "ftp"

mandatory keys: user, password, host

The only note about these options is about scheme: it defaults to ftp and the only alternative option is ftps. passive can be true or false based on your hosting.

Please note that having password as mandatory key, makes this configuration security sensitive, thus risky to be put on a Git repository.

production:
  hooks: # Remote hooks won't work with FTP
    push:
      before:
        local:
          - 'echo "Do something locally before push"'
        remote:
          - 'echo "Do something remotely before push"'
      after:
        local:
          - 'echo "Do something locally after push"'
        remote:
          - 'echo "Do something remotely after push"'
    pull:
      before:
        local:
          - 'echo "Do something locally before pull"'
        remote:
          - 'echo "Do something remotely before pull"'
      after:
        local:
          - 'echo "Do something locally after pull"'
        remote:
          - 'echo "Do something remotely after pull"'

Entire hooks section in optional

@since 2.4

hooks are separated in 2 groups: push and pull. Each group of commands will be evaluated while performing the matching action (wordmove push/wordmove pull).

Hooks will ignore what you will push or pull: they will be evaluated if you do wordmove push --all as much as you'd have done wordmove push --themes. I think making this more configurable would ends in an unusable mess of configurations.

Each group of hooks split itself in two subgroups: before and after. Commands brought by these groups will be executes at the matching timing: before pushing/pulling or after have pushed/pulled.

The deeper and last split is between local and remote. This the environment where the commands will run. remote environment will obviously be the one where the configuration is contained.

Remote hooks can't run over FTP; you will be warned if you'll try to do that.

It's redundant to say, but: hooks cannot be configured in the local environment.

You can read more about hooks on the dedicated wiki page.

production:
  forbid:
    push:
      db: false
      plugins: false
      themes: false
      languages: false
      uploads: false
      mu-plugins: false
    pull:
      db: false
      plugins: false
      themes: false
      languages: false
      uploads: false
      mu-plugins: false

Entire forbid section in optional

@since 3.0

forbid section needs to forbid (!) Wordmove's actions by config. By mean of actions we're speaking about push/pull plus a specific task. In the example above we have the complete list of tasks available to each action with default configurations (false value).

forbidden tasks will ignore command line flags. So if you have forbid.push.db: true in your movefile.yml and you'll call wordmove push -d you will have a warning such as:

Forbid warning message example

Note that tasks names are the same as in the long form of the command line flags.

Note that value must be BOOLEAN, not strings. wordmove doctor is able to detect such errors.

YAML tips

Moved in a dedicated wiki page

Add a custom footer
Add a custom sidebar
Clone this wiki locally