Storage Service Settings in the Boxfile

Last Updated October 2014

Network storage services are persistent file-stores with read/write access. Anything directory that needs writable permissions must be stored in network storage. For a detailed explaination of network storage, view the Network Storage Documentation. The Boxfile is responsible for much of the granular control and streamlined workflow available on Pagoda Box. It is a yaml config file that houses all configuration related to your app’s deployment and infrastructure and allows you to custom-configure your app's environment to your project's specific needs. This doc outlines Boxfile configurations related to network storage. After reading it, you will be familiar with:

  • Configuring network storage services
  • What options are available in the Boxfile

Overview of Network Storage Boxfile Settings YAML

  storage1:
    name: storage-name
    type: nfs
    topology: single
   
  web1:
    network_dirs:
      storage1:
        - path/to/directoryA
        - path/to/directoryB
      storage2:
        - path/to/directoryC
/Boxfile

Network Storage Service Config Options

Name

Using a custom name for your storage service will help act as a quick reference in your app dashboard. If you have multiple storage services, custom names come in handy.

name YAML

  storage1:
    name: shawna
/Boxfile
Type

The "type" config specifies which file system engine should be used in your storage service. Currently, there is only one type available (NFS), but more will be available in the future.

You Must Include a Storage Type

A storage type must be included in your Boxfile config. If no type is specified, the service will not be created on deploy.

type YAML

  storage1:
    type: nfs
/Boxfile
Topology

Topology defines the services architecture and in what ways it can scale. Currently, only the "single" topology is supported for NFS. More information can be found in the Service Topologies doc.

topology YAML

  # default setting
  storage1:
    type: nfs
    topology: single
/Boxfile

Network Directories

Network directories are not specifically a part of your storage service configuration, but they are directly connected. Network directories are declared in web and worker Boxfile configs. The directories themselves are stored on your storage service(s).

Network Directories

These directories are read/write accessible to all your web instances. These directories are mounted at runtime, and should not be created at the same location as a directory containing source code in your repo. Filepaths should be relative to the root of your repo.

In order to use network_dirs, you must have one or more storage services to store them on. In your Boxfile config, specify which storage service the directories should be stored on. If no storage service is specified, we assume storage1.

For more details, view the Network Storage Documentation.

network_dirs YAML

  web1:
    network_dirs:
      storage1:
        - path/to/directoryA
        - path/to/directoryB
      storage2:
        - path/to/directoryC
/Boxfile

Contents of Network Directories are Obscured by Network Mounts

On deploy, network directories are replaced with network mounts, which connect instances to your network storage service(s). These mounts obscure anything committed to your repo inside of those directories. If there are files inside network directories in your repo, your app will not be able to access them unless you manually upload them into your network storage service.

If you have any questions, suggestions, or corrections, let us know.