embark/site/source/docs/storage_configuration.md

title: Configuring decentralized storages layout: docs

With Embark, we easily connect to decentralized storage solutions such as IPFS and Swarm. This enables us to upload, storing and download data and assets for our decentralized applications. Let's take a closer look at how to make use of this.

Configuration basics

Embark will check our preferred storage configuration in the file config/storage.js, unless configured differently in our application's embark.json file. This file contains the preferred configuration for each environment, with default being the configuration that applies to every environment. If environments in Embark are new to you, check out the dedicated guide first and come back.

Each of these configuration options can be individually overridden on a per environment basis.

module.exports = {
  "default": {
    "enabled": true,
    "ipfs_bin": "ipfs",
    "available_providers": ["ipfs", "swarm"],
    "upload":{
      "provider": "ipfs",
      "host": "localhost",
      "port": 5001,
      "getUrl": "http://localhost:8080/ipfs"
    },
    "dappConnection":[
      {"provider": "swarm", "host": "localhost", "port": 8500, "getUrl": "http://localhost:8500/bzz:/"},
      {"provider": "ipfs", "host": "localhost", "port": 5001, "getUrl": "http://localhost:8080/ipfs/"}
    ],
    "versions": {
      "ipfs-api": "17.2.4"
    }
  },
  "development": {
    "enabled": true,
    "provider": "ipfs",
    "host": "localhost",
    "port": 5001
  }
}

The available options are:

Option	Type: default	Value
enabled	boolean: true	Enables or completely disables storage support
ipfs_bin	string: ipfs	Name or desired path to the ipfs binary
available_providers	array: ["ipfs", "swarm"]	List of storages to be supported on the dapp. This will affect what's available with the EmbarkJS library on the dapp.
upload		The upload element specifies storage provider settings used for uploading your dapp. A swarm node will be automatically launched in a child process using these settings.
upload.provider	string: ipfs	Desired provider to use when uploading dapp.
upload.protocol	string: http	Storage provider protocol for upload, ie http or https
upload.host	string: localhost	Host value used to interact with the storage provider for upload, i.e. localhost or swarm-gateways.net
upload.port	integer: 5001	Port value used to interact with the storage provider for upload, i.e. 5001 (IPFS local node) or 8500 (Swarm local node) or 80
upload.getUrl	string: http://localhost:8080/ipfs/	Only for IPFS. This sets the file/document retrieval URL, which is different than the host/port combination used to interact with the IPFS API.
dappConnection		List of storage providers to attempt connection to in the dapp. Each provider process will be launched in a child process. Each connection listed will be tried in order on the dapp, until one is avaialable. Can also specify $BZZ to attempt to connect to an injected swarm object.
dappConnection.provider	string: ipfs	Desired provider to use for dapp storage.
dappConnection.protocol	string: http	Storage provider protocol used in the dapp, i.e. http or https
dappConnection.host	string	Host value used to interact with the storage provider in the dapp, i.e. localhost or swarm-gateways.net
dappConnection.port	integer	Port value used to interact with the storage provider in the dapp, i.e. 5001 (IPFS local node) or 8500 (Swarm local node) or 80. Can specify false if a port should not be included in the connection URL (i.e. for a public gateway like http://swarm-gateways.net).
dappConnection.getUrl	string	Only for IPFS. This sets the file/document retrieval URL, which is different than the host/port combination used to interact with the IPFS API.
versions	object	key-value hash of library and its desired version

Using a local node

Either for IPFS or Swarm, Embark will default to use a local node for development purposes. Note that we still need to set up the right port according to the storage platform we use. By default, IPFS runs on port 5001 and Swarm runs on 8500.

We can start a local storage node ourselves or now we can let Embark start the node for us. Letting Embark do the job lets us focus on developing faster while doing it ourselves might give us more flexibility. Obviously, we still need to have IPFS or Swarm installed locally for it to work.

Important configurations for swarm:

{
  "development": {
    "provider": "swarm",
    "account": {
      "address": "YOUR_ACCOUNT_ADDRESS",
      "password": "PATH/TO/PASSWORD/FILE"
    },
    "swarmPath": "PATH/TO/SWARM/EXECUTABLE"
  }
}

Using a public gateway

Embark can connect to a public gateway when using any of the available storage options. To use a public gateway, instead of running a local node, for IPFS or Swarm, use the following config/storage.js options:

IPFS

"development": {
  "enabled": true,
  "upload":{
    "provider": "ipfs",
    "host": "ipfs.infura.io",
    "port": 80,
    "protocol": "https",
    "getUrl": "https://ipfs.infura.io/ipfs/"
  }
}

Swarm

"development": {
  "enabled": true,
  "upload": {
    "provider": "swarm",
    "host": "localhost",
    "port": 8500
  }
}

Troubleshooting

If you are running your own processes for IPFS or Swarm, the CORS needs to be set to the domain of your application, to the geth domain, and to the domain of the storage used inside the application.

If you are using the built in webserver, the CORS would need to be set to http://localhost:8000, however if you are using embark upload, the domain of the decentralised storage host should be included in CORS.

Depending on your upload settings in storage.js, this could be http://localhost:8080 or http://ipfs.infura.io for IPFS or it could be http://localhost:8500 or http://swarm-gateways.net for Swarm.

Of course, if you are hosting your DApp on a different domain (i.e. not localhost, then that would need to be included in CORS as well. Examples of how to include multiple domains for each are below:

ipfs config --json API.HTTPHeaders.Access-Control-Allow-Origin "[\"http://localhost:8000\", \"http://localhost:8500\", \"http://localhost:8545\", \"ws://localhost:8546\"]"

NOTE: http://localhost:8545 and ws://localhost:8546 are for geth.

swarm --bzzaccount=fedda09fd9218d1ea4fd41ad44694fa4ccba1878 --datadir=~/.bzz-data/ --password=config/development/password --corsdomain=http://localhost:8000,http://localhost:8080,http://localhost:8545,ws://localhost:8546 --ens-api=''