Add new tutorial draft #412

caldav · 2017-11-14T07:56:55Z

~~This is a draft.~~
How to snap a website with Electron. Ready for review.

Demo: http://tutorials.ubuntu.com-pr-412.run.demo.haus/tutorial/snap-a-website

Note that this tutorial is not relying on the electron-builder snap integration since it doesn't use cleanbuild and produces broken snaps on 17.10.

webteam-app · 2017-11-14T07:59:23Z

Starting demo at: http://tutorials.ubuntu.com-pr-412.run.demo.haus/

evilnick · 2017-11-14T15:34:23Z

tutorials/packaging/snap-a-website.md

+## Overview
+Duration: 1:00
+
+Turning your website into a desktop integrated app is a relatively simple thing to do, but distributing it as such and making it noticeable in app stores is another story. This tutorial will show you how to leverage Electron and snaps to create a website-based desktop app from scratch and publish it on a multi-million users app store shared between many Linux distributions.


publish it on a multi-million user
Also, do we want to say 'app store', I think just 'store would do fine

evilnick · 2017-11-14T15:36:30Z

tutorials/packaging/snap-a-website.md

+cd app
+```
+
+With the `npm` command, we can install electron and electron-builder inside the current directory. They will provide the framework and tooling to build our app binary.


I get that 'electron' here is used as the name of the package - maybe it would make more sense to italicise these?

evilnick · 2017-11-14T15:41:22Z

tutorials/packaging/snap-a-website.md

+summary: Destroy your opponent's castle to win!
+description: |
+ Play online or against a bot, click and drag cards to your side of the field
+ to deploy powerful building and units to attack your ennemy.


buildings? enemy?

evilnick · 2017-11-14T15:42:06Z

tutorials/packaging/snap-a-website.md

+    plugin: nodejs
+```
+
+A part needs a `source`, to declare where to pull its code from, relatively to our project directory. In this case: `app/`.


evilnick · 2017-11-14T15:42:34Z

tutorials/packaging/snap-a-website.md

+
+A part needs a `source`, to declare where to pull its code from, relatively to our project directory. In this case: `app/`.
+
+The `plugin` is the type of part we are building: it's a `nodejs` app. Which means snapcraft will use `nodejs` when building the snap, and bundle it (among other related dependencies) in the final snap package.


This means snapcraft...

evilnick · 2017-11-14T15:44:14Z

tutorials/packaging/snap-a-website.md

+summary: Destroy your opponent's castle to win!
+description: |
+ Play online or against a bot, click and drag cards to your side of the field
+ to deploy powerful building and units to attack your ennemy.


as previously 😄

evilnick · 2017-11-14T15:45:24Z

tutorials/packaging/snap-a-website.md

+
+### Icon and desktop file
+
+The last bit of packaging we need is an icon and a `<app>.desktop` file so desktop environments recognize our app as such. The icon and the desktop file will be picked up by snapcraft and handled accordingly by putting them in a `snap/gui/` directory.


you can either have "so desktop environments will" or "so that desktop environments..."

evilnick · 2017-11-14T15:46:15Z

tutorials/packaging/snap-a-website.md

