You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
IPFS daemons are already easy to start and stop, but this module is here to do it from JavaScript itself.
32
53
54
+
### Spawn an IPFS daemon from Node.js
55
+
33
56
```js
34
57
// Start a disposable node, and get access to the api
35
-
// print the node id, and kill the temporary daemon
36
-
37
-
// IPFS_PATH will point to /tmp/ipfs_***** and will be
38
-
// cleaned up when the process exits.
58
+
// print the node id, and stop the temporary daemon
39
59
40
-
var ipfsd =require('ipfsd-ctl')
60
+
constDaemonFactory=require('ipfsd-ctl')
61
+
constdf=DaemonFactory.create()
41
62
42
-
ipfsd.disposableApi(function (err, ipfs) {
43
-
ipfs.id(function (err, id) {
63
+
df.spawn(function (err, ipfsd) {
64
+
if (err) { throw err }
65
+
66
+
ipfsd.api.id(function (err, id) {
67
+
if (err) { throw err }
68
+
44
69
console.log(id)
45
-
process.exit()
70
+
ipfsd.stop()
46
71
})
47
72
})
48
73
```
49
74
50
-
If you need want to use an existing ipfs installation you can set `$IPFS_EXEC=/path/to/ipfs` to ensure it uses that.
75
+
### Spawn an IPFS daemon from the Browser using the provided remote endpoint
76
+
77
+
```js
78
+
// Start a remote disposable node, and get access to the api
79
+
// print the node id, and stop the temporary daemon
80
+
81
+
constDaemonFactory=require('ipfsd-ctl')
82
+
83
+
constport=9999
84
+
constserver=DaemonFactory.createServer(port)
85
+
constdf=DaemonFactory.create({ remote:true, port: port })
86
+
87
+
server.start((err) => {
88
+
if (err) { throw err }
89
+
90
+
df.spawn((err, ipfsd) => {
91
+
if (err) { throw err }
92
+
93
+
ipfsd.api.id(function (err, id) {
94
+
if (err) { throw err }
95
+
96
+
console.log(id)
97
+
ipfsd.stop(server.stop)
98
+
})
99
+
})
100
+
})
101
+
```
102
+
103
+
## Disposable vs non Disposable nodes
104
+
105
+
`ipfsd-ctl` can create two types of node controllers, `disposable` and `non-disposable`. A disposable node will be created on a temporary repo which will be optionally initialized and started (the default), as well cleaned up on process exit. A non-disposable node on the other hand, 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 the `repoPath` option, if the `repoPath` is not defined, it will use the default repo for the node type (`$HOME/.ipfs` or `$HOME/.jsipfs`). The `repoPath` parameter is ignored for disposable nodes, as there is a risk of deleting a live repo.
106
+
107
+
## IPFS executables
108
+
109
+
`ipfsd-ctl` no longer installs go-ipfs nor js-ipfs dependencies, instead it expects them to be provided by the parent project. In order to be able to use both go and js daemons, please make sure that your project includes these two npm packages as dependencies.
110
+
111
+
-`ipfs` - the js-ipfs implementation
112
+
-`go-ipfs-dep` - the packaged go-ipfs implementation
`DaemonFactory.create([options])` returns an object that will expose the `df.spawn` method
121
+
122
+
-`options` - an optional object with the following properties
123
+
-`remote` bool - indicates if the factory should spawn local or remote nodes. By default, local nodes are spawned in Node.js and remote nodes are spawned in Browser environments.
124
+
-`port` number - the port number to use for the remote factory. It should match the port on which `DaemonFactory.server` was started. Defaults to 9999.
125
+
-`type` - the daemon type to create with this factory. See the section bellow for the supported types
126
+
-`exec` - path to the desired IPFS executable to spawn, otherwise `ipfsd-ctl` will try to locate the correct one based on the `type`. In the case of `proc` type, exec is required and expects an IPFS coderef.
127
+
128
+
`ipfsd-ctl` allows spawning different IPFS implementations, such as:
129
+
130
+
-**`go`** - calling `DaemonFactory.create({type: 'go'})` will spawn a `go-ipfs` daemon.
131
+
-**`js`** - calling `DaemonFactory.create({type: 'js'})` will spawn a `js-ipfs` daemon.
132
+
-**`proc`** - calling `DaemonFactory.create({type: 'proc', exec: require('ipfs') })` will spawn an `in process js-ipfs node` using the provided code reference that implements the core IPFS API. Note that, `exec` option to `df.spawn()` is required if `type: 'proc'` is used.
133
+
134
+
#### DaemonFactory endpoint for remote spawning - `const server = `DaemonFactory.createServer([options]) `
135
+
136
+
`DaemonFactory.createServer` create an instance of the bundled REST API used by the remote controller.
137
+
138
+
- exposes `start` and `stop` methods to start and stop the http server endpoint.
139
+
140
+
#### Spawn a new daemon with `df.spawn`
141
+
142
+
Spawn either a js-ipfs or go-ipfs daemon
143
+
144
+
`df.spawn([options], callback)`
145
+
146
+
`options` is an optional object the following properties:
147
+
-`init` bool (default true) - should the node be initialized
148
+
-`start` bool (default true) - should the node be started
149
+
-`repoPath` string - the repository path to use for this node, ignored if node is disposable
150
+
-`disposable` bool (default false) - a new repo is created and initialized for each invocation, as well as cleaned up automatically once the process exits
151
+
-`args` - array of cmd line arguments to be passed to ipfs daemon
152
+
-`config` - ipfs configuration options
153
+
154
+
`callback` - is a function with the signature `function (err, ipfsd)` where:
155
+
-`err` - is the error set if spawning the node is unsuccessful
156
+
-`ipfsd` - is the daemon controller instance:
157
+
-`api` - a property of `ipfsd`, an instance of [ipfs-api](https://github.com/ipfs/js-ipfs-api) attached to the newly created ipfs node
158
+
159
+
### IPFS Daemon Controller (`ipfsd`)
160
+
161
+
The IPFS daemon controller (`ipfsd`) allows you to interact with the spawned IPFS daemon.
162
+
163
+
#### `ipfsd.apiAddr` (getter)
164
+
165
+
Get the address (multiaddr) of connected IPFS API. Returns a multiaddr
166
+
167
+
#### `ipfsd.gatewayAddr` (getter)
51
168
52
-
For more details see https://ipfs.github.io/js-ipfsd-ctl/.
169
+
Get the address (multiaddr) of connected IPFS HTTP Gateway. Returns a multiaddr.
53
170
171
+
#### `ipfsd.repoPath` (getter)
172
+
173
+
Get the current repo path. Returns string.
174
+
175
+
#### `ipfsd.started` (getter)
176
+
177
+
Is the node started. Returns a boolean.
178
+
179
+
#### `init([initOpts], callback)`
180
+
181
+
Initialize a repo.
182
+
183
+
`initOpts` (optional) is an object with the following properties:
184
+
-`keysize` (default 2048) - The bit size of the identity key.
185
+
-`directory` (default IPFS_PATH if defined, or ~/.ipfs for go-ipfs and ~/.jsipfs for js-ipfs) - The location of the repo.
186
+
187
+
`callback` is a function with the signature `function (Error, ipfsd)` where `err` is an Error in case something goes wrong and `ipfsd` is the daemon controller instance.
188
+
189
+
#### `ipfsd.cleanup(callback)`
190
+
191
+
Delete the repo that was being used. If the node was marked as `disposable` this will be called automatically when the process is exited.
192
+
193
+
`callback` is a function with the signature `function(err)`.
194
+
195
+
#### `ipfsd.start(flags, callback)`
196
+
197
+
Start the daemon.
198
+
199
+
`flags` - Flags array to be passed to the `ipfs daemon` command.
200
+
201
+
`callback` is a function with the signature `function(err, ipfsApi)` that receives an instance of `ipfs-api` on success or an instance of `Error` on failure
202
+
203
+
204
+
#### `ipfsd.stop([callback])`
205
+
206
+
Stop the daemon.
207
+
208
+
`callback` is a function with the signature `function(err)` callback - function that receives an instance of `Error` on failure
209
+
210
+
#### `ipfsd.killProcess([callback])`
211
+
212
+
Kill the `ipfs daemon` process.
213
+
214
+
First a `SIGTERM` is sent, after 10.5 seconds `SIGKILL` is sent if the process hasn't exited yet.
215
+
216
+
`callback` is a function with the signature `function()` called once the process is killed
217
+
218
+
#### `ipfsd.pid()`
219
+
220
+
Get the pid of the `ipfs daemon` process. Returns the pid number
221
+
222
+
#### `ipfsd.getConfig([key], callback)`
223
+
224
+
Returns the output of an `ipfs config` command. If no `key` is passed, the whole config is returned as an object.
225
+
226
+
`key` (optional) - A specific config to retrieve.
227
+
228
+
`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
229
+
230
+
#### `ipfsd.setConfig(key, value, callback)`
231
+
232
+
Set a config value.
233
+
234
+
`key` - the key of the config entry to change/set
235
+
236
+
`value` - the config value to change/set
237
+
238
+
`callback` is a function with the signature `function(err)` callback - function that receives an `Error` instance on failure
239
+
240
+
#### `ipfsd.version(callback)`
241
+
242
+
Get the version of ipfs
243
+
244
+
`callback` is a function with the signature `function(err, version)`
245
+
246
+
### IPFS Client (`ipfsd.api`)
247
+
248
+
An instance of [ipfs-api](https://github.com/ipfs/js-ipfs-api#api) that is used to interact with the daemon.
249
+
250
+
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})`.
251
+
54
252
### Packaging
55
253
56
-
`ipfsd-ctl` can be packaged in Electron applications, but the ipfs binary
57
-
has to be excluded from asar (Electron Archives),
254
+
`ipfsd-ctl` can be packaged in Electron applications, but the ipfs binary has to be excluded from asar (Electron Archives).
58
255
[read more about unpack files from asar](https://electron.atom.io/docs/tutorial/application-packaging/#adding-unpacked-files-in-asar-archive).
59
-
`ipfsd-ctl` will try to detect if used from within an `app.asar` archive
60
-
and tries to resolve ipfs from `app.asar.unpacked`. The ipfs binary is part of
61
-
the `go-ipfs-dep` module.
256
+
257
+
`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.
0 commit comments