Install Kubo

This document provides step-by-step instructions for installing Kubo, the reference implementation of the ADCS protocol, on various operating systems. It covers methods for binary installation, source compilation, and initial node configuration required to join the Autheo Decentralized Cloud Storage network.

Table of contents

1. Minimal system requirements

2. Build from source

   • 2.1. Install Go

   • 2.2. Download and compile ADCS Testnet

   • 2.3. Cross compiling

3. Troubleshooting

4. Getting started

   • 4.1. Usage

   • 4.2. Some things to try

   • 4.3. HTTP/RPC clients

   • 4.4. Troubleshooting

1. Minimal system requirements

Note: Make sure to go through PREREQUISITES.md before installation.

Kubo runs on most Linux, macOS, and Windows systems. For optimal performance, we recommend at least 6 GB of RAM and 2 CPU cores (more is ideal, as Kubo is highly parallel).

Larger pinsets require additional memory, with an estimated $\approx 1\text{ GiB}$ of RAM per $20$ million items for reproviding to the DHT.

Warning: Systems with less than the recommended memory may experience instability, frequent OOM errors or restarts, and missing data announcement (reprovider window), which can make data fully or partially inaccessible to other peers. Running Kubo on underprovisioned hardware is at your own risk.

2. Build from source

2.1. Install Go

Building Kubo requires Go v1.24.

If you need to update, download the latest version of Go.

You'll need to add Go's binary directories to your $PATH environment variable. Add these lines to your shell profile (e.g., ~/.profile or /etc/profile for system-wide):

export PATH=$PATH:/usr/local/go/bin
export PATH=$PATH:$GOPATH/bin

(If you run into trouble, see the Go install instructions).

2.2. Download and compile ADCS Testnet

Kubo's build system requires Go and some standard POSIX build tools:

• GNU make

• Git

• GCC (or some other Go-compatible C Compiler) (optional)

1. Clone the repository and navigate into the directory:

   $ git clone https://github.com/autheo-network/adcs-kubo.git
   $ cd adcs-kubo
   

2. Install the binary:

   $ make install
   

   Alternatively, you can run make build to build the binary (storing it in cmd/ipfs/adcstestnet) without installing it.

NOTE: If you get an error like "fatal error: stdlib.h: No such file or directory", you're missing a C compiler. Re-run make with CGO_ENABLED=0 or install GCC.

• To build without GCC, use:

  make build CGO_ENABLED=0
  

2.3. Cross compiling

Compiling for a different platform is simple:

make build GOOS=myTargetOS GOARCH=myTargetArchitecture

3. Troubleshooting

• Windows: Separate instructions are available for building on Windows.

• Git: git is required in order for go get to fetch all dependencies.

• Go Version: Package managers often contain out-of-date Go packages. Ensure that go version reports at least 1.10.

• Development Dependencies: If you are interested in development, install the development dependencies as well.

• Command Completions: Shell command completions can be generated with one of the adcstestnet completion subcommands. Read docs/command-completion.md to learn more.

4. Getting started

4.1. Usage

To start using ADCS Testnet, you must first initialize ADCS Testnet's config files on your system. This is done with adcstestnet init.

See adcstestnet init --help for information on the optional arguments it takes. After initialization is complete, you can use adcstestnet mount, adcstestnet add, and any of the other commands to explore.

4.2. Some things to try

To perform a basic check that adcstestnet is working locally:

1. Create a file:

   echo "hello world" > hello
   

2. Add the file to ADCS:

   adcstestnet add hello
   

   (This should output a hash string that looks something like: # QmT78zSuBmuS4z925WZfrqQ1qHaJ56DQaTfyMUF7F8ff5o)

3. Retrieve the file content:

   adcstestnet cat <that hash>
   

4.3. HTTP/RPC clients

For programmatic interaction with Kubo, see our list of HTTP/RPC clients.

4.4. Troubleshooting

If you have previously installed ADCS Testnet and are running into problems getting a newer version to work, try deleting (or backing up somewhere else) your ADCS Testnet config directory (~/.adcstestnet by default) and rerunning adcstestnet init. This will reinitialize the config file to its defaults and clear out the local datastore of any bad entries.