mirror of
https://github.com/ipfs/kubo.git
synced 2026-02-21 10:27:46 +08:00
refactor: kubo in ./docs
This commit is contained in:
Marcin Rataj
parent
91e6451419
commit
8565bbb75c
@ -2,7 +2,7 @@
|
||||
|
||||
## What is it?
|
||||
|
||||
The early testers programme allows groups using go-ipfs in production to self-volunteer to help test `go-ipfs` release candidates to ensure that no regressions that might affect production systems make it into the final release. While we invite the _entire_ community to help test releases, members of the early testers program are expected to participate directly and actively in every release.
|
||||
The early testers programme allows groups using Kubo in production to self-volunteer to help test `kubo` release candidates to ensure that no regressions that might affect production systems make it into the final release. While we invite the _entire_ community to help test releases, members of the early testers program are expected to participate directly and actively in every release.
|
||||
|
||||
## What are the expectations?
|
||||
|
||||
@ -14,11 +14,11 @@ Members of the early tester program are expected to work closely with us to:
|
||||
|
||||
We will ask early testers to participate at two points in the process:
|
||||
|
||||
* When go-ipfs enters the second release stage (public beta), early testers will be asked to test go-ipfs on non-production infrastructure. This may involve things like:
|
||||
* When Kubo enters the second release stage (public beta), early testers will be asked to test Kubo on non-production infrastructure. This may involve things like:
|
||||
- Running integration tests against the release candidate.
|
||||
- Running simulations/benchmarks on the release candidate.
|
||||
- Manually testing the release candidate to check for regressions.
|
||||
* When go-ipfs enters the third release stage (soft release), early testers will be asked to partially deploy the release candidate to production infrastructure. Release candidates at this stage are expected to be identical to the final release. However, this stage allows the go-ipfs team to fix any last-minute regressions without cutting an entirely new release.
|
||||
* When Kubo enters the third release stage (soft release), early testers will be asked to partially deploy the release candidate to production infrastructure. Release candidates at this stage are expected to be identical to the final release. However, this stage allows the Kubo team to fix any last-minute regressions without cutting an entirely new release.
|
||||
|
||||
## Who has signed up?
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Patch Release Checklist
|
||||
|
||||
This process handles patch releases from version `vX.Y.Z` to `vX.Y.Z+1` assuming that `vX.Y.Z` is the latest released version of go-ipfs.
|
||||
This process handles patch releases from version `vX.Y.Z` to `vX.Y.Z+1` assuming that `vX.Y.Z` is the latest released version of Kubo.
|
||||
|
||||
- [ ] Get temporary permissions to force-push to `release-*` branches
|
||||
- [ ] Fork a new branch (`release-vX.Y.Z`) from `release` and cherry-pick the relevant commits from master (or custom fixes) onto this branch
|
||||
@ -15,7 +15,7 @@ This process handles patch releases from version `vX.Y.Z` to `vX.Y.Z+1` assuming
|
||||
2. Pin the resulting release.
|
||||
3. Make a PR against ipfs/distributions with the updated versions, including the new hash in the PR comment.
|
||||
4. Ask the infra team to update the DNSLink record for dist.ipfs.io to point to the new distribution.
|
||||
- [ ] cut a release on [github](https://github.com/ipfs/go-ipfs/releases) and upload the result of the ipfs/distributions build in the previous step.
|
||||
- [ ] cut a release on [github](https://github.com/ipfs/kubo/releases) and upload the result of the ipfs/distributions build in the previous step.
|
||||
- Announce the Release:
|
||||
- [ ] On IRC/Matrix (both #ipfs and #ipfs-dev)
|
||||
- [ ] On discuss.ipfs.io
|
||||
@ -24,7 +24,7 @@ This process handles patch releases from version `vX.Y.Z` to `vX.Y.Z+1` assuming
|
||||
- [ ] to [npm-go-ipfs](https://github.com/ipfs/npm-go-ipfs)
|
||||
- [ ] to [chocolatey](https://chocolatey.org/packages/ipfs)
|
||||
- [ ] to [snap](https://snapcraft.io/ipfs)
|
||||
- [ ] to [github](https://github.com/ipfs/go-ipfs/releases)
|
||||
- [ ] to [github](https://github.com/ipfs/kubo/releases)
|
||||
- [ ] to [arch](https://www.archlinux.org/packages/community/x86_64/go-ipfs/) (flag it out of date)
|
||||
- [ ] Cut a new ipfs-desktop release
|
||||
- [ ] Merge the `release` branch back into `master`, ignoring the changes to `version.go` (keep the `-dev` version from master).
|
||||
|
||||
@ -6,9 +6,9 @@ If you’re experiencing an issue with IPFS, **please follow [our issue guide](g
|
||||
|
||||
Otherwise, check out the following guides to using and developing IPFS:
|
||||
|
||||
## Developing `go-ipfs`
|
||||
## Developing `kubo`
|
||||
|
||||
- First, please read the Contributing Guidelines [for IPFS projects](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) and then the Contributing Guidelines for [go-ipfs specifically](https://github.com/ipfs/community/blob/master/CONTRIBUTING_GO.md)
|
||||
- First, please read the Contributing Guidelines [for IPFS projects](https://github.com/ipfs/community/blob/master/CONTRIBUTING.md) and then the Contributing Guidelines for [Go code specifically](https://github.com/ipfs/community/blob/master/CONTRIBUTING_GO.md)
|
||||
- Building on…
|
||||
- [Windows](windows.md)
|
||||
- [Performance Debugging Guidelines](debug-guide.md)
|
||||
@ -17,7 +17,7 @@ Otherwise, check out the following guides to using and developing IPFS:
|
||||
## Guides
|
||||
|
||||
- [How to Implement an API Client](implement-api-bindings.md)
|
||||
- [Connecting with Websockets](transports.md) — if you want `js-ipfs` nodes in web browsers to connect to your `go-ipfs` node, you will need to turn on websocket support in your `go-ipfs` node.
|
||||
- [Connecting with Websockets](transports.md) — if you want `js-ipfs` nodes in web browsers to connect to your `kubo` node, you will need to turn on websocket support in your `kubo` node.
|
||||
|
||||
## Advanced User Guides
|
||||
|
||||
@ -28,7 +28,7 @@ Otherwise, check out the following guides to using and developing IPFS:
|
||||
- [Installing command completion](command-completion.md)
|
||||
- [Mounting IPFS with FUSE](fuse.md)
|
||||
- [Installing plugins](plugins.md)
|
||||
- [Setting up an IPFS Gateway](https://github.com/ipfs/go-ipfs/blob/master/docs/gateway.md)
|
||||
- [Setting up an IPFS Gateway](https://github.com/ipfs/kubo/blob/master/docs/gateway.md)
|
||||
|
||||
## Other
|
||||
|
||||
|
||||
@ -1,8 +1,8 @@
|
||||
> Release Issue Template
|
||||
|
||||
# go-ipfs X.Y.Z Release
|
||||
# Kubo X.Y.Z Release
|
||||
|
||||
We're happy to announce go-ipfs X.Y.Z, bla bla...
|
||||
We're happy to announce Kubo X.Y.Z, bla bla...
|
||||
|
||||
As usual, this release includes important fixes, some of which may be critical for security. Unless the fix addresses a bug being exploited in the wild, the fix will _not_ be called out in the release notes. Please make sure to update ASAP. See our [release process](https://github.com/ipfs/go-ipfs/tree/master/docs/releases.md#security-fix-policy) for details.
|
||||
|
||||
@ -29,7 +29,7 @@ For each RC published in each stage:
|
||||
2. Pin the resulting release.
|
||||
3. Make a PR against ipfs/distributions with the updated versions, including the new hash in the PR comment.
|
||||
4. Ask the infra team to update the DNSLink record for dist.ipfs.io to point to the new distribution.
|
||||
- cut a pre-release on [github](https://github.com/ipfs/go-ipfs/releases) and upload the result of the ipfs/distributions build in the previous step.
|
||||
- cut a pre-release on [github](https://github.com/ipfs/kubo/releases) and upload the result of the ipfs/distributions build in the previous step.
|
||||
- Announce the RC:
|
||||
- [ ] On Matrix (both #ipfs and #ipfs-dev)
|
||||
- [ ] To the _early testers_ listed in [docs/EARLY_TESTERS.md](https://github.com/ipfs/go-ipfs/tree/master/docs/EARLY_TESTERS.md). Do this by copy/pasting their GitHub usernames and checkboxes as a comment so they get a GitHub notification. ([example](https://github.com/ipfs/go-ipfs/issues/8176#issuecomment-909356394))
|
||||
@ -40,7 +40,7 @@ Checklist:
|
||||
- [ ] Upgrade to the latest patch release of Go that CircleCI has published
|
||||
- [ ] See the list here: https://hub.docker.com/r/cimg/go/tags
|
||||
- [ ] [ipfs/distributions](https://github.com/ipfs/distributions): bump [this version](https://github.com/ipfs/distributions/blob/master/.tool-versions#L2)
|
||||
- [ ] [ipfs/go-ipfs](https://github.com/ipfs/go-ipfs): [example PR](https://github.com/ipfs/go-ipfs/pull/8599)
|
||||
- [ ] [ipfs/kubo](https://github.com/ipfs/kubo): [example PR](https://github.com/ipfs/kubo/pull/8599)
|
||||
- [ ] Fork a new branch (`release-vX.Y.Z`) from `master` and make any further release related changes to this branch. If any "non-trivial" changes (see the footnotes of [docs/releases.md](https://github.com/ipfs/go-ipfs/tree/master/docs/releases.md) for a definition) get added to the release, uncheck all the checkboxes and return to this stage.
|
||||
- [ ] Follow the RC release process to cut the first RC.
|
||||
- [ ] Bump the version in `version.go` in the `master` branch to `vX.(Y+1).0-dev`.
|
||||
@ -85,7 +85,7 @@ Checklist:
|
||||
- [ ] Manually run [the release workflow](https://github.com/ipfs/choco-go-ipfs/actions/workflows/main.yml)
|
||||
- [ ] to [snap](https://snapcraft.io/ipfs)
|
||||
- [ ] to [github](https://github.com/ipfs/go-ipfs/releases)
|
||||
- [ ] use the artifacts built in CI for dist.ipfs.io: `wget "https://ipfs.io/api/v0/get?arg=/ipns/dist.ipfs.io/go-ipfs/$(curl -s https://dist.ipfs.io/go-ipfs/versions | tail -n 1)"`
|
||||
- [ ] use the artifacts built in CI for dist.ipfs.io: `wget "https://ipfs.io/api/v0/get?arg=/ipns/dist.ipfs.io/kubo/$(curl -s https://dist.ipfs.io/kubo/versions | tail -n 1)"`
|
||||
- [ ] to [arch](https://www.archlinux.org/packages/community/x86_64/go-ipfs/) (flag it out of date)
|
||||
- [ ] Cut a new ipfs-desktop release
|
||||
- [ ] Submit [this form](https://airtable.com/shrNH8YWole1xc70I) to publish a blog post, linking to the GitHub release notes
|
||||
@ -124,7 +124,7 @@ The best place to ask your questions about IPFS, how it works and what you can d
|
||||
|
||||
Would you like to contribute to the IPFS project and don't know how? Well, there are a few places you can get started:
|
||||
|
||||
- Check the issues with the `help wanted` label in the [go-ipfs repo](https://github.com/ipfs/go-ipfs/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)
|
||||
- Check the issues with the `help wanted` label in the [ipfs/kubo repo](https://github.com/ipfs/kubo/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)
|
||||
- Join an IPFS All Hands, introduce yourself and let us know where you would like to contribute - https://github.com/ipfs/team-mgmt/#weekly-ipfs-all-hands
|
||||
- Hack with IPFS and show us what you made! The All Hands call is also the perfect venue for demos, join in and show us what you built
|
||||
- Join the discussion at [discuss.ipfs.io](https://discuss.ipfs.io/) and help users finding their answers.
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
# The go-ipfs config file
|
||||
# The Kubo config file
|
||||
|
||||
The go-ipfs config file is a JSON document located at `$IPFS_PATH/config`. It
|
||||
The Kubo (go-ipfs) config file is a JSON document located at `$IPFS_PATH/config`. It
|
||||
is read once at node instantiation, either for an offline command, or when
|
||||
starting the daemon. Commands that execute on a running daemon do not read the
|
||||
config file at runtime.
|
||||
|
||||
# Table of Contents
|
||||
|
||||
- [The go-ipfs config file](#the-go-ipfs-config-file)
|
||||
- [The Kubo config file](#the-kubo-config-file)
|
||||
- [Table of Contents](#table-of-contents)
|
||||
- [Profiles](#profiles)
|
||||
- [Types](#types)
|
||||
@ -245,7 +245,7 @@ This document refers to the standard JSON types (e.g., `null`, `string`,
|
||||
|
||||
Flags allow enabling and disabling features. However, unlike simple booleans,
|
||||
they can also be `null` (or omitted) to indicate that the default value should
|
||||
be chosen. This makes it easier for go-ipfs to change the defaults in the
|
||||
be chosen. This makes it easier for Kubo to change the defaults in the
|
||||
future unless the user _explicitly_ sets the flag to either `true` (enabled) or
|
||||
`false` (disabled). Flags have three possible states:
|
||||
|
||||
@ -281,7 +281,7 @@ does (e.g, `"1d2h4m40.01s"`).
|
||||
Optional integers allow specifying some numerical value which has
|
||||
an implicit default when missing from the config file:
|
||||
|
||||
- `null`/missing will apply the default value defined in go-ipfs sources (`.WithDefault(value)`)
|
||||
- `null`/missing will apply the default value defined in Kubo sources (`.WithDefault(value)`)
|
||||
- an integer between `-2^63` and `2^63-1` (i.e. `-9223372036854775808` to `9223372036854775807`)
|
||||
|
||||
### `optionalBytes`
|
||||
@ -289,7 +289,7 @@ an implicit default when missing from the config file:
|
||||
Optional Bytes allow specifying some number of bytes which has
|
||||
an implicit default when missing from the config file:
|
||||
|
||||
- `null`/missing (apply the default value defined in go-ipfs sources)
|
||||
- `null`/missing (apply the default value defined in Kubo sources)
|
||||
- a string value indicating the number of bytes, including human readable representations:
|
||||
- [SI sizes](https://en.wikipedia.org/wiki/Metric_prefix#List_of_SI_prefixes) (metric units, powers of 1000), e.g. `1B`, `2kB`, `3MB`, `4GB`, `5TB`, …)
|
||||
- [IEC sizes](https://en.wikipedia.org/wiki/Binary_prefix#IEC_prefixes) (binary units, powers of 1024), e.g. `1B`, `2KiB`, `3MiB`, `4GiB`, `5TiB`, …)
|
||||
@ -299,7 +299,7 @@ an implicit default when missing from the config file:
|
||||
Optional strings allow specifying some string value which has
|
||||
an implicit default when missing from the config file:
|
||||
|
||||
- `null`/missing will apply the default value defined in go-ipfs sources (`.WithDefault("value")`)
|
||||
- `null`/missing will apply the default value defined in Kubo sources (`.WithDefault("value")`)
|
||||
- a string
|
||||
|
||||
### `optionalDuration`
|
||||
@ -307,7 +307,7 @@ an implicit default when missing from the config file:
|
||||
Optional durations allow specifying some duration value which has
|
||||
an implicit default when missing from the config file:
|
||||
|
||||
- `null`/missing will apply the default value defined in go-ipfs sources (`.WithDefault("1h2m3s")`)
|
||||
- `null`/missing will apply the default value defined in Kubo sources (`.WithDefault("1h2m3s")`)
|
||||
- a string with a valid [go duration](#duration) (e.g, `"1d2h4m40.01s"`).
|
||||
|
||||
## `Addresses`
|
||||
@ -431,7 +431,7 @@ Type: `string` (one of `"enabled"` or `"disabled"`)
|
||||
### `AutoNAT.Throttle`
|
||||
|
||||
When set, this option configure's the AutoNAT services throttling behavior. By
|
||||
default, go-ipfs will rate-limit the number of NAT checks performed for other
|
||||
default, Kubo will rate-limit the number of NAT checks performed for other
|
||||
nodes to 30 per minute, and 3 per peer.
|
||||
|
||||
### `AutoNAT.Throttle.GlobalLimit`
|
||||
@ -671,7 +671,7 @@ Type: `bool`
|
||||
|
||||
### `Gateway.PathPrefixes`
|
||||
|
||||
**DEPRECATED:** see [go-ipfs#7702](https://github.com/ipfs/go-ipfs/issues/7702)
|
||||
**DEPRECATED:** see [kubo#7702](https://github.com/ipfs/kubo/issues/7702)
|
||||
|
||||
<!--
|
||||
An array of acceptable url paths that a client can specify in X-Ipfs-Path-Prefix
|
||||
@ -830,7 +830,7 @@ Below is a list of the most common public gateway setups.
|
||||
|
||||
`http://dweb.link/ipfs/{cid}` → `http://{cid}.ipfs.dweb.link`
|
||||
|
||||
- **X-Forwarded-Proto:** if you run go-ipfs behind a reverse proxy that provides TLS, make it add a `X-Forwarded-Proto: https` HTTP header to ensure users are redirected to `https://`, not `http://`. It will also ensure DNSLink names are inlined to fit in a single DNS label, so they work fine with a wildcart TLS cert ([details](https://github.com/ipfs/in-web-browsers/issues/169)). The NGINX directive is `proxy_set_header X-Forwarded-Proto "https";`.:
|
||||
- **X-Forwarded-Proto:** if you run Kubo behind a reverse proxy that provides TLS, make it add a `X-Forwarded-Proto: https` HTTP header to ensure users are redirected to `https://`, not `http://`. It will also ensure DNSLink names are inlined to fit in a single DNS label, so they work fine with a wildcart TLS cert ([details](https://github.com/ipfs/in-web-browsers/issues/169)). The NGINX directive is `proxy_set_header X-Forwarded-Proto "https";`.:
|
||||
|
||||
`http://dweb.link/ipfs/{cid}` → `https://{cid}.ipfs.dweb.link`
|
||||
|
||||
@ -892,7 +892,7 @@ Type: `string` (base64 encoded)
|
||||
|
||||
## `Internal`
|
||||
|
||||
This section includes internal knobs for various subsystems to allow advanced users with big or private infrastructures to fine-tune some behaviors without the need to recompile go-ipfs.
|
||||
This section includes internal knobs for various subsystems to allow advanced users with big or private infrastructures to fine-tune some behaviors without the need to recompile Kubo.
|
||||
|
||||
**Be aware that making informed change here requires in-depth knowledge and most users should leave these untouched. All knobs listed here are subject to breaking changes between versions.**
|
||||
|
||||
@ -1193,7 +1193,7 @@ Type: `bool`
|
||||
|
||||
## `Peering`
|
||||
|
||||
Configures the peering subsystem. The peering subsystem configures go-ipfs to
|
||||
Configures the peering subsystem. The peering subsystem configures Kubo to
|
||||
connect to, remain connected to, and reconnect to a set of nodes. Nodes should
|
||||
use this subsystem to create "sticky" links between frequently useful peers to
|
||||
improve reliability.
|
||||
@ -1202,15 +1202,15 @@ Use-cases:
|
||||
|
||||
* An IPFS gateway connected to an IPFS cluster should peer to ensure that the
|
||||
gateway can always fetch content from the cluster.
|
||||
* A dapp may peer embedded go-ipfs nodes with a set of pinning services or
|
||||
* A dapp may peer embedded Kubo nodes with a set of pinning services or
|
||||
textile cafes/hubs.
|
||||
* A set of friends may peer to ensure that they can always fetch each other's
|
||||
content.
|
||||
|
||||
When a node is added to the set of peered nodes, go-ipfs will:
|
||||
When a node is added to the set of peered nodes, Kubo will:
|
||||
|
||||
1. Protect connections to this node from the connection manager. That is,
|
||||
go-ipfs will never automatically close the connection to this node and
|
||||
Kubo will never automatically close the connection to this node and
|
||||
connections to this node will not count towards the connection limit.
|
||||
2. Connect to this node on startup.
|
||||
3. Repeatedly try to reconnect to this node if the last connection dies or the
|
||||
@ -1366,10 +1366,10 @@ Type: `bool`
|
||||
|
||||
Disable automatic NAT port forwarding.
|
||||
|
||||
When not disabled (default), go-ipfs asks NAT devices (e.g., routers), to open
|
||||
up an external port and forward it to the port go-ipfs is running on. When this
|
||||
When not disabled (default), Kubo asks NAT devices (e.g., routers), to open
|
||||
up an external port and forward it to the port Kubo is running on. When this
|
||||
works (i.e., when your router supports NAT port forwarding), it makes the local
|
||||
go-ipfs node accessible from the public internet.
|
||||
Kubo node accessible from the public internet.
|
||||
|
||||
Default: `false`
|
||||
|
||||
@ -1380,7 +1380,7 @@ Type: `bool`
|
||||
Enable hole punching for NAT traversal
|
||||
when port forwarding is not possible.
|
||||
|
||||
When enabled, go-ipfs will coordinate with the counterparty using
|
||||
When enabled, Kubo will coordinate with the counterparty using
|
||||
a [relayed connection](https://github.com/libp2p/specs/blob/master/relay/circuit-v2.md),
|
||||
to [upgrade to a direct connection](https://github.com/libp2p/specs/blob/master/relay/DCUtR.md)
|
||||
through a NAT/firewall whenever possible.
|
||||
@ -1553,7 +1553,7 @@ Please use [`AutoNAT.ServiceMode`][#autonatservicemode].
|
||||
### `Swarm.ConnMgr`
|
||||
|
||||
The connection manager determines which and how many connections to keep and can
|
||||
be configured to keep. Go-ipfs currently supports two connection managers:
|
||||
be configured to keep. Kubo currently supports two connection managers:
|
||||
|
||||
* none: never close idle connections.
|
||||
* basic: the default connection manager.
|
||||
@ -1709,7 +1709,7 @@ Each field in this section is a `flag`.
|
||||
#### `Swarm.Transports.Network.TCP`
|
||||
|
||||
[TCP](https://en.wikipedia.org/wiki/Transmission_Control_Protocol) is the most
|
||||
widely used transport by go-ipfs nodes. It doesn't directly support encryption
|
||||
widely used transport by Kubo nodes. It doesn't directly support encryption
|
||||
and/or multiplexing, so libp2p will layer a security & multiplexing transport
|
||||
over it.
|
||||
|
||||
@ -1726,7 +1726,7 @@ Listen Addresses:
|
||||
[Websocket](https://en.wikipedia.org/wiki/WebSocket) is a transport usually used
|
||||
to connect to non-browser-based IPFS nodes from browser-based js-ipfs nodes.
|
||||
|
||||
While it's enabled by default for dialing, go-ipfs doesn't listen on this
|
||||
While it's enabled by default for dialing, Kubo doesn't listen on this
|
||||
transport by default.
|
||||
|
||||
Default: Enabled
|
||||
@ -1785,9 +1785,9 @@ this section will be used to secure unencrypted connections.
|
||||
|
||||
Security transports are configured with the `priority` type.
|
||||
|
||||
When establishing an _outbound_ connection, go-ipfs will try each security
|
||||
When establishing an _outbound_ connection, Kubo will try each security
|
||||
transport in priority order (lower first), until it finds a protocol that the
|
||||
receiver supports. When establishing an _inbound_ connection, go-ipfs will let
|
||||
receiver supports. When establishing an _inbound_ connection, Kubo will let
|
||||
the initiator choose the protocol, but will refuse to use any of the disabled
|
||||
transports.
|
||||
|
||||
@ -1798,7 +1798,7 @@ No default priority will ever be less than 100.
|
||||
#### `Swarm.Transports.Security.TLS`
|
||||
|
||||
[TLS](https://github.com/libp2p/specs/tree/master/tls) (1.3) is the default
|
||||
security transport as of go-ipfs 0.5.0. It's also the most scrutinized and
|
||||
security transport as of Kubo 0.5.0. It's also the most scrutinized and
|
||||
trusted security transport.
|
||||
|
||||
Default: `100`
|
||||
@ -1835,7 +1835,7 @@ No default priority will ever be less than 100.
|
||||
|
||||
### `Swarm.Transports.Multiplexers.Yamux`
|
||||
|
||||
Yamux is the default multiplexer used when communicating between go-ipfs nodes.
|
||||
Yamux is the default multiplexer used when communicating between Kubo nodes.
|
||||
|
||||
Default: `100`
|
||||
|
||||
@ -1843,7 +1843,7 @@ Type: `priority`
|
||||
|
||||
### `Swarm.Transports.Multiplexers.Mplex`
|
||||
|
||||
Mplex is the default multiplexer used when communicating between go-ipfs and all
|
||||
Mplex is the default multiplexer used when communicating between Kubo and all
|
||||
other IPFS and libp2p implementations. Unlike Yamux:
|
||||
|
||||
* Mplex is a simpler protocol.
|
||||
|
||||
@ -39,8 +39,8 @@ Uses a leveldb database to store key value pairs.
|
||||
|
||||
Uses [badger](https://github.com/dgraph-io/badger) as a key value store.
|
||||
|
||||
* `syncWrites`: Flush every write to disk before continuing. Setting this to false is safe as go-ipfs will automatically flush writes to disk before and after performing critical operations like pinning. However, you can set this to true to be extra-safe (at the cost of a 2-3x slowdown when adding files).
|
||||
* `truncate`: Truncate the DB if a partially written sector is found (defaults to true). There is no good reason to set this to false unless you want to manually recover partially written (and unpinned) blocks if go-ipfs crashes half-way through a adding a file.
|
||||
* `syncWrites`: Flush every write to disk before continuing. Setting this to false is safe as kubo will automatically flush writes to disk before and after performing critical operations like pinning. However, you can set this to true to be extra-safe (at the cost of a 2-3x slowdown when adding files).
|
||||
* `truncate`: Truncate the DB if a partially written sector is found (defaults to true). There is no good reason to set this to false unless you want to manually recover partially written (and unpinned) blocks if kubo crashes half-way through a adding a file.
|
||||
|
||||
```json
|
||||
{
|
||||
|
||||
@ -1,14 +1,17 @@
|
||||
# General performance debugging guidelines
|
||||
|
||||
This is a document for helping debug go-ipfs. Please add to it if you can!
|
||||
This is a document for helping debug Kubo. Please add to it if you can!
|
||||
|
||||
### Table of Contents
|
||||
- [Beginning](#beginning)
|
||||
- [Analyzing the stack dump](#analyzing-the-stack-dump)
|
||||
- [Analyzing the CPU Profile](#analyzing-the-cpu-profile)
|
||||
- [Analyzing vars and memory statistics](#analyzing-vars-and-memory-statistics)
|
||||
- [Tracing](#tracing)
|
||||
- [Other](#other)
|
||||
# Table of Contents
|
||||
|
||||
- [General performance debugging guidelines](#general-performance-debugging-guidelines)
|
||||
- [Table of Contents](#table-of-contents)
|
||||
- [Beginning](#beginning)
|
||||
- [Analyzing the stack dump](#analyzing-the-stack-dump)
|
||||
- [Analyzing the CPU Profile](#analyzing-the-cpu-profile)
|
||||
- [Analyzing vars and memory statistics](#analyzing-vars-and-memory-statistics)
|
||||
- [Tracing](#tracing)
|
||||
- [Other](#other)
|
||||
|
||||
### Beginning
|
||||
|
||||
@ -103,6 +106,6 @@ See `tracing/doc.go` for more details.
|
||||
|
||||
### Other
|
||||
|
||||
If you have any questions, or want us to analyze some weird go-ipfs behaviour,
|
||||
If you have any questions, or want us to analyze some weird kubo behaviour,
|
||||
just let us know, and be sure to include all the profiling information
|
||||
mentioned at the top.
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# go-ipfs environment variables
|
||||
# Kubo environment variables
|
||||
|
||||
## `IPFS_PATH`
|
||||
|
||||
@ -9,7 +9,7 @@ Default: ~/.ipfs
|
||||
|
||||
## `IPFS_LOGGING`
|
||||
|
||||
Specifies the log level for go-ipfs.
|
||||
Specifies the log level for Kubo.
|
||||
|
||||
`IPFS_LOGGING` is a deprecated alias for the `GOLOG_LOG_LEVEL` environment variable. See below.
|
||||
|
||||
@ -61,11 +61,11 @@ The logging format defaults to `color` when the output is a terminal, and `nocol
|
||||
|
||||
## `GOLOG_FILE`
|
||||
|
||||
Sets the file to which go-ipfs logs. By default, go-ipfs logs to standard error.
|
||||
Sets the file to which Kubo logs. By default, Kubo logs to standard error.
|
||||
|
||||
## `GOLOG_TRACING_FILE`
|
||||
|
||||
Sets the file to which go-ipfs sends tracing events. By default, tracing is
|
||||
Sets the file to which Kubo sends tracing events. By default, tracing is
|
||||
disabled.
|
||||
|
||||
This log can be read at runtime (without writing it to a file) using the `ipfs
|
||||
@ -87,14 +87,14 @@ Default: false
|
||||
|
||||
## `IPFS_FD_MAX`
|
||||
|
||||
Sets the file descriptor limit for go-ipfs. If go-ipfs fails to set the file
|
||||
Sets the file descriptor limit for Kubo. If Kubo fails to set the file
|
||||
descriptor limit, it will log an error.
|
||||
|
||||
Defaults: 2048
|
||||
|
||||
## `IPFS_DIST_PATH`
|
||||
|
||||
IPFS Content Path from which go-ipfs fetches repo migrations (when the daemon
|
||||
IPFS Content Path from which Kubo fetches repo migrations (when the daemon
|
||||
is launched with the `--migrate` flag).
|
||||
|
||||
Default: `/ipfs/<cid>` (the exact path is hardcoded in
|
||||
@ -116,7 +116,7 @@ $ ipfs resolve -r /ipns/dnslink-test2.example.com
|
||||
|
||||
## `LIBP2P_TCP_REUSEPORT`
|
||||
|
||||
go-ipfs tries to reuse the same source port for all connections to improve NAT
|
||||
Kubo tries to reuse the same source port for all connections to improve NAT
|
||||
traversal. If this is an issue, you can disable it by setting
|
||||
`LIBP2P_TCP_REUSEPORT` to false.
|
||||
|
||||
@ -126,7 +126,7 @@ Default: true
|
||||
|
||||
Deprecated: Use the `Swarm.Transports.Multiplexers` config field.
|
||||
|
||||
Tells go-ipfs which multiplexers to use in which order.
|
||||
Tells Kubo which multiplexers to use in which order.
|
||||
|
||||
Default: "/yamux/1.0.0 /mplex/6.7.0"
|
||||
|
||||
@ -134,7 +134,7 @@ Default: "/yamux/1.0.0 /mplex/6.7.0"
|
||||
|
||||
Forces [libp2p Network Resource Manager](https://github.com/libp2p/go-libp2p-resource-manager#readme)
|
||||
to be enabled (`1`) or disabled (`0`).
|
||||
When set, overrides [`Swarm.ResourceMgr.Enabled`](https://github.com/ipfs/go-ipfs/blob/master/docs/config.md#swarmresourcemgrenabled) from the config.
|
||||
When set, overrides [`Swarm.ResourceMgr.Enabled`](https://github.com/ipfs/kubo/blob/master/docs/config.md#swarmresourcemgrenabled) from the config.
|
||||
|
||||
Default: use config (not set)
|
||||
|
||||
@ -190,7 +190,7 @@ Default: "$PWD/traces.json"
|
||||
### How to use Jaeger UI
|
||||
|
||||
One can use the `jaegertracing/all-in-one` Docker image to run a full Jaeger
|
||||
stack and configure go-ipfs to publish traces to it (here, in an ephemeral
|
||||
stack and configure Kubo to publish traces to it (here, in an ephemeral
|
||||
container):
|
||||
|
||||
```console
|
||||
@ -208,7 +208,7 @@ $ docker run --rm -it --name jaeger \
|
||||
jaegertracing/all-in-one
|
||||
```
|
||||
|
||||
Then, in other terminal, start go-ipfs with Jaeger tracing enabled:
|
||||
Then, in other terminal, start Kubo with Jaeger tracing enabled:
|
||||
```
|
||||
$ OTEL_TRACES_EXPORTER=jaeger ipfs daemon
|
||||
```
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
# Experimental features of go-ipfs
|
||||
# Experimental features of Kubo
|
||||
|
||||
This document contains a list of experimental features in go-ipfs.
|
||||
This document contains a list of experimental features in Kubo.
|
||||
These features, commands, and APIs aren't mature, and you shouldn't rely on them.
|
||||
Once they reach maturity, there's going to be mention in the changelog and
|
||||
release posts. If they don't reach maturity, the same applies, and their code is
|
||||
removed.
|
||||
|
||||
Subscribe to https://github.com/ipfs/go-ipfs/issues/3397 to get updates.
|
||||
Subscribe to https://github.com/ipfs/kubo/issues/3397 to get updates.
|
||||
|
||||
When you add a new experimental feature to go-ipfs or change an experimental
|
||||
When you add a new experimental feature to kubo or change an experimental
|
||||
feature, you MUST please make a PR updating this document, and link the PR in
|
||||
the above issue.
|
||||
|
||||
@ -54,7 +54,7 @@ Then use the `ipfs pubsub` commands.
|
||||
|
||||
NOTE: `--enable-pubsub-experiment` CLI flag overrides `Pubsub.Enabled` config.
|
||||
|
||||
Configuration documentation can be found in [go-ipfs/docs/config.md](./config.md#pubsub)
|
||||
Configuration documentation can be found in [kubo/docs/config.md](./config.md#pubsub)
|
||||
|
||||
### Road to being a real feature
|
||||
|
||||
@ -435,7 +435,7 @@ Replaced by autosharding.
|
||||
|
||||
The `Experimental.ShardingEnabled` config field is no longer used, please remove it from your configs.
|
||||
|
||||
go-ipfs now automatically shards when directory block is bigger than 256KB, ensuring every block is small enough to be exchanged with other peers
|
||||
kubo now automatically shards when directory block is bigger than 256KB, ensuring every block is small enough to be exchanged with other peers
|
||||
|
||||
## IPNS pubsub
|
||||
|
||||
@ -574,7 +574,7 @@ ipfs config --json Experimental.GraphsyncEnabled true
|
||||
|
||||
Stable, enabled by default
|
||||
|
||||
[Noise](https://github.com/libp2p/specs/tree/master/noise) libp2p transport based on the [Noise Protocol Framework](https://noiseprotocol.org/noise.html). While TLS remains the default transport in go-ipfs, Noise is easier to implement and is thus the "interop" transport between IPFS and libp2p implementations.
|
||||
[Noise](https://github.com/libp2p/specs/tree/master/noise) libp2p transport based on the [Noise Protocol Framework](https://noiseprotocol.org/noise.html). While TLS remains the default transport in Kubo, Noise is easier to implement and is thus the "interop" transport between IPFS and libp2p implementations.
|
||||
|
||||
## Accelerated DHT Client
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
**EXPERIMENTAL:** FUSE support is limited, YMMV.
|
||||
|
||||
`go-ipfs` makes it possible to mount `/ipfs` and `/ipns` namespaces in your OS,
|
||||
Kubo makes it possible to mount `/ipfs` and `/ipns` namespaces in your OS,
|
||||
allowing arbitrary apps access to IPFS.
|
||||
|
||||
## Install FUSE
|
||||
|
||||
@ -6,9 +6,11 @@ they were stored in a traditional web server.
|
||||
|
||||
[More about Gateways](https://docs.ipfs.io/concepts/ipfs-gateway/) and [addressing IPFS on the web](https://docs.ipfs.io/how-to/address-ipfs-on-web/).
|
||||
|
||||
Kubo's Gateway implementation follows [ipfs/specs: Specification for HTTP Gateways](https://github.com/ipfs/specs/tree/main/http-gateways#readme).
|
||||
|
||||
### Local gateway
|
||||
|
||||
By default, go-ipfs nodes run
|
||||
By default, Kubo nodes run
|
||||
a [path gateway](https://docs.ipfs.io/how-to/address-ipfs-on-web/#path-gateway) at `http://127.0.0.1:8080/`
|
||||
and a [subdomain gateway](https://docs.ipfs.io/how-to/address-ipfs-on-web/#subdomain-gateway) at `http://localhost:8080/`
|
||||
|
||||
@ -24,8 +26,8 @@ There is a list of third-party public gateways provided by the IPFS community at
|
||||
## Configuration
|
||||
|
||||
The `Gateway.*` configuration options are (briefly) described in the
|
||||
[config](https://github.com/ipfs/go-ipfs/blob/master/docs/config.md#gateway)
|
||||
documentation, including a list of common [gateway recipes](https://github.com/ipfs/go-ipfs/blob/master/docs/config.md#gateway-recipes).
|
||||
[config](https://github.com/ipfs/kubo/blob/master/docs/config.md#gateway)
|
||||
documentation, including a list of common [gateway recipes](https://github.com/ipfs/kubo/blob/master/docs/config.md#gateway-recipes).
|
||||
|
||||
### Debug
|
||||
The gateway's log level can be changed with this command:
|
||||
@ -45,7 +47,7 @@ a directory:
|
||||
2. Dynamically build and serve a listing of the contents of the directory.
|
||||
|
||||
<sub><sup>†</sup>This redirect is skipped if the query string contains a
|
||||
`go-get=1` parameter. See [PR#3964](https://github.com/ipfs/go-ipfs/pull/3963)
|
||||
`go-get=1` parameter. See [PR#3964](https://github.com/ipfs/kubo/pull/3963)
|
||||
for details</sub>
|
||||
|
||||
## Static Websites
|
||||
@ -97,7 +99,7 @@ This is equivalent of `ipfs block get`.
|
||||
Returns a [CAR](https://ipld.io/specs/transport/car/) stream for specific DAG and selector.
|
||||
|
||||
Right now only 'full DAG' implicit selector is implemented.
|
||||
Support for user-provided IPLD selectors is tracked in https://github.com/ipfs/go-ipfs/issues/8769.
|
||||
Support for user-provided IPLD selectors is tracked in https://github.com/ipfs/kubo/issues/8769.
|
||||
|
||||
This is a rough equivalent of `ipfs dag export`.
|
||||
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
# IPFS API Implementation Doc
|
||||
|
||||
This short document aims to give a quick guide to anyone implementing API
|
||||
bindings for IPFS implementations-- in particular go-ipfs.
|
||||
bindings for IPFS implementations-- in particular kubo.
|
||||
|
||||
Sections:
|
||||
- IPFS Types
|
||||
@ -28,7 +28,7 @@ handled for you by writes to the request body blocking.)
|
||||
## API Transports
|
||||
|
||||
Like with everything else, IPFS aims to be flexible regarding the API transports.
|
||||
Currently, the [go-ipfs](https://github.com/ipfs/go-ipfs) implementation supports
|
||||
Currently, the [kubo](https://github.com/ipfs/kubo) implementation supports
|
||||
both an in-process API and an HTTP API. More can be added easily, by mapping the
|
||||
API functions over a transport. (This is similar to how gRPC is also _mapped on
|
||||
top of transports_, like HTTP).
|
||||
@ -45,7 +45,7 @@ In the commandline, IPFS uses a traditional flag and arg-based mapping, where:
|
||||
`ipfs object patch <hash1> add-linkfoo <hash2>`
|
||||
- files are specified by filename, or through stdin
|
||||
|
||||
(NOTE: When go-ipfs runs the daemon, the CLI API is actually converted to HTTP
|
||||
(NOTE: When kubo runs the daemon, the CLI API is actually converted to HTTP
|
||||
calls. otherwise, they execute in the same process)
|
||||
|
||||
#### HTTP API Transport
|
||||
@ -62,8 +62,8 @@ In HTTP, our API layering uses a REST-like mapping, where:
|
||||
## API Commands
|
||||
|
||||
There is a "standard IPFS API" which is currently defined as "all the commands
|
||||
exposed by the go-ipfs implementation". There are auto-generated [API Docs](https://ipfs.io/docs/api/).
|
||||
You can Also see [a listing here](https://github.com/ipfs/go-ipfs/blob/94b832df861728c65e912935641d08880c341e0a/core/commands/root.go#L96-L130), or get a list of
|
||||
exposed by the kubo implementation". There are auto-generated [API Docs](https://ipfs.io/docs/api/).
|
||||
You can Also see [a listing here](https://github.com/ipfs/kubo/blob/94b832df861728c65e912935641d08880c341e0a/core/commands/root.go#L96-L130), or get a list of
|
||||
commands by running `ipfs commands` locally.
|
||||
|
||||
## Implementing bindings for the HTTP API
|
||||
@ -80,8 +80,8 @@ To date, we have two different HTTP API clients:
|
||||
|
||||
- [js-ipfs-api](https://github.com/ipfs/js-ipfs-api) - simple javascript
|
||||
wrapper -- best to look at
|
||||
- [go-ipfs/commands/http](https://github.com/ipfs/go-ipfs/tree/916f987de2c35db71815b54bbb9a0a71df829838/commands/http) -
|
||||
generalized transport based on the [command definitions](https://github.com/ipfs/go-ipfs/tree/916f987de2c35db71815b54bbb9a0a71df829838/core/commands)
|
||||
- [kubo/commands/http](https://github.com/ipfs/kubo/tree/916f987de2c35db71815b54bbb9a0a71df829838/commands/http) -
|
||||
generalized transport based on the [command definitions](https://github.com/ipfs/kubo/tree/916f987de2c35db71815b54bbb9a0a71df829838/core/commands)
|
||||
|
||||
The Go implementation is good to answer harder questions, like how is multipart
|
||||
handled, or what headers should be set in edge conditions. But the javascript
|
||||
@ -102,14 +102,14 @@ Currently, node-ipfs-api has three main files
|
||||
|
||||
Despite all the generalization spoken about above, the IPFS API is actually very
|
||||
simple. You can inspect all the requests made with `nc` and the `--api` option
|
||||
(as of [this PR](https://github.com/ipfs/go-ipfs/pull/1598), or `0.3.8`):
|
||||
(as of [this PR](https://github.com/ipfs/kubo/pull/1598), or `0.3.8`):
|
||||
|
||||
```
|
||||
> nc -l 5002 &
|
||||
> ipfs --api /ip4/127.0.0.1/tcp/5002 swarm addrs local --enc=json
|
||||
POST /api/v0/version?enc=json&stream-channels=true HTTP/1.1
|
||||
Host: 127.0.0.1:5002
|
||||
User-Agent: /go-ipfs/0.3.8/
|
||||
User-Agent: /kubo/0.14.0/
|
||||
Content-Length: 0
|
||||
Content-Type: application/octet-stream
|
||||
Accept-Encoding: gzip
|
||||
@ -118,7 +118,7 @@ Accept-Encoding: gzip
|
||||
```
|
||||
|
||||
The only hard part is getting the file streaming right. It is (now) fairly easy
|
||||
to stream files to go-ipfs using multipart. Basically, we end up with HTTP
|
||||
to stream files to kubo using multipart. Basically, we end up with HTTP
|
||||
requests like this:
|
||||
|
||||
```
|
||||
@ -126,7 +126,7 @@ requests like this:
|
||||
> ipfs --api /ip4/127.0.0.1/tcp/5002 add -r ~/demo/basic/test
|
||||
POST /api/v0/add?encoding=json&progress=true&r=true&stream-channels=true HTTP/1.1
|
||||
Host: 127.0.0.1:5002
|
||||
User-Agent: /go-ipfs/0.3.8/
|
||||
User-Agent: /kubo/0.14.0/
|
||||
Transfer-Encoding: chunked
|
||||
Content-Disposition: form-data: name="files"
|
||||
Content-Type: multipart/form-data; boundary=2186ef15d8f2c4f100af72d6d345afe36a4d17ef11264ec5b8ec4436447f
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# Plugins
|
||||
|
||||
Since 0.4.11 go-ipfs has an experimental plugin system that allows augmenting
|
||||
Since 0.4.11 Kubo has an experimental plugin system that allows augmenting
|
||||
the daemons functionality without recompiling.
|
||||
|
||||
When an IPFS node is started, it will load plugins from the `$IPFS_PATH/plugins`
|
||||
@ -22,7 +22,7 @@ directory (by default `~/.ipfs/plugins`).
|
||||
## Plugin Types
|
||||
|
||||
Plugins can implement one or more plugin types, defined in the
|
||||
[plugin](https://godoc.org/github.com/ipfs/go-ipfs/plugin) package.
|
||||
[plugin](https://godoc.org/github.com/ipfs/kubo/plugin) package.
|
||||
|
||||
### IPLD
|
||||
|
||||
@ -37,15 +37,15 @@ Datastore plugins add support for additional datastore backends.
|
||||
|
||||
(experimental)
|
||||
|
||||
Tracer plugins allow injecting an opentracing backend into go-ipfs.
|
||||
Tracer plugins allow injecting an opentracing backend into Kubo.
|
||||
|
||||
### Daemon
|
||||
|
||||
Daemon plugins are started when the go-ipfs daemon is started and are given an
|
||||
Daemon plugins are started when the Kubo daemon is started and are given an
|
||||
instance of the CoreAPI. This should make it possible to build an ipfs-based
|
||||
application without IPC and without forking go-ipfs.
|
||||
application without IPC and without forking Kubo.
|
||||
|
||||
Note: We eventually plan to make go-ipfs usable as a library. However, this
|
||||
Note: We eventually plan to make Kubo usable as a library. However, this
|
||||
plugin type is likely the best interim solution.
|
||||
|
||||
### Internal
|
||||
@ -53,9 +53,9 @@ plugin type is likely the best interim solution.
|
||||
(never stable)
|
||||
|
||||
Internal plugins are like daemon plugins _except_ that they can access, replace,
|
||||
and modify all internal state. Use this plugin type to extend go-ipfs in
|
||||
and modify all internal state. Use this plugin type to extend Kubo in
|
||||
arbitrary ways. However, be aware that your plugin will likely break every time
|
||||
go-ipfs updated.
|
||||
Kubo updated.
|
||||
|
||||
## Configuration
|
||||
|
||||
@ -89,47 +89,47 @@ Example:
|
||||
|
||||
| Name | Type | Preloaded | Description |
|
||||
|---------------------------------------------------------------------------------|-----------|-----------|------------------------------------------------|
|
||||
| [git](https://github.com/ipfs/go-ipfs/tree/master/plugin/plugins/git) | IPLD | x | An IPLD format for git objects. |
|
||||
| [badgerds](https://github.com/ipfs/go-ipfs/tree/master/plugin/plugins/badgerds) | Datastore | x | A high performance but experimental datastore. |
|
||||
| [flatfs](https://github.com/ipfs/go-ipfs/tree/master/plugin/plugins/flatfs) | Datastore | x | A stable filesystem-based datastore. |
|
||||
| [levelds](https://github.com/ipfs/go-ipfs/tree/master/plugin/plugins/levelds) | Datastore | x | A stable, flexible datastore backend. |
|
||||
| [git](https://github.com/ipfs/kubo/tree/master/plugin/plugins/git) | IPLD | x | An IPLD format for git objects. |
|
||||
| [badgerds](https://github.com/ipfs/kubo/tree/master/plugin/plugins/badgerds) | Datastore | x | A high performance but experimental datastore. |
|
||||
| [flatfs](https://github.com/ipfs/kubo/tree/master/plugin/plugins/flatfs) | Datastore | x | A stable filesystem-based datastore. |
|
||||
| [levelds](https://github.com/ipfs/kubo/tree/master/plugin/plugins/levelds) | Datastore | x | A stable, flexible datastore backend. |
|
||||
| [jaeger](https://github.com/ipfs/go-jaeger-plugin) | Tracing | | An opentracing backend. |
|
||||
|
||||
* **Preloaded** plugins are built into the go-ipfs binary and do not need to be
|
||||
* **Preloaded** plugins are built into the Kubo binary and do not need to be
|
||||
installed separately. At the moment, all in-tree plugins are preloaded.
|
||||
|
||||
## Installing Plugins
|
||||
|
||||
Go-ipfs supports two types of plugins: External and Preloaded.
|
||||
Kubo supports two types of plugins: External and Preloaded.
|
||||
|
||||
* External plugins must be installed in `$IPFS_PATH/plugins/` (usually
|
||||
`~/.ipfs/plugins/`).
|
||||
* Preloaded plugins are built-into the go-ipfs when it's compiled.
|
||||
* Preloaded plugins are built-into the Kubo when it's compiled.
|
||||
|
||||
### External Plugin
|
||||
|
||||
The advantage of an external plugin is that it can be built, packaged, and
|
||||
installed independently of go-ipfs. Unfortunately, this method is only supported
|
||||
installed independently of Kubo. Unfortunately, this method is only supported
|
||||
on Linux and MacOS at the moment. Users of other operating systems should follow
|
||||
the instructions for preloaded plugins.
|
||||
|
||||
#### In-tree
|
||||
|
||||
To build plugins included in
|
||||
[plugin/plugins](https://github.com/ipfs/go-ipfs/tree/master/plugin/plugins),
|
||||
[plugin/plugins](https://github.com/ipfs/kubo/tree/master/plugin/plugins),
|
||||
run:
|
||||
|
||||
```bash
|
||||
go-ipfs$ make build_plugins
|
||||
go-ipfs$ ls plugin/plugins/*.so
|
||||
kubo$ make build_plugins
|
||||
kubo$ ls plugin/plugins/*.so
|
||||
```
|
||||
|
||||
To install, copy desired plugins to `$IPFS_PATH/plugins`. For example:
|
||||
|
||||
```bash
|
||||
go-ipfs$ mkdir -p ~/.ipfs/plugins/
|
||||
go-ipfs$ cp plugin/plugins/git.so ~/.ipfs/plugins/
|
||||
go-ipfs$ chmod +x ~/.ipfs/plugins/git.so # ensure plugin is executable
|
||||
kubo$ mkdir -p ~/.ipfs/plugins/
|
||||
kubo$ cp plugin/plugins/git.so ~/.ipfs/plugins/
|
||||
kubo$ chmod +x ~/.ipfs/plugins/git.so # ensure plugin is executable
|
||||
```
|
||||
|
||||
Finally, restart daemon if it is running.
|
||||
@ -153,22 +153,22 @@ Finally, as with in-tree plugins:
|
||||
|
||||
The advantages of preloaded plugins are:
|
||||
|
||||
1. They're bundled with the go-ipfs binary.
|
||||
1. They're bundled with the Kubo binary.
|
||||
2. They work on all platforms.
|
||||
|
||||
To preload a go-ipfs plugin:
|
||||
To preload a Kubo plugin:
|
||||
|
||||
1. Add the plugin to the preload list: `plugin/loader/preload_list`
|
||||
2. Build ipfs
|
||||
```bash
|
||||
go-ipfs$ make build
|
||||
kubo$ make build
|
||||
```
|
||||
|
||||
You can also preload an in-tree but disabled-by-default plugin by adding it to
|
||||
the IPFS_PLUGINS variable. For example, to enable plugins foo, bar, and baz:
|
||||
|
||||
```bash
|
||||
go-ipfs$ make build IPFS_PLUGINS="foo bar baz"
|
||||
kubo$ make build IPFS_PLUGINS="foo bar baz"
|
||||
```
|
||||
|
||||
## Creating A Plugin
|
||||
|
||||
@ -1,22 +1,25 @@
|
||||
# `go-ipfs` Release Flow
|
||||
# `kubo` Release Flow
|
||||
|
||||
## Table of Contents
|
||||
# Table of Contents
|
||||
|
||||
- [Release Philosophy](#release-philosophy)
|
||||
- [Release Flow](#release-flow)
|
||||
- [Stage 0 - Automated Testing](#stage-0---automated-testing)
|
||||
- [Stage 1 - Internal Testing](#stage-1---internal-testing)
|
||||
- [Stage 2 - Community Dev Testing](#stage-2---community-dev-testing)
|
||||
- [Stage 3 - Community Prod Testing](#stage-3---community-prod-testing)
|
||||
- [Stage 4 - Release](#stage-4---release)
|
||||
- [Release Cycle](#release-cycle)
|
||||
- [Patch Releases](#patch-releases)
|
||||
- [Performing a Release](#performing-a-release)
|
||||
- [Release Version Numbers (aka semver)](#release-version-numbers-aka-semver)
|
||||
- [`kubo` Release Flow](#kubo-release-flow)
|
||||
- [Table of Contents](#table-of-contents)
|
||||
- [Release Philosophy](#release-philosophy)
|
||||
- [Release Flow](#release-flow)
|
||||
- [Stage 0 - Automated Testing](#stage-0---automated-testing)
|
||||
- [Stage 1 - Internal Testing](#stage-1---internal-testing)
|
||||
- [Stage 2 - Community Dev Testing](#stage-2---community-dev-testing)
|
||||
- [Stage 3 - Community Prod Testing](#stage-3---community-prod-testing)
|
||||
- [Stage 4 - Release](#stage-4---release)
|
||||
- [Release Cycle](#release-cycle)
|
||||
- [Patch Releases](#patch-releases)
|
||||
- [Security Fix Policy](#security-fix-policy)
|
||||
- [Performing a Release](#performing-a-release)
|
||||
- [Release Version Numbers (aka semver)](#release-version-numbers-aka-semver)
|
||||
|
||||
## Release Philosophy
|
||||
|
||||
`go-ipfs` aims to have release every six weeks, two releases per quarter. During these 6 week releases, we go through 4 different stages that gives us the opportunity to test the new version against our test environments (unit, interop, integration), QA in our current production environment, IPFS apps (e.g. Desktop and WebUI) and with our community and _early testers_<sup>[1]</sup> that have IPFS running in production.
|
||||
`kubo` aims to have release every six weeks, two releases per quarter. During these 6 week releases, we go through 4 different stages that gives us the opportunity to test the new version against our test environments (unit, interop, integration), QA in our current production environment, IPFS apps (e.g. Desktop and WebUI) and with our community and _early testers_<sup>[1]</sup> that have IPFS running in production.
|
||||
|
||||
We might expand the six week release schedule in case of:
|
||||
|
||||
@ -25,9 +28,9 @@ We might expand the six week release schedule in case of:
|
||||
|
||||
## Release Flow
|
||||
|
||||
`go-ipfs` releases come in 5 stages designed to gradually roll out changes and reduce the impact of any regressions that may have been introduced. If we need to merge non-trivial<sup>[2]</sup> changes during the process, we start over at stage 0.
|
||||
`kubo` releases come in 5 stages designed to gradually roll out changes and reduce the impact of any regressions that may have been introduced. If we need to merge non-trivial<sup>[2]</sup> changes during the process, we start over at stage 0.
|
||||
|
||||
|
||||
|
||||
|
||||
### Stage 0 - Automated Testing
|
||||
|
||||
@ -93,21 +96,21 @@ Finally, unless a security issue is actively being exploited or a significant nu
|
||||
|
||||
## Performing a Release
|
||||
|
||||
The release is managed by the `Lead Maintainer` for `go-ipfs`. It starts with the opening of an issue containing the content available on the [RELEASE_ISSUE_TEMPLATE](./RELEASE_ISSUE_TEMPLATE.md) not more than **48 hours** after the previous release.
|
||||
The release is managed by the `Lead Maintainer` for `kubo`. It starts with the opening of an issue containing the content available on the [RELEASE_ISSUE_TEMPLATE](./RELEASE_ISSUE_TEMPLATE.md) not more than **48 hours** after the previous release.
|
||||
|
||||
This issue is pinned and labeled ["release"](https://github.com/ipfs/go-ipfs/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Arelease). When the cycle is due to begin the 5 stages will be followed until the release is done.
|
||||
This issue is pinned and labeled ["release"](https://github.com/ipfs/kubo/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3Arelease). When the cycle is due to begin the 5 stages will be followed until the release is done.
|
||||
|
||||
## Release Version Numbers (aka semver)
|
||||
|
||||
Until `go-ipfs` 0.4.X, `go-ipfs` was not using semver to communicate the type of release
|
||||
Until `kubo` 0.4.X, `kubo` was not using semver to communicate the type of release
|
||||
|
||||
Post `go-ipfs` 0.5.X, `go-ipfs` will use semver. This means that patch releases will not contain any breaking changes nor new features. Minor releases might contain breaking changes and always contain some new feature
|
||||
Post `kubo` 0.5.X, `kubo` will use semver. This means that patch releases will not contain any breaking changes nor new features. Minor releases might contain breaking changes and always contain some new feature
|
||||
|
||||
Post `go-ipfs` 1.X.X (future), `go-ipfs` will use semver. This means that only major releases will contain breaking changes, minors will be reserved for new features and patches for bug fixes.
|
||||
Post `kubo` 1.X.X (future), `kubo` will use semver. This means that only major releases will contain breaking changes, minors will be reserved for new features and patches for bug fixes.
|
||||
|
||||
We do not yet retroactively apply fixes to older releases (no Long Term Support releases for now), which means that we always recommend users to update to the latest, whenever possible.
|
||||
|
||||
----------------------------
|
||||
|
||||
- <sup>**[1]**</sup> - _early testers_ is an IPFS programme in which members of the community can self-volunteer to help test `go-ipfs` Release Candidates. You find more info about it at [EARLY_TESTERS.md](./EARLY_TESTERS.md)
|
||||
- <sup>**[1]**</sup> - _early testers_ is an IPFS programme in which members of the community can self-volunteer to help test `kubo` Release Candidates. You find more info about it at [EARLY_TESTERS.md](./EARLY_TESTERS.md)
|
||||
- <sup>**[2]**</sup> - A non-trivial change is any change that could potentially introduce an issue not trivially caught by automated testing. This is up to the discretion of the Lead Maintainer but the assumption is that every change is non-trivial unless proven otherwise.
|
||||
|
||||
@ -3,9 +3,9 @@
|
||||
If you want browsers to connect to e.g. `/dns4/example.com/tcp/443/wss/p2p/QmFoo`
|
||||
|
||||
- [ ] An SSL cert matching the `/dns4` or `/dns6` name
|
||||
- [ ] go-ipfs listening on `/ip4/127.0.0.1/tcp/8081/ws`
|
||||
- [ ] Kubo listening on `/ip4/127.0.0.1/tcp/8081/ws`
|
||||
- 8081 is just an example
|
||||
- note that it's `/ws` here, not `/wss` -- go-ipfs can't currently do SSL, see the next point
|
||||
- note that it's `/ws` here, not `/wss` -- Kubo can't currently do SSL, see the next point
|
||||
- [ ] nginx
|
||||
- configured with the SSL cert
|
||||
- listening on port 443
|
||||
|
||||
@ -1,20 +1,20 @@
|
||||
# Building on Windows
|
||||
|
||||
|
||||
If you just want to install go-ipfs, please download it from https://dist.ipfs.io/#go-ipfs. This document explains how to build it from source.
|
||||
If you just want to install kubo, please download it from https://dist.ipfs.io/#kubo. This document explains how to build it from source.
|
||||
|
||||
## Install Go
|
||||
`go-ipfs` is built on Golang and thus depends on it for all building methods.
|
||||
`kubo` is built on Golang and thus depends on it for all building methods.
|
||||
https://golang.org/doc/install
|
||||
The `GOPATH` environment variable must be set as well.
|
||||
https://golang.org/doc/code.html#GOPATH
|
||||
|
||||
## Choose the way you want to proceed
|
||||
`go-ipfs` utilizes `make` to automate builds and run tests, but can be built without it using only `git` and `go`.
|
||||
`kubo` utilizes `make` to automate builds and run tests, but can be built without it using only `git` and `go`.
|
||||
No matter which method you choose, if you encounter issues, please see the [Troubleshooting](#troubleshooting) section.
|
||||
|
||||
**Using `make`:**
|
||||
MSYS2 and Cygwin provide the Unix tools we need to build `go-ipfs`. You may use either, but if you don't already have one installed, we recommend MSYS2.
|
||||
MSYS2 and Cygwin provide the Unix tools we need to build `kubo`. You may use either, but if you don't already have one installed, we recommend MSYS2.
|
||||
[MSYS2→](#msys2)
|
||||
[Cygwin→](#cygwin)
|
||||
|
||||
@ -29,28 +29,28 @@ An explanation of this block is below.
|
||||
```
|
||||
SET PATH=%PATH%;\msys64\usr\bin
|
||||
pacman --noconfirm -S git make unzip
|
||||
go get -u github.com/ipfs/go-ipfs
|
||||
cd %GOPATH%\src\github.com\ipfs\go-ipfs
|
||||
go get -u github.com/ipfs/kubo
|
||||
cd %GOPATH%\src\github.com\ipfs\kubo
|
||||
make install
|
||||
%GOPATH%\bin\ipfs.exe version --all
|
||||
```
|
||||
|
||||
If there were no errors, the final command should output version information similar to "`ipfs version 0.4.14-dev-XXXXXXX`" where "XXXXXXX" should match the current short-hash of the `go-ipfs` repo. You can retrieve said hash via this command: `git rev-parse --short HEAD`.
|
||||
If there were no errors, the final command should output version information similar to "`ipfs version 0.4.14-dev-XXXXXXX`" where "XXXXXXX" should match the current short-hash of the `kubo` repo. You can retrieve said hash via this command: `git rev-parse --short HEAD`.
|
||||
If `ipfs.exe` executes and the version string matches, then building was successful.
|
||||
|
||||
|Command|Explanation|
|
||||
| ---: | :--- |
|
||||
|`SET PATH=%PATH%;\msys64\usr\bin` |Add msys2's tools to our [`PATH`](https://ss64.com/nt/path.html); Defaults to: (\msys64\usr\bin)|
|
||||
|`pacman --noconfirm -S git make unzip` |Install `go-ipfs` build dependencies|
|
||||
|`go get -u github.com/ipfs/go-ipfs` |Fetch / Update `go-ipfs` source|
|
||||
|`cd %GOPATH%\src\github.com\ipfs\go-ipfs` |Change to `go-ipfs` source directory|
|
||||
|`pacman --noconfirm -S git make unzip` |Install `kubo` build dependencies|
|
||||
|`go get -u github.com/ipfs/kubo` |Fetch / Update `kubo` source|
|
||||
|`cd %GOPATH%\src\github.com\ipfs\kubo` |Change to `kubo` source directory|
|
||||
|`make install` |Build and install to `%GOPATH%\bin\ipfs.exe`|
|
||||
|`%GOPATH%\bin\ipfs.exe version --all` |Test the built binary|
|
||||
|
||||
To build again after making changes to the source, run:
|
||||
```
|
||||
SET PATH=%PATH%;\msys64\usr\bin
|
||||
cd %GOPATH%\src\github.com\ipfs\go-ipfs
|
||||
cd %GOPATH%\src\github.com\ipfs\kubo
|
||||
make install
|
||||
```
|
||||
|
||||
@ -75,27 +75,27 @@ An explanation of this block is below.
|
||||
SET PATH=%PATH%;\cygwin64\bin
|
||||
mkdir %GOPATH%\src\github.com\ipfs
|
||||
cd %GOPATH%\src\github.com\ipfs
|
||||
git clone https://github.com/ipfs/go-ipfs.git
|
||||
cd %GOPATH%\src\github.com\ipfs\go-ipfs
|
||||
git clone https://github.com/ipfs/kubo.git
|
||||
cd %GOPATH%\src\github.com\ipfs\kubo
|
||||
make install
|
||||
%GOPATH%\bin\ipfs.exe version --all
|
||||
```
|
||||
|
||||
If there were no errors, the final command should output version information similar to "`ipfs version 0.4.14-dev-XXXXXXX`" where "XXXXXXX" should match the current short-hash of the `go-ipfs` repo. You can retrieve said hash via this command: `git rev-parse --short HEAD`.
|
||||
If there were no errors, the final command should output version information similar to "`ipfs version 0.4.14-dev-XXXXXXX`" where "XXXXXXX" should match the current short-hash of the `kubo` repo. You can retrieve said hash via this command: `git rev-parse --short HEAD`.
|
||||
If `ipfs.exe` executes and the version string matches, then building was successful.
|
||||
|
||||
|Command|Explanation|
|
||||
| ---: | :--- |
|
||||
|`SET PATH=%PATH%;\cygwin64\bin` |Add Cygwin's tools to our [`PATH`](https://ss64.com/nt/path.html); Defaults to: (\cygwin64\bin)|
|
||||
|`mkdir %GOPATH%\src\github.com\ipfs`<br/>`cd %GOPATH%\src\github.com\ipfs`<br/>`git clone https://github.com/ipfs/go-ipfs.git` |Fetch / Update `go-ipfs` source|
|
||||
|`cd %GOPATH%\src\github.com\ipfs\go-ipfs` |Change to `go-ipfs` source directory|
|
||||
|`mkdir %GOPATH%\src\github.com\ipfs`<br/>`cd %GOPATH%\src\github.com\ipfs`<br/>`git clone https://github.com/ipfs/kubo.git` |Fetch / Update `kubo` source|
|
||||
|`cd %GOPATH%\src\github.com\ipfs\kubo` |Change to `kubo` source directory|
|
||||
|`make install` |Build and install to `%GOPATH%\bin\ipfs.exe`|
|
||||
|`%GOPATH%\bin\ipfs.exe version --all` |Test the built binary|
|
||||
|
||||
To build again after making changes to the source, run:
|
||||
```
|
||||
SET PATH=%PATH%;\cygwin64\bin
|
||||
cd %GOPATH%\src\github.com\ipfs\go-ipfs
|
||||
cd %GOPATH%\src\github.com\ipfs\kubo
|
||||
make install
|
||||
```
|
||||
|
||||
@ -106,24 +106,24 @@ SETX PATH %PATH%
|
||||
|
||||
## Minimal
|
||||
|
||||
While it's possible to build `go-ipfs` with `go` alone, we'll be using `git` to fetch the source.
|
||||
While it's possible to build `kubo` with `go` alone, we'll be using `git` to fetch the source.
|
||||
|
||||
You can use whichever version of `git` you wish but we recommend the Windows builds at <https://git-scm.com>. `git` must be in your [`PATH`](https://ss64.com/nt/path.html) for `go get` to recognize and use it.
|
||||
|
||||
### go-ipfs
|
||||
### kubo
|
||||
|
||||
Clone and change directory to the source code, if you haven't already:
|
||||
|
||||
CMD:
|
||||
```bat
|
||||
git clone https://github.com/ipfs/go-ipfs %GOPATH%/src/github.com/ipfs/go-ipfs
|
||||
cd %GOPATH%/src/github.com/ipfs/go-ipfs/cmd/ipfs
|
||||
git clone https://github.com/ipfs/kubo %GOPATH%/src/github.com/ipfs/kubo
|
||||
cd %GOPATH%/src/github.com/ipfs/kubo/cmd/ipfs
|
||||
```
|
||||
|
||||
PowerShell:
|
||||
```powershell
|
||||
git clone https://github.com/ipfs/go-ipfs $env:GOPATH/src/github.com/ipfs/go-ipfs
|
||||
cd $env:GOPATH/src/github.com/ipfs/go-ipfs/cmd/ipfs
|
||||
git clone https://github.com/ipfs/kubo $env:GOPATH/src/github.com/ipfs/kubo
|
||||
cd $env:GOPATH/src/github.com/ipfs/kubo/cmd/ipfs
|
||||
```
|
||||
|
||||
We need the `git` commit hash to be included in our build so that in the extremely rare event a bug is found, we have a reference point later for tracking it. We'll ask `git` for it and store it in a variable. The syntax for the next command is different depending on whether you're using the interactive command line or writing a batch file. Use the one that applies to you.
|
||||
@ -134,13 +134,13 @@ Finally, we'll build and test `ipfs` itself.
|
||||
|
||||
CMD:
|
||||
```bat
|
||||
go install -ldflags="-X "github.com/ipfs/go-ipfs".CurrentCommit=%SHA%"
|
||||
go install -ldflags="-X "github.com/ipfs/kubo".CurrentCommit=%SHA%"
|
||||
%GOPATH%\bin\ipfs.exe version --all
|
||||
```
|
||||
|
||||
PowerShell:
|
||||
```powershell
|
||||
go install -ldflags="-X "github.com/ipfs/go-ipfs".CurrentCommit=$env:SHA"
|
||||
go install -ldflags="-X "github.com/ipfs/kubo".CurrentCommit=$env:SHA"
|
||||
cp ./ipfs.exe $env:GOPATH/bin/ipfs.exe -force
|
||||
. $env:GOPATH/bin/ipfs.exe version --all
|
||||
```
|
||||
@ -155,4 +155,4 @@ If you get authentication problems with Git, you might want to take a look at ht
|
||||
- **Anything else**
|
||||
Please search [https://discuss.ipfs.io](https://discuss.ipfs.io/search?q=windows%20category%3A13) for any additional issues you may encounter. If you can't find any existing resolution, feel free to post a question asking for help.
|
||||
|
||||
If you encounter a bug with `go-ipfs` itself (not related to building) please use the [issue tracker](https://github.com/ipfs/go-ipfs/issues) to report it.
|
||||
If you encounter a bug with `kubo` itself (not related to building) please use the [issue tracker](https://github.com/ipfs/kubo/issues) to report it.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user