w3up makes IPFS more accessible than ever before, bringing the scalability and responsiveness of cloud-native architecture to the world of content-addressed, verifiable data that IPFS enables.
If you're already using IPFS, you can take advantage of w3up today to make your data stack more responsive and reliable. Because w3up builds on the Elastic IPFS stack, it's fully interoperable with traditional IPFS implmentations like kubo (formerly go-ipfs), js-ipfs, and rust-ipfs. This makes it easy to incrementally adopt w3up without needing to completely replace your existing IPFS code and processes.
This guide will cover a few key IPFS use cases that you might currently be using, along with the w3up equivalent. Hopefully this will give you some ideas about how w3up could fit into your current stack. If you have questions about things not covered here, please reach out!
Sharing files
IPFS is often used to share files with others on the internet, and w3up makes it easier than ever.
Just replace ipfs add <your-file> with w3 up <your-file>, and the w3up service will take care of making the data available to the IPFS network.
Unlike the ipfs add command, you don't need to keep an IPFS node running to make sure the file is available, and there's no need to remotely "pin" the content with another service. Once the w3up service has received your data, the Elastic IPFS stack will take care of the rest.
Publishing web sites
IPFS is one of the cornerstones of the decentralized web and Web3 movements, and a key part of that is the ability to publish web content on IPFS. Browsers like Brave and Opera enable people to directly visit ipfs:// URLs with content verification built in, and HTTP gateways bridge the gap and make IPFS content available to any browser.
Using w3up to publish your site is as simple as running w3 up <your-site-directory>, where <your-site-directory> contains an index.html file and any other content you might need. Just make sure that you use relative URLs when you link from one page to another, since the root URL will depend on the content address of the entire site.
Once your site is uploaded, you can use w3name to create a verfiable "pointer" to your site. Using w3name gives you a stable URL that only you control, without needing to depend on DNS or any other trusted third party. In fact, you don't even need to trust the w3name service, since it's not possible for the service to tamper with your w3name updates.
Distributing public datasets
One of the guiding principles of IPFS is to enable and preserve access to vital public data, especially scientific research data. This domain is especially well-suited to IPFS because the built-in content verfication allows you to create stable links to the exact dataset used in your original research. This is huge for reproducability, and it gives peer reviewers the tools they need to properly evaluate your work.
w3up lets you leverage IPFS for research data without requiring you to maintain an IPFS node or contract with a pinning service. Once again, w3 up <your-dataset> is all that you need.
Getting started with w3cli
This guide will use the w3 command line tool to interact with the w3up service. If you're writing a JavaScript application, check out our guide to getting started with the w3up-client library.
You can install the w3 command by globally installing the @web3-storage/w3cli package using NPM, the package manager for NodeJS.
npm install -g @web3-storage/w3cli
Once the package is installed, you should be able to run the w3 --help command to see the help text. Let's walk through the basics of signing up and using w3 to upload files
First, we need to create an "space," which is a secure, unique id that is associated with your uploads. Use the w3 space create command, optionally passing in a friendly name (we're using "Documents" below:
w3 space create
did:key:z6MkvjhcXtyKA7qsU8wwEwf9qZSUZ9FkksG4xLEwofKGUe9S
Your ID should look similar to the one above, but with a different value after the did:key: part.
Before you can upload, you need to register your new space with the w3up service.
Using the w3 space register command, we can associate the new space with an email address. This also grants your local "agent" access to the w3up upload services using a UCAN delegation.
w3 space register your-address@email-provider.net
The w3 space register command will wait for you to check the activation email and click the registration link inside. Once you click the link, you should see a success message, and you're ready to go!
Translating common IPFS commands to w3up
Once you've registered, you're ready to use w3 to manage your IPFS data. Let's take a look at the most common operations and see how they compare to kubo (formerly known as go-ipfs).
Adding files and directories
To add files to IPFS using kubo, you would use the ipfs add command, passing in the path to a file or directory. This will add the data to your local IPFS repository and make it available on the network as long as your computer is online.
To switch to w3up, just replace ipfs add with w3 up. Once the upload is complete, you can turn your computer off, and your files will still be available thanks to Elastic IPFS.
Retrieve content by CID
Fetching data from the IPFS peer-to-peer network using kubo is most commonly done with the ipfs get command, which downloads the content for a given Content Identifier (CID).
If you've already got a workflow that uses ipfs get, you don't have to change anything to fetch data stored with w3up. Since Elastic IPFS is compatible with the peer-to-peer Bitswap protocol, anything you store with w3up is retrievable from any IPFS peer using the same ipfs get command you're familiar with.
As an alternative to Bitswap, you can download IPFS data from a web browser or other client applications using an HTTP gateway. Gateways translate between the HTTP protocol used by browsers and the peer-to-peer Bitswap protocol.
To fetch from a gateway, make a URL of the form https://$CID.ipfs.$GATEWAY_HOST, replacing $GATEWAY_HOST with the domain name of the gateway, and $CID with the root CID of your content. You can use any public IPFS gateway to fetch data stored using w3up, but we recommend using our own gateway at w3s.link, which can be faster for content served from Elastic IPFS.
You can also add filenames to the end of the URL to "drill down" into the directory structure of your uploads. For example, the following URL links directly to a file named not-distributed.jpg:
Removing the filename from the URL will take you to a directory listing page instead:
https://bafybeidd2gyhagleh47qeg77xqndy2qy3yzn4vkxmk775bg2t5lpuy7pcu.ipfs.w3s.link
List your IPFS data
Adding files to your local IPFS repository with kubo causes them to be "pinned," which makes sure that they don't get removed if you're ever low on disk space. You can get a list of the content you've pinned using the ipfs pin ls command, which lists the CIDs of the files you've added, along with anything from other users that you might have pinned manually.
With w3up, you can get a list of all the content you've added using w3 list, which prints the CIDs for everything you've uploaded to your account.
% w3up list
bafybeiafg7mms5mxdcbxq52l3gdyjujlmb7vkj52g5fprclcb3jjz6bkiq
bafybeibn2iq7zh74k6anntvo4vxehvnlp6j37galv2u5sy363ofc5j2wwe
bafybeidwm2gfdrx2yjnzdqnw7n3a2er2vo5uwv6w5otjfbyboeoq3jfiby
bafybeiefiddap3p3z3p3obatviipgda2us3umt4uxeh2trrni5pt6bfc6e
Building apps, IPFS style
One of the reasons to use w3up, in addition to super-simple cloud storage workflows, is the ease of building mobile and web apps using the web3.storage UCAN based upload API. Get started writing apps with w3ui, our front end component library, and enable new ways for users to own their data with our UCAN account delegation capabilities.
You can try out the w3ui widget code samples live on the site's sandbox, to get a feel for how IPFS on web3.storage can work for your mobile and web apps.
