Improve installation of DocumentCSS sample app

[adrifolio]

Currently a shell script is used to run the installation of the the sample app (vintage shop) that is used in the Creating a Living Style Guide Tutorial. This script does the following:

• npm install donejs -g
• npm install documentjs -g
• cd vintage-shop
• npm install

Here's a link the the sample app download: https://www.bitovi.com/hubfs/downloads/lsg-docss.zip?t=1502400521202

[BigAB]

The "problem" here, is that in our Installing the sample app video and installation instructions we tell the user to cd in to the directory and execute a shell script with Super User level privileges.

cd ~/Desktop/lsg-docss && sudo ./install.sh

This is super unsafe, and promotes a bad practice.

I think we would be better off to list out the steps above, and maybe even start with instruction on how to install node.js correctly so you don't need sudo (as @Alfredo-Delgado pointed out https://www.nearform.com/blog/nodejs-sudo-free/) We cold also add a section about what to do if it didn't work. But, yeah, that is a lot of install friction.

If we want to lower the install friction, I think optimally we could just give them an app to install, like an electron app with a GUI to do DocumentCSS things. Or even as a comprimise an executable that packages node, so that they only have to install the executable (https://github.com/zeit/pkg)

I would love to help with this. Only time is my enemy, as I don't have enough of it to do the things I want, but I am eager to help at least.

[adrifolio]

Given that our audience in this case are primarily designers, going through a series of technical instructions would not work. That's why I resorted to the script.

An electron app would be great, and is something I have documented as a pipe dream here: https://github.com/bitovi/incubit/issues/10 and in a more short term approach here: https://github.com/bitovi/documentcss/issues/56

[tomgreever]

I think @BigAB's biggest concern is the use of sudo which may not be needed for most people. We can remove that from the command, with an asterisk that if they get errors during installation their best bet might be to use sudo and then link to that article for more info. That way, if they decide to add sudo, it's on them.

[adrifolio]

So installing DoneJS is required as part of this, which according to the docs it needs to be installed using -g, which requires of super user access. Is there are way of installing DoneJS without that flag?

[chasenlehara]

I would encourage people to fix the permission issues instead of using sudo.

This page is a handy reference: https://docs.npmjs.com/getting-started/fixing-npm-permissions

In particular, whenever I run into a permissions issue with npm, I run the second command listed under Option 1 from that page:

sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

[Alfredo-Delgado]

If you're not having the user work with donejs generators then you should be fine skipping that. Just have them npm run develop etc. instead of relaying that from the donejs cli?

[adrifolio]

@Alfredo-Delgado that would work. Would also need to update documentjs -g to use ./node_modules/.bin/documentjs.

[BigAB]

@adrifolio

needs to be installed using -g, which requires of super user access

It does not luckily, for example I never used sudo to install node, and have never used sudo to install a global package, so if a user needs sudo, something has gone wrong.

I use NVM now, so it's hard to compare to a manual install, but if I recall correctly I installed node from the installer binary and still never had to use sudo for either my install or global package installs.

Would also need to update documentjs -g to use ./node_modules/.bin/documentjs.

Funny thing about npm scripts is that if you have a script in your package json like:

 "scripts": {
    "document": "documentjs"
  },

It will first check if you have documentjs installed locally, (technically it looks for an executable in node_modules/.bin/) and runs that, if it does not exist tries to run it from the global install. (that's actually a simplification of what it does, but that's the only 2 cases I have ever run into anyway)

So you wouldn't have to change the npm script.

[adrifolio]

@BigAB this is good to know. I was going by what is documented on both donejs and documentjs sites.

So it sounds that these commands should work:

npm install donejs npm install documentjs npm install

And once installed:

• npm run develop
• In a new tab enter: documentjs

I'm gonna try them and will update the post. I'm also gonna remove the script all together and instead point people to get the files from github and follow the commands.

[adrifolio]

Ok, so I gave it a shot. And if I don't use -g the packages it tries to put it in /usr/local/lib which is a system protected directory (https://support.apple.com/en-us/HT204899), so npm asked me for sudo access. So @chasenlehara if I'm following correctly, it would be necessary for users to fix npm permissions as indicated here https://docs.npmjs.com/getting-started/fixing-npm-permissions?

This is probably something that most devs would be comfortable doing, but I honestly would feel discouraged of having to do this if I'm just wanting to follow a tutorial.

[Alfredo-Delgado]

I would feel more comfortable nudging toward a correct install rather than fixing permissions. With the former we're not making any assumptions other than they're not meeting prerequisites. The later feels like opening a can of worms since we don't know just how badly/deeply/wide their problems may go.

[adrifolio]

Totally @Alfredo-Delgado. How would a correct install look like?

[Alfredo-Delgado]

I continue to flog nvm. ☝️ https://www.nearform.com/blog/nodejs-sudo-free/

It keeps things within the user's home directory and they end up with additional functionality.

[adrifolio]

Oh man! But that adds 3 more steps of a dependency unrelated to the tutorial. There are no other ways around it? Why is using sudo a bad practice and more insecure? Would think that the fact that a password is asked, would make it more secure (similar to when installing an GUI application).

[BigAB]

Okay, so after installing node (which ever way) you should only have to:

• either download or clone the vintage repo
• cd into that directory
• in the terminal npm install (wait for that to finish)
• npm run develop
• then in a new terminal window/tab npm run document

You don't need donejs at all do you? (or is there stuff later where you do need it?)

Just FYI, If you do these commands... npm install donejs
npm install documentjs
npm install
...in a directory that has a package.json file, like in the vintage-shop directory, it will just install them right there in the node_modules directory. But if the package.json isn't there (ie wherever you run those commands), then it will try to install in /usr/local/lib or wherever it does... and of course -g installs it somewhere else too

[BigAB]

Why is using sudo a bad practice and more insecure?

When you sudo a script (like install.sh) you say, let this script do whatever it wants with full permissions on this computer. It could plant ransomeware, erase important documents, add creepy malware like turning on cameras remotely and sending the video feed somewhere else.

Even when you install an app (on mac at least) it is "sandboxed", it can only affect a certain predetermined space on the disk, it is restricted from accessing certain other parts of the computer and such, but using sudo is basically saying every thing this script does, do it with full access and no protections. from what I understand at least, I am not really a computer guy

[adrifolio]

Hey guys, I sat down with @chasenlehara today and he help me setup this commands for the installation in a more simple way. sudo and global installs have been removed, as well as the use of a script. Also, the download of the sample app links to the Github repo.

The article has been updated with the new commands: https://www.bitovi.com/blog/creating-pages-in-a-living-style-guide

And I will be updated the recorded tutorial soon.

Thanks so much for all of your input and help!