If you pay attention to new web dev news, you’ve probably recently heard about Vapid. The creators have billed it as “an intentionally simple content management system built on the idea that you can create a custom dashboard without ever leaving the HTML.” Of course, the idea of creating a custom dashboard via your markup is not exactly new. Perch CMS, launched in 2009, also has what I call a “generative dashboard,” too. There may be others.

While Perch advertises itself as “the really little content management system” that’s easy to learn, it comes with a host of features baked in. I’ve used Perch and found it to have a relatively shallow learning curve. You do need to know some PHP to implement custom functionality. But it is extensible and customizable.

Vapid is a bit different. It really is quite simple (not an insult to any degree). It uses sqlite to store and retrieve your data, but there’s no server-side scripting language you’ll need to wrestle with. From what I can tell, you really do access its features purely through your markup. That does feel new. I don’t think there’s anything quite like it on the market.

But I digress.

We’re supposed to be talking about getting it up and running on WSL Ubuntu. Here are the official installation instructions:

npm install -g vapid-cli
vapid new path/to/project/folder
cd path/to/project/folder
vapid start

Seems simple enough, but definitely didn’t work for me. I should say at the outset, I’m no command line wizard. I get by, but I figure most things out by trial and error (and a fair bit of googling).

Installing vapid-cli

The first order of business is to install the vapid-cli. That’s where my troubles started. But try it anyway. Your mileage may vary from mine.

npm install -g vapid-cli

This failed for me.

bcrypt error

The first error I encountered was with bcrypt (a password hashing function). The error might look something like this for you.

> bcrypt@2.0.1 install /usr/local/lib/node_modules/vapid-cli/node_modules/bcrypt
> node-pre-gyp install --fallback-to-build


npm ERR! errno 1
npm ERR! bcrypt@2.0.1 install: `node-pre-gyp install --fallback-to-build`
npm ERR! Exit status 1
npm ERR!
npm ERR! Failed at the bcrypt@2.0.1 install script.

This doesn’t appear to be a vapid-cli issue per se. But it was an issue for me nonetheless.

bcrypt error solution

The solution? Add the --unsafe-perm configuration parameter to the above installation command. Thus:

npm install -g vapid-cli --unsafe-perm

Admittedly, that sounds a bit, shall we say, unsafe. But it just means that the install script will be run as root. If you trust the folks at Vapid (and I guess I do), this isn’t that big of a deal. Plus, it’s the only solution that got me over the bcrypt hump.

With any luck, after running the above, you’ll have the vapid-cli successfully installed.

Now, go ahead and give this a whirl:

vapid new path/to/project/folder

The directory you specified should now be created and populated with the base Vapid install. (I don’t recall any errors at this step; hopefully, you won’t have any either.)

Attempting to start the server

cd into the directory you just created and try to start the server:

vapid start . 

sqlite3 error

If your setup is anything like mine, this will fail with the following error:

ERROR: Please install sqlite3 package manually

But before you go off and do just that, listen to my tale of woe. As far as I can figure out, this is an unnecessary rabbit trail that leads to nowhere.

Yeah, I fell for it. I installed sqlite3 as many ways as I could find to do so. I installed with npm. It failed. I installed with the APT (Advanced Package Tool) cli. It failed again. I marked the package as manually installed (apt-mark manual sqlite3). It was already so marked. Failure again. Nothing worked.

Spoiler alert: I finally ended up removing sqlite3 via npm and APT. You most likely do not need to install them in the first place.

sqlite3 error solution

What I’m about to share probably isn’t really a solution, but a workaround. Still, it did work for me. In response to another user having the same issue, Scott Robin (co-creator of Vapid) suggested trying to start the server with the start script.

npm start

In desperation, I did just that.


> wwd@ start /mnt/path/to/project/folder
> vapid start .
==> Starting the development server...
==> Watching for changes in /mnt/path/to/project/folder
View your website at http://localhost:3000
Ctrl + C to quit


Vapid Welcome Screen

When all else fails…

Hopefully, you now have Vapid up and running. But if you don’t, all is not lost. You may need to purge your node_modules directory and run npm install in the root directory of your project and try the last step again.

Hit me up on Twitter if none of this worked. I did lots of other things in the process of trying to get Vapid running (most of them too boneheaded to mention here). But some of those steps may be necessary on your end, too. I’ll do my best to help out.

Vapid looks like a lot of fun. I plan to do an in-depth review in the near future when I’ve had a chance to kick the proverbial tires a bit.

Good luck!

Update (10/08/2018)

So, I resintalled vapid-cli and created a new project. Now, somehow, this …

vapid start . 

… works as advertised.

Good news.