+
+Some details about the output you are now looking at:
+
+1. The container is created (if it's the first time you create an Ubuntu 16.04 container on this computer, an Ubuntu image is downloaded as part of the process)


doesn't codelabs support proper markdown lists? These should all be '1.'

Codelabs do, I obviously don't :D

test comment

evilnick

a few more spelling and grammar bits

evilnick · 2017-11-14T16:59:33Z

tutorials/packaging/snap-a-website.md

+
+## What next?
+
+What a journey! If this is the first time you installed a snap or created a LXD container, you may have realized that most of the time spent in this tutorial was looking at downloads! When the tools have been used once, things get much faster, since most of them don't have to be installed or initialized anymore.


realised, initialised

I would put here the paragraph about releasing.

evilnick · 2017-11-14T17:01:17Z

tutorials/packaging/snap-a-website.md

+
+Positive
+: **What does `--dangerous` mean?**
+The `--dangerous` flag indicates that you are acknowledging that this snap could be unsafe to install, this is necessary when the snap didn't went through store security checks. Since you are the developer of the snap, you know it's safe, but the snap command doesn't and would prevent the install if you omitted the flag.


"when the snap hasn't been through..."

evilnick · 2017-11-14T17:01:43Z

tutorials/packaging/snap-a-website.md

+
+### Icon and desktop file
+
+The last bit of packaging we need is an icon and a `<app>.desktop` file so that desktop environments recognize our app as such. The icon and the desktop file will be picked up by snapcraft and handled accordingly by putting them in a `snap/gui/` directory.


come-maiz · 2017-11-14T18:39:12Z

tutorials/packaging/snap-a-website.md

+* **nodejs**: A JavaScript runtime, that will also provide the `npm` command we are going to use
+
+```bash
+sudo apt install curl build-essential libgconf2-4


libgconf2-4 is the only one not explained. I'm left wondering what is it for, so it might be better to explain all of them above.

come-maiz · 2017-11-14T18:45:57Z

tutorials/packaging/snap-a-website.md

+
+```bash
+npm install electron --save-dev --save-exact
+npm install electron-builder --save-dev


stack Error: not found: make <- one missing dependency.

Actually, two: make: g++: Command not found

That's odd, build-essential should have installed make and g++.

Yeah, apparently I missed that command. 😔

come-maiz · 2017-11-14T18:55:25Z

tutorials/packaging/snap-a-website.md

+## Electron metadata (package.json)
+Duration: 2:00
+
+Now that we have a working app, we need to turn it into an executable file. To do this, we are going to use a dependency we installed earlier: electron-builder. To build the executable, it requires a `package.json` file containing some basic metadata.


This is a little slow to read. What about:
Now that we have a working app, we are going to turn it into an executable file using a dependency we installed earlier: electron-builder.

come-maiz · 2017-11-14T18:56:37Z

tutorials/packaging/snap-a-website.md

+}
+```
+
+As you can see, all entries are self-explicit. We have a name, a version, the location of our app, how to start the app using the `electron` command and instructions to build a linux executable without packaging (`dir` stands for `directory`).


I think it's self-explanatory, not self-explicit.

Hah, missed this one, thanks

come-maiz · 2017-11-14T19:14:20Z

tutorials/packaging/snap-a-website.md

+Then we need to provide the following information:
+
+* **The command (or commands) to build the app**:
+  Since we are using electron-builder and simply calling `electron-builder` in the project will pick up details from our `package.json` file and generate an executable.


There's something wrong in this sentence. Who will pick up the details?

come-maiz · 2017-11-14T19:15:56Z

tutorials/packaging/snap-a-website.md

+
+### Let's recap
+
+We have added general metadata to ensure our app appears correctly in stores and parts to ensure it bundles our executable and its dependencies in a confined package. But we are still missing one very important bit: the launcher.


Maybe a missing comma here, after "stores"?

come-maiz · 2017-11-14T19:16:54Z

tutorials/packaging/snap-a-website.md

+
+## Launcher and desktop integration
+
+To launch the app, the snap needs to know which command to run. This is done within an `apps` section in the `snapcraft.yaml`, where we are going to declare: the name of the app, the command to run and which access we want the app to be granted outside of the snap confinement.


There's a ":" after declare

come-maiz · 2017-11-14T19:18:32Z

tutorials/packaging/snap-a-website.md

+```yaml
+apps:
+  castlearena:
+    command: env TMPDIR=$XDG_RUNTIME_DIR desktop-launch $SNAP/app/castlearena


This XDG_RUNTIME_DIR should probably be explained. I have no idea what it does there.

come-maiz · 2017-11-14T19:19:46Z

tutorials/packaging/snap-a-website.md

+
+### Icon and desktop file
+
+The last bit of packaging we need is an icon and a `<app>.desktop` file so that desktop environments recognize our app as such. The icon and the desktop file will be picked up by snapcraft and handled accordingly by putting them in a `snap/gui/` directory.


I think it should be "an <app>.desktop file", but maybe @kyrofa can confirm.

come-maiz · 2017-11-14T19:23:43Z

tutorials/packaging/snap-a-website.md

+1. snapcraft pulls the source of each part
+1. ...and downloads all the required dependencies
+1. Each part is built following our instructions
+1. Snapcraft creates a staging directory where the content of our snap is curated based on instructions and parts plugin declarations


"based on instructions" sounds bad. Why don't you just drop "instructions"?

You should probably call it the "stage directory", not staging.

come-maiz · 2017-11-14T19:24:49Z

tutorials/packaging/snap-a-website.md

+1. ...and downloads all the required dependencies
+1. Each part is built following our instructions
+1. Snapcraft creates a staging directory where the content of our snap is curated based on instructions and parts plugin declarations
+1. The staging directory is packed into a snap


That's not completely accurate. The one that is packed is the prime directory.

come-maiz · 2017-11-14T19:25:07Z

tutorials/packaging/snap-a-website.md

+
+`castlearena_0.1_amd64.snap`
+
+Congrats, you made a snap!


^_^ so exciting!

