Include documentation in image and a custom script directory

.gitlab-ci.yml

@@ -1,15 +1,38 @@
 image: gitlab/dind
 
+stages:
+ - docs
+ - publish
+
 variables:
  VERSION: ${CI_COMMIT_REF_NAME}
+ CI_JOB: ${CI_JOB_ID}
 
 before_script:
  - apt-get update && apt-get install -y --no-install-recommends make linux-image-generic
 
-job:
+sd-image:
+ stage: publish
  script:
  - make sd-image
  artifacts:
  paths:
  - hypriotos-rpi-${VERSION}.img.zip
  - hypriotos-rpi-${VERSION}.img.zip.sha256
+
+pages:
+ stage: docs
+ image: node:6
+ before_script:
+ - npm install gitbook-cli -g # install gitbook
+ - gitbook fetch latest # fetch latest stable version
+ - gitbook install docs # add any requested plugins in book.json
+ script:
+ - gitbook build docs builder/files/var/www/docs # build to public path
+ after_script:
+ - cp -ar builder/files/var/www/docs public
+ artifacts:
+ paths:
+ - public
+# only:
+# - master

builder/build.sh

@@ -59,6 +59,7 @@ mount -t sysfs none ${BUILD_PATH}/sys
 
 # modify/add image files directly
 cp -R /builder/files/* ${BUILD_PATH}/
+cp -R /builder/scripts/* ${BUILD_PATH}/usr/local/bin/
 
 # make our build directory the current root
 # and install the Rasberry Pi firmware, kernel packages,

builder/files/var/www/index.html

@@ -16,5 +16,8 @@ <h2>Public Lab Pi Kit</h2>
  <p>
  <i>You've correctly connected to your Pi!</i>
  </p>
+ <p>
+ <a href="/docs">Documentation</a>
+ </p>
  </body>
 </html>

builder/scripts/timelapse.sh

@@ -0,0 +1,5 @@
+while true 
+do
+ echo 'im' >> /var/www/cam/FIFO
+ sleep 5
+done

docs/README.md

@@ -0,0 +1,41 @@
+# Raspberry Pi Image Builder
+
+**PublicLab.Org**
+
+![](publiclab.svg)
+
+This documentation covers the usage of the builder script for operating system images designed to be included with Public Lab Camera Kits.
+
+Any person may use this script and the related infrastructure for building customized operating systems for their own projects.
+
+It is important to highlight that this project was forked from the [Hypriot project](https://github.com/hypriot/image-builder-rpi). Thanks!
+
+## Rationale
+
+Often DIY projects require customizing software. It is an effort to publish these customizations.
+
+This repository could serve to share customizations and develop them *socially*, by means of issuing pull requests and sharing build recipes and resulting images.
+
+This guide serves the purpose of detailing the build process and suggesting a customization workflow.
+
+## Developing
+
+Issuing a PR will build the image. We will merge PRs aligned and suitable to be included in Public Lab's Camera Kits, at the discretion of the maitainers. You are encouraged to fork your own repository and experiment with preparing your own images!
+
+- Repository (GitLab): https://gitlab.com/publiclab/image-builder-rpi
+
+By using Gitlab's automated continuous integration to build images you'll have fresh images built for you every time you push your changes.
+
+For the community's convenience, this repository is also mirrored at Github
+
+- Repository (GitHub): https://github.com/publiclab/image-builder-rpi
+
+## License
+
+Like its upstream project Hypriot, `image-builder-rpi` is licensed with the MIT license. 
+
+This guide is licensed with Creative Commons Share-Alike 4.0 Unported license.
+
+## Contributors
+
+This project was initiated by Sebastian Silva by contract of PublicLab.Org, the **Public Laboratory for Open Technology and Science**.

docs/SUMMARY.md

@@ -0,0 +1,7 @@
+# Summary
+
+* [Image Builder](README.md)
+* [Customization](customization.md)
+* [Workflow](workflow.md)
+* [Scripting](scripting.md)
+* [Roadmap](roadmap.md)

docs/book.json

@@ -0,0 +1,3 @@
+{
+ "title": "Raspberry Pi Image Builder"
+}

docs/customization.md

@@ -0,0 +1,29 @@
+# Image Customization
+
+This repository holds the recipe and files for building an operating system image capable of booting on Raspberry Pi (tested on model `Pi Zero W`).
+
+While you may build locally if you have Docker (tested on Linux), it is recommended that you follow the [workflow](workflow.md).
+
+## Files and Directories
+
+ `builder/files/`: All files in this directory will be copied over to the Raspberry Pi image's root directory.
+
+ `builder/build.sh`: This is the script that does the actual building.
+
+ `builder/chroot-script.sh`: This is the script that is run inside an ARM based virtual machine that emulates the raspberry pi. It installs packages and also generates some configuration files.
+
+ `builder/files/boot/user-data`: This is the configuration file for cloud-init. It holds important customizations such as username creation and hostname configuration.
+
+## Cloud Init Configuration File (`user-data`)
+
+This is one recommended configuration point as it can be modified *before first boot*.
+
+This is the main configuration file for `cloud-init` which is designed to customize cloud servers and provides many useful configuration hooks. Please refer to the [`cloud-init` documentation](https://cloudinit.readthedocs.io/en/0.7.9/) for details.
+
+## Customization Orientation
+
+If you'd like to start scripts every boot, try to customize `builder/files/etc/rc.local` adding commands which will be ran after the rest of the startup process.
+
+Also the web root is at `/var/www/`. You may place web content or applications here. PHP has been enabled by default.
+
+Once you have modified the scripts or files to be included in the distribution, follow the [workflow](workflow.md) into the next step.

docs/package.json

@@ -0,0 +1,6 @@
+{
+ "dependencies": {
+ "gitbook-cli": "^2.3.2",
+ "svgexport": "^0.3.2"
+ }
+}

docs/roadmap.md

@@ -0,0 +1,8 @@
+# Development goals
+
+This is a wishlist of features to include:
+
+* Configure Wifi (client / access point / forwarding)
+* Streaming Camera
+* Web editor / runner for scripts
+* Configure scripts to run at boot

docs/scripting.md

@@ -0,0 +1,30 @@
+# Scripting
+
+The operating system installed is Raspbian Lite, a derivative of the popular Debian GNU/Linux distribution. Please refer to the Debian documentation for most configuration needs. *This section attempts to introduce basic recipes to make use of scripts*.
+
+You'll need to access the terminal emulator in order to execute scripts (or schedule them). You may access the console with a SSH client or from the web terminal (if available). You may also copy files from and into the device with an SFTP client (such as `scp`).
+
+# Writing scripts
+
+Scripts can be written in any language included with Raspbian. The default shell is called **bash** and it's common among GNU/Linux systems.
+
+In Debian, you may place custom scripts in the `/usr/local/bin` directory. This will make it available to all users.
+Scripts should have execution privileges enabled. Execution privileges are granted with the `chmod a+x script.sh` (where `script.sh` is the script file).
+
+**Tip**: If you are trying to run a script located in the current directory, you'll need to call it like this: `./my_script.sh` (with "./" to indicate the current directory)
+
+# Running scripts on startup
+
+Once your scripts are properly installed in the `/usr/local/bin` directory and work as intended, you may want to start them at boot time. You may do so by adding a line to `/etc/rc.local` which is run at the end of the boot process.
+
+# Scheduling scripts to be run at intervals
+
+It's possible to use the Cron daemon to schedule tasks either from root or as a user. Use the command `crontab -e` to edit the current users's cron entry. The basic syntax for a cron entry is:
+
+`minute hour day-of-month month day-of-week user command`
+
+Refer to the Cron manual for details (`man cron`).
+
+# Running a script every few seconds
+
+Try the `watch` command. It works as `watch -n seconds command` and runs a given command repeatedly and continually.

docs/workflow.md

@@ -0,0 +1,27 @@
+# Development Workflow for Custom Images
+
+We recommend that you follow these steps to build your images.
+
+## Make a Pull Request
+
+Create a named branch with a descriptive name (it will be used in the image filename), and **make a pull request** describing your intentions!
+
+**Intention to merge to master is not required**. You may issue a PR simply for sharing an experiment and for triggering a build to test an image.
+
+## Download the build artifact from GitLab CI
+
+Once you've made a PR, you should see a build triggered that is linked in your PR.
+
+It can take more than 20 minutes to build an image.
+
+You may follow the link on your PR to view the build log and find the links to download the build artifacts, which hold the image for flashing.
+
+These images are referred to as build artifacts and are available for download directly from the [**build jobs page at Gitlab**](https://gitlab.com/publiclab/image-builder-rpi/-/jobs).
+
+## Flash your image
+
+Using your preferred method (or the [Hypriot flash tool](https://github.com/hypriot/flash), which offers some flash-time customization hooks).
+
+## Share your results!
+
+Do comment on your PR!