@dorfjungs/relocator

Moving states among environments.

Installation

In case you don't want to use the docker image, you can install it directly via npm:

npm install -g @dorfjungs/relocator

The only requirement is Docker.

Configuration

The configuration of your project is done in a .relocator.yml file. You can place it wherever you want, but the root directory is recommended.

After you've created the .relocator.yml config file, you can start to fill it all the states your project requires. A state (e.g. mysql) is simply a specific type of content attached to an environment (e.g. staging).

Creating environments

There's not much to talk about here. Just take a look at the following configuration snippet, it's self-explanatory:

environments:
  # A unique name of your environemnt
  - name: local
    # This flag protects the environment from being manipulated.
    # It basically means: Read-Only. Default is `false`
    protected: true
    # The states for your environment
    states: []

You add this to the root level of the .relocator.yml file

Creating states

You can attach as many states as you like. Just make sure the name matches across the environments, so you don't end up with invalid data on one of your environments.

states:
  # The name of the state.
  # You need a compatible state in a different environment,
  # so they can communicate with one another.
  - name: fs
    # The type (or `plugin`) used to handle this state (import/export)
    # You need a compatible type in a different environment
    type: rsync
    # This is the type-specific config (rsync in this case)
    # Each plugin has its own set of rules
    config:
      delete: yes
      chmod: D777,F777
      paths:
        uploads: ./uploads

You add this to .environments[].states[] in the .relocator.yml file

Using environment vars

You can easily inject any environment variable from your process. The cli will also read the .env file lying beside the .relocator.yml file.

environments:
  - name: staging
    states:
      - name: fs
        type: rsync
        config:
          chmod: ${LOCAL_FS_CHMOD}
          paths:
            uploads: $LOCAL_UPLOAD_DIR

Using secrets

In order to use secrets from your secret API you just have to tell the tool where to fetch the secrets from in your .relocator.yml config file:

secret:
  # The endpoint of your secret api. e.g. https://secrets.company.com/
  endpoint: $SECRET_ENPOINT
  # A random string defined by you to sign each request
  token: $SECRET_TOKEN
environments:
  - name: production
    states:
      - name: db
        type: mysql
        config:
          host: { from_secret: 'secrets/customer_db/host' }
          password:
            from_secret: 'secrets/customer_db/password'
          ...

The cli will fetch the secrets via signed http requests using the defined token as a secret. You add this to the root level of the .relocator.yml file

Plugins

s3

Compatible with: s3, rsync

# Purge before imporing to remove old files?
# Default: no
purge: yes
# The lang env var to use for the aws cli
# default: C.UTF-8
lang: en_US.UTF-8
# The key to use for the aws-cli commands
key:
  id: keyId
  secret: keySecret
# The path mapping
# Make sure the name matches in your environments
paths:
  uploads1: bucketName/path
  uploads2: bucketName2/path

rsync

Compatible with: rsync, s3

# Add `--delete` flag to rsync command?
# Default: no
delete: yes
# Folder and file permissions set by rsync
# Default: None
chmod: D777,F777
# Optional ssh connection to use instead of localhost
# Default: None
ssh:
  host: hostname_or_ip
  user: ssh_user
  key: base64_encoded_private_ssh_key
# The path mapping
# Make sure the name matches in your environments
paths:
  uploads: ./uploads

mysql

Compatible with: mysql

# Mysql connection config
database: database_name
host: hostname_or_ip
username: database_user
password: database_pass
# Optional ssh connection to use instead of localhost
# Default: None
ssh:
  host: hostname_or_ip
  user: ssh_user
  key: base64_encoded_private_ssh_key
# Extra arguments to add to the `mysqldump` command
# This can differ from server to server
# Default: []
dumpargs:
  - --set-gtid-purged=OFF
  - --column-statistics=0

Usage

After you've created the .relocator.yml, you can easily run the following commands to move the states:

relocator move <from> <to>

# Examples
relocator move staging local

# The environemnt name matches with `startsWith`,
# which allows you to do the following, you lazy f*ck :D
relocator move s l

# Oh no the `.relocator.yml` is no in the root. FEAR NOT
relocator move --config ./stupid/sub/dir/.relocator.yml prod loc

# Force import and ignore the `protected` flag
relocator move --force staging production

# Limit to one or multiple states
relocator move --limit=db loc prod
relocator move --limit=db1,fs1 loc prod

# MOAR output
relocator move --verbose staging local

Development

To release a new version simply run yarn version <major|minor|patch> to update the package.json and then just git push origin master. Our CI/CD will handle the rest.