kyrofa · 2017-11-14T19:26:24Z

tutorials/packaging/snap-a-website.md

+
+```bash
+sudo apt install curl build-essential libgconf2-4
+curl -sL https://deb.nodesource.com/setup_9.x | sudo -E bash -


Also, no idea what this command is doing.

Wait for the awesome node snap! nodejs/installer#54
(leave your thumbs up in there :)

come-maiz · 2017-11-14T19:27:18Z

tutorials/packaging/snap-a-website.md

+  `snap try squashfs-root` will mount the directory as if it was an installed snap.
+  You can then run the snap and edit its content at the same time.
+* Enter a shell with the same confinement as the snap to inspect its environment, paths, and see what it sees:
+  `snap run --shell <snap>`


Wouldn't this be better as a link to a tutorial that explains each of them?

come-maiz

very nice work @caldav, thanks!

caldav · 2017-11-15T08:47:44Z

Thanks all!

3DJetengine · 2017-11-16T14:44:28Z

@caldav is there any chance - when you say:

Some command line experience required.

we could link to https://linuxjourney.com/ - command line as a ubu.one link or an ubuntu link ?

all of the links seem to remain in-house.

Add new tutorial draft

b13c13f

caldav added the Don't merge label Nov 14, 2017

caldav added 2 commits November 14, 2017 15:06

Content update

80785af

Version update in package.json

9206432

caldav requested a review from evilnick November 14, 2017 14:12

caldav added 3 commits November 14, 2017 15:19

Update binary name to latest version

f8a7734

Update last page

72b31b7

Merge branch 'master' into packaging-website

cc52e4c

evilnick reviewed Nov 14, 2017

View reviewed changes

caldav added 2 commits November 14, 2017 16:47

Small update

9373b8e

Add screenshots, some fixes and follow feedback

26f2cac

caldav removed the Don't merge label Nov 14, 2017

evilnick approved these changes Nov 14, 2017

View reviewed changes

come-maiz reviewed Nov 14, 2017

View reviewed changes

tutorials/packaging/snap-a-website.md Outdated

`castlearena_0.1_amd64.snap`

Congrats, you made a snap!

Copy link

come-maiz Nov 14, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

^_^ so exciting!

kyrofa reviewed Nov 14, 2017

View reviewed changes

come-maiz reviewed Nov 14, 2017

View reviewed changes

come-maiz suggested changes Nov 14, 2017

View reviewed changes

Feedback fixes

07e24fb

caldav merged commit 1399068 into master Nov 15, 2017

caldav deleted the packaging-website branch December 19, 2017 16:27


		A part needs a `source`, to declare where to pull its code from, relatively to our project directory. In this case: `app/`.

		The `plugin` is the type of part we are building: it's a `nodejs` app. Which means snapcraft will use `nodejs` when building the snap, and bundle it (among other related dependencies) in the final snap package.


		### Icon and desktop file

		The last bit of packaging we need is an icon and a `<app>.desktop` file so desktop environments recognize our app as such. The icon and the desktop file will be picked up by snapcraft and handled accordingly by putting them in a `snap/gui/` directory.


		Some details about the output you are now looking at:

		1. The container is created (if it's the first time you create an Ubuntu 16.04 container on this computer, an Ubuntu image is downloaded as part of the process)


		## What next?

		What a journey! If this is the first time you installed a snap or created a LXD container, you may have realized that most of the time spent in this tutorial was looking at downloads! When the tools have been used once, things get much faster, since most of them don't have to be installed or initialized anymore.


		### Let's recap

		We have added general metadata to ensure our app appears correctly in stores and parts to ensure it bundles our executable and its dependencies in a confined package. But we are still missing one very important bit: the launcher.


		## Launcher and desktop integration

		To launch the app, the snap needs to know which command to run. This is done within an `apps` section in the `snapcraft.yaml`, where we are going to declare: the name of the app, the command to run and which access we want the app to be granted outside of the snap confinement.

Add new tutorial draft #412

Add new tutorial draft #412

Conversation

caldav commented Nov 14, 2017 • edited

webteam-app commented Nov 14, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

evilnick Nov 14, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

evilnick left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

caldav Nov 14, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

come-maiz Nov 14, 2017 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

come-maiz left a comment

Choose a reason for hiding this comment

caldav commented Nov 15, 2017

3DJetengine commented Nov 16, 2017 • edited

caldav commented Nov 14, 2017 •

edited

evilnick Nov 14, 2017 •

edited

caldav Nov 14, 2017 •

edited

come-maiz Nov 14, 2017 •

edited

3DJetengine commented Nov 16, 2017 •

edited