Open Source
January 4th

VIPFS: Getting Started

Anthony C. Budd profile image
Anthony C. Budd

Introduction

In this tutorial I will show you how you can use VIPFS to build a decentralized Vue.js application deployed on IPFS in less than 5 minutes.

This tutorial is also available as a step-by-step video. In this 15min video I go into more depth about the architecture, best practices and use cases for VIPFS.

TLDR;

Installation

First, clone the repository and then cd into the project

$ git clone [email protected]:Ideea-inc/vipfs.git $ cd vipfs

Next, install the required node packages by running

$ npm install

Finally, run the build command to compile the project.

$ npm run build

Now you should have a new directory called `build` in the root of the vipfs project, this is where all of the project’s compiled HTML, JS and CSS is stored.

Development Server

Once you have successfully compiled the project, you will need to set-up the local development server so you can see your project in a browser and deploy it to IPFS. Run the command below to start the Docker containers (see docker-compose.yml)

$ docker-compose up

The first time you run this command it may take a while to download and build the container images. Once the containers are built, you should be able to see two running containers named app and ipfs when you run the command docker ps

To confirm you have set everything up correctly, you should be able to goto http://localhost:8000 and see the default VIPFS welcome screen.

VIPFS Welcome Screen

Let’s Build!

Now we have got VIPFS set-up, we can start building. Let’s create a simple website that just has a bio page with a downloadable link. VIPFS comes with a few helpful templates, one is a bio page.

Tip: In a new terminal window, run the command npm run watch to automatically compile the project on each file change.

Routes

First edit the routes.js file located at vipfs/src/routes.js Remove all of the existing routes except the route for bio page and modify the path parameter so the bio page is the webroot. Now your app will use the bio page template instead of the home page template.


Storage

All modern web apps need the ability to host files, play videos and display images. To make this as easy as possible, VIPFS has a directory in the root of the project called storage.

The storage directory is automatically copied into the build directory so when you publish your project all of the contents will also be published to IPFS.

For this tutorial you will need to copy a profile image, header image and a downloadable file into the storage directory.

Tip: When linking to stored files in your code do not start the URL with any prefixes like http, https or /. Just reference the stored file relatively as shown in this example <img src="storage/images/example.png">. This is because when you try and access your website via an IPFS gateway, the url (more specifically, the path) will always start with your hash. Not doing this, will work locally but the urls will 404 once deployed.

Template

Now let’s modify the bio page to display your name, title and images. Open vipfs/components/bio.vue and update the name and title (line 7 in the gist below) and write a small bio (line 17). Then update the src attributes in the img tags to reference your header image and profile image (lines 3 and 5).



Deployment

Last but definitely not least we can deploy your application to IPFS. Thanks to some handy work with Docker, NPM and IPFS. This command will add the build directory to IPFS and publish that IPNS name.

$ npm run publish

This command will return a IPFS hash which will look something like this Qmxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The IPFS docker container is configured to provide you with a local IPFS gateway. To see your project deployed on IPFS, all you have to do is head to http://localhost:8080/ipns/Qmxxxxxxxx...

VIPFS Welcome Screen

The IPFS container will also seed your application to the network meaning you should be able to access your project over the main ipfs public gateway too by going to: https://gateway.ipfs.io/ipns/Qmxxxxxxxx... It may take a while for the gateway to find your hash but be patient it will find it eventually. Once you can successfully load your project over the IPFS gateway, stop your local dev server and refresh the page, the gateway should still return your web app. Congratulations, you have made your first decentralized application with VIPFS!

Don't forget to star the project on GitHub. If you have any questions or comments please feel free to get in touch!