Doc/lepidopter services #68

anadahz · 2016-09-08T18:16:28Z

This PR is based in #60 that contains important documentation and fixes.

hellais · 2016-09-08T18:22:36Z

content/install/lepidopter.md

+that supports automatic discovery of hosts in the local network.
+
+The applications that are bundled with the Bonjour software in Windows:
+


Include a download link to install the software and steps on how a windows user can then use bonjour once it's installed.

Do we really need to add links for these applications that will most probably change in the future?

I think we should say:

If you have any of the following applications installed, then you don't need to do anything. However if you don't then install XXX, where XXX probably should be the Bonjour Print services.

If the links to them change in the future we should update them, but it's important that we give some instructions that a newbie can follow to access their pi.

anadahz · 2016-09-13T11:28:12Z

I have updated the docs based on feedback from @hellais .

* Add documentaton on how to access ooniprobe's WUI and lepidopter's SSH * Add service discovery install instructions for a number of OSes

@hellais

Based on feedback from @hellais

anadahz · 2016-09-19T13:50:08Z

@hellais I made the changes in aaabcee for 012ed0b and also updated the documentation to the reflect the changes of newer lepidopter image build.

darkk · 2016-10-19T21:57:12Z

content/install/lepidopter.md

+(https://get.ooni.torproject.org/lepidopter/lepidopter-v0.3.5-beta-armel.img.xz)
+for a significantly reduced file size compared to the zip archive.
+Note that this will require an extra program to be installed depending on your
+OS.


What do you think about [extra program](http://tukaani.org/xz/) ?

You are right it makes sense to add this.

darkk · 2016-10-19T22:04:57Z

content/install/lepidopter.md

 ```

 You should look for the message `Good signature from "Lepidopter Team (signing
 key)"`:

 ```
-gpg: assuming signed data in `lepidopter-alpha-armel.img.zip'
+gpg: assuming signed data in `lepidopter-v0.3.5-beta-armel.img.zip'
 gpg: Signature made Sun 22 May 2016
 gpg:                using RSA key 0xBA56AC5A53E9C7A4
 gpg: using PGP trust model


I see trailing newline in the paste after gpg: binary signature, digest algorithm SHA512

what about using full fingerprint like --recv-keys 625511968E240F24F6CFD0B6BA56AC5A53E9C7A4 ?

darkk · 2016-10-19T22:10:57Z

content/install/lepidopter.md

@@ -266,7 +266,7 @@ the name of the whole SD card as described above, not just a partition of it
 (for example, sdd, not sdds1 or sddp1, or mmcblk0 not mmcblk0p1).

 ```     
-dd bs=4M if=~/lepidopter-alpha-armel.img of=/dev/sdd
+dd bs=4M if=~/lepidopter-v0.3.5-beta-armel.img of=/dev/sdd


Doesn't one need sudo to run dd against SD card?

The user will be prompted with a Permission denied error in case of access rights.
As someone can destroy a hard disk with dd is better to understand what the command does.

darkk · 2016-10-19T22:15:10Z

content/install/lepidopter.md


-   `xz --decompress --verbose --no-sparse lepidopter-alpha-armel.img.zip`
+   `xz --decompress --verbose --no-sparse lepidopter-v0.3.5-beta-armel.img.zip`


xz can't decompress zip

Why --no-sparse ? Saving 3Gb of zeros looks like a good idea to me.

I recall some issues with different version of dd not parsing correctly sparse files.

darkk · 2016-10-19T22:23:33Z

content/install/lepidopter.md

-archive. Note that this will require an extra program to be installed depending
-on your OS.
+(https://get.ooni.torproject.org/lepidopter/lepidopter-v0.3.5-beta-armel.img.xz)
+for a significantly reduced file size compared to the zip archive.


IMHO exact sizes are better.

Lepidopter image.zip, 254 MB, GPG signature

Lepidopter image.xz, 174 MB, GPG signature

I was hoping to have a link pointing to the latest image file and having inaccurate exact file sizes numbers is not nice.

anadahz · 2016-10-20T16:19:12Z

@darkk thanks for your comments, add fixes in 317a8bb.

hellais · 2016-10-25T17:24:21Z

So I have thought a bit about this and I have the following feedback.

I think the installation instructions for lepidopter should be restructured to take into account the fact that there are two types of users of lepidopter (or maybe even 3):

A user of lepidopter that has gotten it via our partnership program. These from what I can tell are actually the majority of lepidopter users and are people that don't care how to burn the image to an SD card. This user is not technically savvy.
A user of lepidopter that wants to download the image and burn it onto their SD card. These are a minority of users that are quite technically savvy.
(if we include this as well) Power users or developers that want to contribute in some way to the project. Very technically savvy.

In light of this I think the guide should be divided into at least 2 sections.

User guide
How to burn an image

Inside the user guide there should be clear and simple explanations as to how to connect the raspberry pi to the power and internet (maybe even including screenshot). @andresazp showed me the document he created for VI and it looks great.
It should also cover information on how to initialise the pi (answering the informed consent) and check that measurements are being run, by visiting the web UI.

An outline of the User Guide could be:

Setting up the device (covering how to connect it to internet and power, putting in the SD card etc.)
First start (covering how to reach the pi over the network, using lepidopter or lepidopter.local) and answering the informed consent
Checking that everything works (checking that measurements are being run)

The How to burn an image can remain as the current section titled: "Downloading and verifying the Lepidopter Raspberry Pi image"

I would also try to make this guide overall much shorted and where possible point to external resources instead of having so much content in here (for example explaining the tests).

hellais · 2016-10-25T17:37:36Z

I am also thinking that maybe the whole part on burning the image could be tucked inside of another page entirely as it makes the whole guide much less user friendly.

Another comment is that the whole section "Lepidopter services" is far too technical and contains a bunch of information that will not be useful to most cases (why would the normal user care to know that there is a mDNS service for SSH?).

I would tuck this stuff as well inside of some advanced section and try to have a minimal guide that is easy for most users to follow.

The experience we had with real deployment of these is that even just explaining how to plug in a pi into a router and connecting to power can be challenging for some non technically savvy users and since this guide is addressed to them we should take that into account.

anadahz · 2016-10-31T00:44:37Z

@hellais your comments:#68 (comment) and #68 (comment) make sense but they will be better addressed in another PR as we need to make the release announcement of ooniprobe v2.0.0 and WUI (#76) ASAP since the users are still using older versions of lepidopter and ooniprobe.

hellais · 2016-11-11T16:54:34Z

Filed an issue with my feedback.

Merging this into the website.

anadahz mentioned this pull request Sep 8, 2016

Document how to access lepidopter web interface TheTorProject/lepidopter#76

Closed

hellais reviewed Sep 8, 2016
View reviewed changes

anadahz force-pushed the doc/lepidopter-services branch from f31fa8f to 012ed0b Compare September 13, 2016 11:26

anadahz added 6 commits September 19, 2016 10:42

Add doc on how to access ooniprobe WUI, lepidopter SSH

15f5373

* Add documentaton on how to access ooniprobe's WUI and lepidopter's SSH * Add service discovery install instructions for a number of OSes

Fix correct link

2ad3d12

Add troubleshoot section, links, avahi check, spelling fixes

8974893

Based on feedback from @hellais

Add local TLD in the available URLs list

e9edb0a

Fix doc to mention ooniprobe WUI port to 80 (default in lepidopter)

e47fb45

Point to the latest lepidopter release.

b0fa4dc

anadahz force-pushed the doc/lepidopter-services branch from 486fc21 to b0fa4dc Compare September 19, 2016 13:45

Point URL to latest lepidopter release, resize images

4ed06d3

darkk reviewed Oct 19, 2016

View reviewed changes

Doc fixes based on @darkk comments

317a8bb

anadahz mentioned this pull request Oct 31, 2016

Add Lepidopter release blog post, fix link #63

Merged

hellais mentioned this pull request Nov 11, 2016

Improve documentation for raspberry pi installation #82

Closed

hellais merged commit 0cbccd8 into master Nov 11, 2016

hellais deleted the doc/lepidopter-services branch November 11, 2016 16:54

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Doc/lepidopter services #68

Doc/lepidopter services #68

anadahz commented Sep 8, 2016

hellais Sep 8, 2016

anadahz Sep 8, 2016 •

edited

Loading

hellais Sep 8, 2016

anadahz commented Sep 13, 2016

anadahz commented Sep 19, 2016

darkk Oct 19, 2016

anadahz Oct 20, 2016

darkk Oct 19, 2016

anadahz Oct 20, 2016

darkk Oct 19, 2016 •

edited

Loading

anadahz Oct 20, 2016

darkk Oct 19, 2016

anadahz Oct 20, 2016

darkk Oct 19, 2016

anadahz Oct 20, 2016

anadahz commented Oct 20, 2016

hellais commented Oct 25, 2016

hellais commented Oct 25, 2016

anadahz commented Oct 31, 2016

hellais commented Nov 11, 2016

		that supports automatic discovery of hosts in the local network.

		The applications that are bundled with the Bonjour software in Windows:


		`xz --decompress --verbose --no-sparse lepidopter-alpha-armel.img.zip`
		`xz --decompress --verbose --no-sparse lepidopter-v0.3.5-beta-armel.img.zip`

Doc/lepidopter services #68

Doc/lepidopter services #68

Conversation

anadahz commented Sep 8, 2016

Choose a reason for hiding this comment

anadahz Sep 8, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

anadahz commented Sep 13, 2016

anadahz commented Sep 19, 2016

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

darkk Oct 19, 2016 • edited Loading

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

anadahz commented Oct 20, 2016

hellais commented Oct 25, 2016

hellais commented Oct 25, 2016

anadahz commented Oct 31, 2016

hellais commented Nov 11, 2016

anadahz Sep 8, 2016 •

edited

Loading

darkk Oct 19, 2016 •

edited

Loading