Spawn IPFS daemons using JavaScript!
npm install --save ipfsd-ctl
Spawn an IPFS daemon from Node.js
// Start a disposable node, and get access to the api
// print the node id, and stop the temporary daemon
const IPFSFactory = require('ipfsd-ctl')
const f = IPFSFactory.create()
f.spawn(function (err, ipfsd) {
if (err) { throw err }
ipfsd.api.id(function (err, id) {
if (err) { throw err }
console.log(id)
ipfsd.stop()
})
})
Spawn an IPFS daemon from the Browser using the provided remote endpoint
// Start a remote disposable node, and get access to the api
// print the node id, and stop the temporary daemon
const IPFSFactory = require('ipfsd-ctl')
const port = 9090
const server = IPFSFactory.createServer(port)
const f = IPFSFactory.create({ remote: true, port: port })
server.start((err) => {
if (err) { throw err }
f.spawn((err, ipfsd) => {
if (err) { throw err }
ipfsd.api.id(function (err, id) {
if (err) { throw err }
console.log(id)
ipfsd.stop(server.stop)
})
})
})
ipfsd-ctl
can spawn disposable
and non-disposable
daemons.
disposable
- Creates on a temporary repo which will be optionally initialized and started (the default), as well cleaned up on process exit. Great for tests.non-disposable
- Requires the user to initialize and start the node, as well as stop and cleanup after wards. Additionally, a non-disposable will allow you to pass a custom repo using therepoPath
option, if therepoPath
is not defined, it will use the default repo for the node type ($HOME/.ipfs
or$HOME/.jsipfs
). TherepoPath
parameter is ignored for disposable nodes, as there is a risk of deleting a live repo.
Install one or both of the following modules:
ipfs
-> npm i ipfs
- If you want to spawn js-ipfs nodes and/or daemons.go-ipfs-dep
-> npm i go-ipfs-dep
- If you want to spwan go-ipfs daemons.
IPFSFactory.create([options])
returns an object that will expose the df.spawn
method
options
- optional object with:remote
bool - use remote endpoint to spawn the nodes.port
number - remote endpoint point. Defaults to 43134.exec
- IPFS executable path.ipfsd-ctl
will attempt to locate it by default. If you desire to spawn js-ipfs instances in the same process, pass the ref to the module instead (e.gexec: require('ipfs')
)type
- the daemon type, see below the optionsgo
- spawn go-ipfs daemonjs
- spawn js-ipfs daemonproc
- spawn in-process js-ipfs instance. Needs to be called also with exec. Example:DaemonFactory.create({type: 'proc', exec: require('ipfs') })
.
IpfsApi
- A custom IPFS API constructor to use instead of the packaged one
example: See Usage
Spawn the daemon
-
options
is an optional object the following properties:init
bool (default true) or Object - should the node be initializedinitOptions
object - should be of the form{bits: <size>}
, which sets the desired key sizestart
bool (default true) - should the node be startedrepoPath
string - the repository path to use for this node, ignored if node is disposabledisposable
bool (default true) - a new repo is created and initialized for each invocation, as well as cleaned up automatically once the process exitsdefaultAddrs
bool (default false) - use the daemon defaultSwarm
addrsargs
- array of cmd line arguments to be passed to ipfs daemonconfig
- ipfs configuration options
-
callback
- is a function with the signaturefunction (err, ipfsd)
where:err
- is the error set if spawning the node is unsuccessfulipfsd
- is the daemon controller instance:api
- a property ofipfsd
, an instance of ipfs-api attached to the newly created ipfs node
example: See Usage
Get the version without spawning a daemon
callback
- is a function with the signaturefunction(err, version)
, where version might be one of the following:- if
type
is 'go' a version string likeipfs version <version number>
- if
type
is 'js' a version string likejs-ipfs version: <version number>
- if
type
is 'proc' an object with the following properties:- version - the ipfs version
- repo - the repo version
- commit - the commit hash for this version
- if
IPFSFactory.createServer
starts a IPFSFactory endpoint.
options
is an optional object the following properties:port
- the port to start the server on
example:
const IPFSFactory = require('ipfsd-ctl')
const server = IPFSFactory.createServer({ port: 12345 })
server.start((err) => {
if (err) { throw err }
console.log('endpoint is running')
server.stop((err) => {
if (err) { throw err }
console.log('endpoint has stopped')
})
})
The IPFS daemon controller (ipfsd
) allows you to interact with the spawned IPFS daemon.
Get the address (multiaddr) of connected IPFS API. Returns a multiaddr
Get the address (multiaddr) of connected IPFS HTTP Gateway. Returns a multiaddr.
Get the current repo path. Returns string.
Is the node started. Returns a boolean.
Initialize a repo.
initOpts
(optional) is an object with the following properties:
keysize
(default 2048) - The bit size of the identity key.directory
(default IPFS_PATH if defined, or ~/.ipfs for go-ipfs and ~/.jsipfs for js-ipfs) - The location of the repo.pass
(optional) - The passphrase of the key chain.
callback
is a function with the signature function (err, ipfsd)
where err
is an Error in case something goes wrong and ipfsd
is the daemon controller instance.
Delete the repo that was being used. If the node was marked as disposable
this will be called automatically when the process is exited.
callback
is a function with the signature function(err)
.
Start the daemon.
flags
- Flags array to be passed to the ipfs daemon
command.
callback
is a function with the signature function(err, ipfsApi)
that receives an instance of Error
on failure or an instance of ipfs-api
on success.
Stop the daemon.
callback
is a function with the signature function(err)
callback - function that receives an instance of Error
on failure. Use timeout to specify the grace period in ms before hard stopping the daemon. Otherwise, a grace period of 10500
ms will be used for disposable nodes and 10500 * 3
ms for non disposable nodes.
Kill the ipfs daemon
process. Use timeout to specify the grace period in ms before hard stopping the daemon. Otherwise, a grace period of 10500
ms will be used for disposable nodes and 10500 * 3
ms for non disposable nodes.
Note: timeout is ignored for proc
nodes
First a SIGTERM
is sent, after 10.5 seconds SIGKILL
is sent if the process hasn't exited yet.
callback
is a function with the signature function()
called once the process is killed
Get the pid of the ipfs daemon
process. Returns the pid number
callback
is a function with the signature function(err, pid)
that receives the pid
of the running daemon or an Error
instance on failure
Returns the output of an ipfs config
command. If no key
is passed, the whole config is returned as an object.
key
(optional) - A specific config to retrieve.
callback
is a function with the signature function(err, (Object|string))
that receives an object or string on success or an Error
instance on failure
Set a config value.
key
- the key of the config entry to change/set
value
- the config value to change/set
callback
is a function with the signature function(err)
callback - function that receives an Error
instance on failure
Get the version of ipfs
callback
is a function with the signature function(err, version)
An instance of ipfs-api that is used to interact with the daemon.
This instance is returned for each successfully started IPFS daemon, when either df.spawn({start: true})
(the default) is called, or ipfsd.start()
is invoked in the case of nodes that were spawned with df.spawn({start: false})
.
In additional to the API described in previous sections, ipfsd-ctl
also supports several environment variables. This are often very useful when running in different environments, such as CI or when doing integration/interop testing.
Environment variables precedence order is as follows. Top to bottom, top entry has highest precedence:
- command line options/method arguments
- env variables
- default values
Meaning that, environment variables override defaults in the configuration file but are superseded by options to df.spawn({...})
An alternative way of specifying the executable path for the js-ipfs
or go-ipfs
executable, respectively.
ipfsd-ctl
can be packaged in Electron applications, but the ipfs binary has to be excluded from asar (Electron Archives).
read more about unpack files from asar.
ipfsd-ctl
will try to detect if used from within an app.asar
archive and tries to resolve ipfs from app.asar.unpacked
. The ipfs binary is part of the go-ipfs-dep
module.
electron-packager ./ --asar.unpackDir=node_modules/go-ipfs-dep
Project structure:
src
├── defaults
│ ├── config.json
│ └── options.json
├── endpoint # endpoint to support remote spawning
│ ├── routes.js
│ └── server.js
├── factory-client.js # IPFS Factories: client (remote), daemon (go or js) and in-proc (js)
├── factory-daemon.js
├── factory-in-proc.js
├── index.js
├── ipfsd-client.js # ipfsd (Daemon Controller): client (remote), daemon (go or js), in-proc (js)
├── ipfsd-daemon.js
├── ipfsd-in-proc.js
└── utils # Utils used by the Factories and Daemon Controllers
├── configure-node.js
├── exec.js
├── find-ipfs-executable.js
├── flatten.js
├── parse-config.js
├── repo
│ ├── create-browser.js
│ └── create-nodejs.js
├── run.js
├── set-config-value.js
└── tmp-dir.js
4 directories, 21 files
Feel free to join in. All welcome. Open an issue!
This repository falls under the IPFS Code of Conduct.