azukiapp/azk

## mounts

`mounts` has three different usage options: `path`, `persistent` and `sync`. They're used to configure which folders will be internalized to the container or persisted internally by `azk`.

#### path

```js
'INTERNAL_FOLDER': path('LOCAL_PATH'),
```

Mount folder for current system machine in `LOCAL_PATH`, relatively to Azkfile.js, to `INTERNAL_FOLDER` path inside system container. If any files are modified on user machine or inside the container the file is also updated on the other end.

Note that `azk` "resolves" the path set on `path` option. This leads to two things:

  * If path does not exists it will not be mounted on container;

  * The path is always relative to host where `azk` is running, i.e. when running the containers system inside a virtual machine the host machine path will be resolved;

##### OPTS (optional)

* `resolve`: `boolean` value that drives `azk` to not resolve folder path. Its default value is `true`, if it is `false` azk will not check the path, making possible to create paths of host machine where the system of containers is running, ignoring if it locally or within a virtual machine.

#### persistent

```js
'INTERNAL_FOLDER': persistent('LOCAL_PATH'),
```

Persists the files that are inside the container on the path `INTERNAL_FOLDER`, to an `azk` persistent data folder in the user machine. The location the data will be saved will vary between Mac and Linux:

###### Mac

The folder is stored in a virtual disk (`~/.azk/data/vm/azk-agent.vmdk`) in the path `/azk/persistent_folders`. This disk is mounted in the path `/mnt/sda1` of the VM.

###### Linux

`~/.azk/data/persistent_folders/#{manifest.id}/LOCAL_PATH`.

Note that using the same 'LOCAL_PATH' in the same Azkfile.js, but in different systems, means that these systems will share the persisted data.

#### sync

```js
'INTERNAL_FOLDER': sync('LOCAL_PATH' [, OPTS]),
```

Syncs the files in `LOCAL_PATH` with a remote destination, which is mounted in the `INTERNAL_FOLDER`. Differently from `path` option, `sync` uses [rsync](https://rsync.samba.org/) instead of VirtualBox [shared folders](https://www.virtualbox.org/manual/ch04.html#sharedfolders). As result, the overall performance is significantly increased, mainly for applications which demand a great number of files (e.g. a Ruby on Rails application with a lot of assets).

##### OPTS (optional)

* `except`: an `Array` of files and/or folders to be ignored in the sync process. It uses [glob patterns](http://teaching.idallen.com/dat2330/06w/notes/glob_patterns.txt). Useful hints:
  * **Exclude a file**: `{except: ["./path/to/the/file.png"]}`
  * **Exclude a folder**: `{except: ["./path/to/the/folder/"]}` // *Mind the tailing slash!*
  * **Exclude all CSS files**: `{except: ["*.css"]}`

  > By default, `azk` ignores the following elements when syncing: `.syncignore`, `.gitignore`, `Azkfile.js`, `.azk/` and `.git/`.

* `daemon`: a `boolean` value that indicates if, when running `azk` in daemon mode (e.g. `azk start`), `azk` should either use or not use the `sync` scheme (in the negative case, the `path` scheme is used) (default: `true`);
* `shell`: similarly to `daemon` option, it's a `boolean` value that indicates if, when running `azk` in shell mode (e.g. `azk shell`), `azk` should either use or not use the `sync` scheme (in the negative case, the `path` scheme is used) (default: `false`). Setting as `false` is particularly useful to keep a two-way sync, allowing created files in the shell (e.g. via `$ rails generate scaffold User name:string`) to be persisted back in the original project folder;

##### Data persistence
When using `sync`, we need to ensure that the all data generated by [`provision`](/en/reference/azkfilejs/provision.html) will be persisted. To do this, we have to add to `mounts` a `persistent` entry with correspondent folder. Those folder may vary between languages and frameworks, but follow some examples:

* __Ruby/Rails__:
  ```js
  mounts: {
    '/azk/#{manifest.dir}'         : sync("."),
    '/azk/bundler'                 : persistent("bundler"),
    '/azk/#{manifest.dir}/tmp'     : persistent("tmp"),
    '/azk/#{manifest.dir}/.bundle' : path(".bundle"),
    '/azk/#{manifest.dir}/log'     : path("log"),
  },
  ```

* __Node.js__:
  ```js
  mounts: {
    '/azk/#{manifest.dir}' : sync('.'),
    '/azk/node_modules'    : persistent('node_modules'),
  },
  ```

##### Excluded folders
Since you use `sync` in a folder, `azk` starts to watch its files for any new change in order to re-sync the modified ones as soon as the change happens. As long as that folder has too many files, the CPU consumption can increase severally. The best way to avoid this is by telling `sync` to skip any folder which isn't absolutely required to make the system run. You can make this by any of the following ways:

* Using the `except` option for the `sync`, as listed above;
* Creating, inside the folder to be sync, a file named `.syncignore` which contains a list of files and folders to be skipped during the sync process (e.g. if you are using `sync(./MyProject)`, `azk` will look for the file `./MyProject/.syncignore`);
* If you don't have a `.syncignore` file, by default `azk` will ignore all the files and folders listed in the file `.gitignore` (inside the folder to be synced) during the sync process (e.g. analogously, if you are using `sync(./MyProject)`, `azk` will look for the file `./MyProject/.gitignore`).

##### Destination synced data

The destination path of the data that will be synced will vary between Mac and Linux:

###### Mac

The folder is stored in a virtual disk (`~/.azk/data/vm/azk-agent.vmdk`) in the path `/azk/sync_folders`. This disk is mounted in the path `/mnt/sda1` of the VM.

###### Linux

`~/.azk/data/sync_folders/#{manifest.id}/LOCAL_PATH`.

Note that using the same 'LOCAL_PATH' in the same Azkfile.js, but in different containers, will mean that they'll share the data.

> **IMPORTANT NOTE:** If you are facing performance issues using `azk` with your application, you should use this option when mounting your source code. Note it's a one-way sync, so you still have to add entries in `mounts` indicating which folders need to use the `share` option (using `path` or `persistent`).

### Examples

* __path__: Mount current project folder (`'.'`) in the container on the path `/azk/azkdemo` (considering `azkdemo` is the name of the folder where the `Azkfile.js` is located).

  ```js
  mounts: {
    '/azk/#{manifest.dir}' : path('.'),
  },
  ```

* __path (resolve: false)__: Mount `/var/run/docker.sock` to this exactly path. This avoid any `azk`'s path resolution;

  ```js
  mounts: {
    '/var/run/docker.sock': path('/var/run/docker.sock',  { resolve: false })
  },
  ```

* __persistent__: Persists the files within the container that are on the path `/azk/bundler`. The files, in this case, will be stored in the _guest machine_ inside the folder `~/.azk/data/persistent_folders/#{manifest.id}/`.

  ```js
  mounts: {
    '/azk/bundler' : persistent('bundler'),
  },
  ```

* __sync__: Syncs the project files within the container on the path `/azk/azkdemo` (considering `azkdemo` is the name of the folder where the `Azkfile.js` is located), excluding CSS files and `config` folder. Plus, use shared folders to `tmp` and `log`.

  ```js
  mounts: {
    '/azk/#{manifest.dir}'      : sync('.', except: ['*.css', 'config/']),
    '/azk/#{manifest.dir}/tmp'  : persistent('tmp/'),
    '/azk/#{manifest.dir}/log'  : persistent('log/'),
  },
  ```