github.com/keltia/go-ipfs@v0.3.8-0.20150909044612-210793031c63/README.md (about) 1 # ipfs implementation in go. 2 [![GoDoc](https://godoc.org/github.com/ipfs/go-ipfs?status.svg)](https://godoc.org/github.com/ipfs/go-ipfs) [![Build Status](https://travis-ci.org/ipfs/go-ipfs.svg?branch=master)](https://travis-ci.org/ipfs/go-ipfs) 3 4 Ipfs is a global, versioned, peer-to-peer filesystem. It combines good ideas from 5 Git, BitTorrent, Kademlia, SFS, and the Web. It is like a single bittorrent swarm, 6 exchanging git objects. IPFS provides an interface as simple as the HTTP web, but 7 with permanence built in. You can also mount the world at /ipfs. 8 9 For more info see: https://github.com/ipfs/ipfs 10 11 Please put all issues regarding IPFS _design_ in the 12 [ipfs repo issues](https://github.com/ipfs/ipfs/issues). 13 Please put all issues regarding go IPFS _implementation_ in [this repo](https://github.com/ipfs/go-ipfs/issues). 14 15 ## Install 16 17 The canonical download instructions for IPFS are over at: http://ipfs.io/docs/install 18 19 ## Install prebuilt packages 20 21 We use [gobuilder.me](https://gobuilder.me), a great service that automatically builds a release on every commit. 22 23 You can see the latest builds for your platform at these links: 24 25 - [`release` - the last released version](https://gobuilder.me/github.com/ipfs/go-ipfs/cmd/ipfs?branch=release) **<-- recommended** 26 - [`master` - development, stable](https://gobuilder.me/github.com/ipfs/go-ipfs/cmd/ipfs?branch=master) 27 28 From there: 29 - click "Download" on the build for your platform 30 - open/extract the archive 31 - move `ipfs` to your path (`install.sh` can do it for you) 32 33 34 ## Build from Source 35 36 ### Prerequisite: Install Go 37 38 First, you'll need go. If you don't have it: [Download Go 1.4+](https://golang.org/dl/). 39 40 You'll need to add Go's bin directories to your `$PATH` environment variable e.g., by adding these lines to your `/etc/profile` (for a system-wide installation) or `$HOME/.profile`: 41 ``` 42 export PATH=$PATH:/usr/local/go/bin 43 export PATH=$PATH:$GOPATH/bin 44 ``` 45 46 (If you run into trouble, see the [Go install instructions](http://golang.org/doc/install)) 47 48 ### Download + Compile IPFS 49 50 Then simply: 51 52 ``` 53 go get -u github.com/ipfs/go-ipfs/cmd/ipfs 54 ``` 55 56 NOTES: 57 58 * `git` is required in order for `go get` to fetch 59 all dependencies. 60 * Package managers often contain out-of-date `golang` packages. 61 Compilation from source is recommended. 62 * If you are interested in development, please install the development 63 dependencies as well. 64 * *WARNING: older versions of OSX FUSE (for Mac OS X) can cause kernel panics when mounting!* 65 We strongly recommend you use the [latest version of OSX FUSE](http://osxfuse.github.io/). 66 (See https://github.com/ipfs/go-ipfs/issues/177) 67 * For more details on setting up FUSE (so that you can mount the filesystem), see the docs folder 68 * Shell command completion is available in `misc/completion/ipfs-completion.bash`. Read [docs/command-completion.md](docs/command-completion.md) to learn how to install it. 69 * See the [init examples](https://github.com/ipfs/examples/tree/master/examples/init) for how to connect IPFS to systemd or whatever init system your distro uses. 70 71 72 ## Usage 73 74 ``` 75 USAGE: 76 77 ipfs - global p2p merkle-dag filesystem 78 79 ipfs [<flags>] <command> [<arg>] ... 80 81 BASIC COMMANDS 82 83 init Initialize ipfs local configuration 84 add <path> Add an object to ipfs 85 cat <ref> Show ipfs object data 86 get <ref> Download ipfs objects 87 ls <ref> List links from an object 88 refs <ref> List hashes of links from an object 89 90 DATA STRUCTURE COMMANDS 91 92 block Interact with raw blocks in the datastore 93 object Interact with raw dag nodes 94 file Interact with Unix filesystem objects 95 96 ADVANCED COMMANDS 97 98 daemon Start a long-running daemon process 99 mount Mount an ipfs read-only mountpoint 100 resolve Resolve any type of name 101 name Publish or resolve IPNS names 102 dns Resolve DNS links 103 pin Pin objects to local storage 104 repo gc Garbage collect unpinned objects 105 106 NETWORK COMMANDS 107 108 id Show info about ipfs peers 109 bootstrap Add or remove bootstrap peers 110 swarm Manage connections to the p2p network 111 dht Query the dht for values or peers 112 ping Measure the latency of a connection 113 diag Print diagnostics 114 115 TOOL COMMANDS 116 117 config Manage configuration 118 version Show ipfs version information 119 update Download and apply go-ipfs updates 120 commands List all available commands 121 122 Use 'ipfs <command> --help' to learn more about each command. 123 124 125 ``` 126 127 ## Getting Started 128 129 See also: http://ipfs.io/docs/getting-started/ 130 131 To start using ipfs, you must first initialize ipfs's config files on your 132 system, this is done with `ipfs init`. See `ipfs init --help` for information on 133 the optional arguments it takes. After initialization is complete, you can use 134 `ipfs mount`, `ipfs add` and any of the other commands to explore! 135 136 ### Some things to try 137 138 Basic proof of 'ipfs working' locally: 139 140 echo "hello world" > hello 141 ipfs add hello 142 # This should output a hash string that looks something like: 143 # QmT78zSuBmuS4z925WZfrqQ1qHaJ56DQaTfyMUF7F8ff5o 144 ipfs cat <that hash> 145 146 147 ### Docker usage 148 149 An ipfs docker image is hosted at [hub.docker.com/r/jbenet/go-ipfs](http://hub.docker.com/r/jbenet/go-ipfs). 150 To make files visible inside the container you need to mount a host directory 151 with the `-v` option to docker. Choose a directory that you want to use to 152 import/export files from ipfs. You should also choose a directory to store 153 ipfs files that will persist when you restart the container. 154 155 export ipfs_staging=</absolute/path/to/somewhere/> 156 export ipfs_data=</absolute/path/to/somewhere_else/> 157 158 Start a container running ipfs and expose ports 4001, 5001 and 8080: 159 160 docker run -d --name ipfs_host -v $ipfs_staging:/export -v $ipfs_data:/data/ipfs -p 8080:8080 -p 4001:4001 -p 5001:5001 jbenet/go-ipfs:latest 161 162 Watch the ipfs log: 163 164 docker logs -f ipfs_host 165 166 Wait for ipfs to start. ipfs is running when you see: 167 168 Gateway (readonly) server 169 listening on /ip4/0.0.0.0/tcp/8080 170 171 (you can now stop watching the log) 172 173 Run ipfs commands: 174 175 docker exec ipfs_host ipfs <args...> 176 177 For example: connect to peers 178 179 docker exec ipfs_host ipfs swarm peers 180 181 182 Add files: 183 184 cp -r <something> $ipfs_staging 185 docker exec ipfs_host ipfs add -r /export/<something> 186 187 Stop the running container: 188 189 docker stop ipfs_host 190 191 #### Docker usage with VirtualBox/boot2docker (OSX and Windows) 192 193 Since docker is running in the boot2docker VM, you need to forward 194 relevant ports from the VM to your host for ipfs act normally. This is 195 accomplished with the following command: 196 197 boot2docker ssh -L 5001:localhost:5001 -L 4001:localhost:4001 -L 8080:localhost:8080 -fN 198 199 200 ### Troubleshooting 201 If you have previously installed ipfs before and you are running into 202 problems getting a newer version to work, try deleting (or backing up somewhere 203 else) your ipfs config directory (~/.ipfs by default) and rerunning `ipfs init`. 204 This will reinitialize the config file to its defaults and clear out the local 205 datastore of any bad entries. 206 207 For any other problems, check the [issues list](http://github.com/ipfs/go-ipfs/issues) 208 and if you dont see your problem there, either come talk to us on irc (freenode #ipfs) or 209 file an issue of your own! 210 211 212 ## Contributing 213 214 go-ipfs is MIT licensed open source software. We welcome contributions big and 215 small! Take a look at the [community contributing notes](https://github.com/ipfs/community/blob/master/contributing.md). Please make sure to check the 216 [issues](https://github.com/ipfs/go-ipfs/issues). Search the closed ones 217 before reporting things, and help us with the open ones. 218 219 Guidelines: 220 221 - see the [dev pseudo-roadmap](dev.md) 222 - please adhere to the protocol described in [the main ipfs repo](https://github.com/ipfs/ipfs) and [paper](http://static.benet.ai/t/ipfs.pdf). 223 - please make branches + pull-request, even if working on the main repository 224 - ask questions or talk about things in [Issues](https://github.com/ipfs/go-ipfs/issues) or #ipfs on freenode. 225 - ensure you are able to contribute (no legal issues please-- we'll probably setup a CLA) 226 - run `go fmt` before pushing any code 227 - run `golint` and `go vet` too -- some things (like protobuf files) are expected to fail. 228 - if you'd like to work on ipfs part-time (20+ hrs/wk) or full-time (40+ hrs/wk), contact [@jbenet](https://github.com/jbenet) 229 - have fun! 230 231 ## Todo 232 233 An IPFS alpha version has been released in February 2015. Things left to be done are all marked as [Issues](https://github.com/ipfs/go-ipfs/issues) 234 235 ## Development Dependencies 236 237 If you make changes to the protocol buffers, you will need to install the [protoc compiler](https://code.google.com/p/protobuf/downloads/list). 238 239 ## License 240 241 MIT