diff --git a/_build/install-toolchain.sh b/_build/install-toolchain.sh index 923b736..5f7ff5d 100755 --- a/_build/install-toolchain.sh +++ b/_build/install-toolchain.sh @@ -3,9 +3,14 @@ set -ev cd $(realpath $(dirname "${0}")) -# Install Alpine SDK and useful tools +# Install basic build tools apk update -apk add alpine-sdk git file htop less openssh-client openssh-server openssh-sftp-server tar xz +apk add git file htop less openssh-client openssh-server openssh-sftp-server tar xz +# Install Alpine SDK +apk add alpine-sdk +# Install Sphinx support +apk-add py3-sphinx +pip3 install recommonmark sphinx-markdown-tables # Copy root profile files and settings mkdir -p /root/.config/htop /root/.ssh diff --git a/_doc/Makefile b/_doc/Makefile new file mode 100644 index 0000000..8d9e831 --- /dev/null +++ b/_doc/Makefile @@ -0,0 +1,19 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build-3 +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/_doc/conf.py b/_doc/conf.py new file mode 100644 index 0000000..0cfab17 --- /dev/null +++ b/_doc/conf.py @@ -0,0 +1,177 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/master/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'SpotterVM' +copyright = '2019, Spotter' +author = 'Spotter' + +# The short X.Y version +version = '' +# The full version, including alpha/beta/rc tags +release = '' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['recommonmark', 'sphinx_markdown_tables'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown' +} + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'en' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = None + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} +html_sidebars = { '**': ['localtoc.html', 'relations.html', 'searchbox.html'] } + +html_show_sourcelink = False + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'SpotterVMdoc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'SpotterVM.tex', 'SpotterVM Documentation', + 'Disassembler', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'spottervm', 'SpotterVM Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'SpotterVM', 'SpotterVM Documentation', + author, 'SpotterVM', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Options for Epub output ------------------------------------------------- + +# Bibliographic Dublin Core info. +epub_title = project + +# The unique identifier of the text. This can be a ISBN number +# or the project homepage. +# +# epub_identifier = '' + +# A unique identification for the text. +# +# epub_uid = '' + +# A list of files that should not be packed into the epub file. +epub_exclude_files = ['search.html'] diff --git a/_doc/existing/index.rst b/_doc/existing/index.rst new file mode 100644 index 0000000..8845742 --- /dev/null +++ b/_doc/existing/index.rst @@ -0,0 +1,9 @@ +Information about existing containers +===================================== + +.. toctree:: + :maxdepth: 2 + + list + tech-overview + map-services diff --git a/_doc/existing/list.md b/_doc/existing/list.md new file mode 100644 index 0000000..f72519e --- /dev/null +++ b/_doc/existing/list.md @@ -0,0 +1,59 @@ +# List of existing containers + +## List of basic and runtime layers + +| Layer | Container | +|-------------------------|---------------------| +| Alpine 3.8 | alpine3.8 | +| Alpine 3.8 - PHP 5.6 | alpine3.8-php5.6 | +| Alpine 3.8 - NodeJS 8 | alpine3.8-nodejs8 | +| Alpine 3.9 - Ruby 2.4 | alpine3.8-ruby2.4 | +| Alpine 3.9 | alpine3.9 | +| Alpine 3.9 - Java 8 | alpine3.9-java8 | +| Alpine 3.9 - PHP 7.2 | alpine3.9-php7.2 | +| Alpine 3.9 - Python 2.7 | alpine3.9-python2.7 | +| Alpine 3.9 - Python 3.6 | alpine3.9-python3.6 | +| Alpine 3.9 - NodeJS 10 | alpine3.9-nodejs10 | +| Alpine 3.9 - Ruby 2.4 | alpine3.9-ruby2.4 | +| Alpine 3.9 - Tomcat 7 | alpine3.9-tomcat7 | +| Alpine 3.9 - Tomcat 8.5 | alpine3.9-tomcat8.5 | +| Sahana - Shared | sahana-shared | + +## List of service containers + +| Service | Container | UID/GID | Internal Port | +|-----------------|-----------------|---------|------------------| +| ActiveMQ | activemq | 61616 | 61616 (ActiveMQ) | +| CKAN Datapusher | ckan-datapusher | 8004 | 8080 (HTTP) | +| MariaDB | mariadb | 3306 | 3306 (MySQL) | +| Postgres | postgres | 5432 | 5432 (Postgres) | +| RabbitMQ | rabbitmq | 5672 | 5672 (AMQP) | +| Redis | redis | 6379 | 6379 (Redis) | +| Solr | solr | 8983 | 8983 (HTTP) | + +## List of application containers + +All application containers listen on internal port 8080 (HTTP) + +| Application | Container | UID/GID | Host | +|----------------|-------------------|---------|-------------| +| CKAN | ckan | 8003 | ckan | +| Crisis Cleanup | crisiscleanup | 8005 | cc | +| CTS | cts | 8006 | cts | +| EcoGIS | ecogis | 8020 | ecogis | +| FrontlineSMS | frontlinesms | 8018 | sms | +| GNU Health | gnuhealth | 8008 | gh | +| KanBoard | kanboard | 8009 | kb | +| Mifos X | mifosx | 8012 | mifosx | +| Motech | motech | 8013 | motech | +| ODK Aggregate | opendatakit | 8015 | odk | +| ODK Build | opendatakit-build | 8017 | odkbuild | +| Odoo | odoo | 8019 | odoo | +| OpenMapKit | openmapkit | 8007 | omk | +| Pan.do/ra | pandora | 8002 | pandora | +| Sahana | sahana | 8001 | sahana | +| Sahana - Demo | sahana-demo | 8001 | sahana-demo | +| SAMBRO | sambro | 8001 | sambro | +| SeedDMS | seeddms | 8010 | dms | +| Sigmah | sigmah | 8011 | sigmah | +| Ushahidi | ushahidi | 8014 | ush | diff --git a/_doc/existing/map-services.md b/_doc/existing/map-services.md new file mode 100644 index 0000000..dfdbe6c --- /dev/null +++ b/_doc/existing/map-services.md @@ -0,0 +1,27 @@ +# Map services used in applications + +| Application | Data sources | Map viewer | Configurable | Notes | +|---------------|--------------|-------------|--------------|-------| +| CKAN | OSM ([Stamen](http://maps.stamen.com)) | Leaflet | No | [1] | +| CrisisCleanup | Google Maps | Google Maps | No | | +| CTS | OSM, [ArcGIS](http://server.arcgisonline.com/arcgis/rest/services) | Leaflet | No | | +| EcoGIS | ? | FreeGIS + OpenLayers 2 | Probably | [2] | +| Odoo | Google Maps | Google Maps | No | [3] | +| OpenMapKit | OSM | N/A | Yes | [4] | +| Pan.do/ra | Google Maps | Google Maps + OxMap | No | | +| Sahana Eden | OSM ([HOT](https://www.hotosm.org/)) | OpenLayers 2 | Yes, very | [5] | +| Ushahidi | OSM ([Mapbox](https://www.mapbox.com/about/maps/), [HOT](https://www.hotosm.org/)) | Leaflet | No | | +| --- | | | | | +| WebODM | OSM | Leaflet | | | +| Crismapp | OSM | Leaflet | | | +| ThinkHazard! | OSM | Mapbox | | | +| Openforis | Google Earth | | No | | +| Tendenci | Google Maps | Google Maps | No | | +| GeoNode | OSM | ? OpenLayers 3 | | | + + +1. Used by CKAN extensions *reclineview*, *spatial* and *geoview*. +2. Untested as the EcoGIS source code is not fully open. Looks like the data sources are configurable, but the full documentation is only in italian. +3. Used by Odoo *Google Maps* module to display company/partner address on map. +4. Map is used by OMK and ODK Android clients. OMK Server only offers the API. See [area of interest depoyment](http://posm.io/docs/omk/walkthrough/) on POSM wiki. +5. Sahana Eden supports multitude of connectors and protocols to process map and feature data. ArcGIS REST, Bing maps, GeoJSON, GeoRSS, Google Maps, GPX, KML, MGRS, OSM, OWM, Shapefile, TMS, WFS, WMS and XYZ. diff --git a/_doc/existing/tech-overview.md b/_doc/existing/tech-overview.md new file mode 100644 index 0000000..aba84c6 --- /dev/null +++ b/_doc/existing/tech-overview.md @@ -0,0 +1,316 @@ +# Overview of technological requirements + +## Basic system + +Components which are installed directly as part of the basic virtual machine. + +### Alpine linux + +- **General description:** Operating system +- **Tech. description:** Lightweight linux distribution based on musl C libraries +- **Depends on:** - +- **Used by:** Everything +- **Related skills:** EXTLINUX / ISOLINUX, git, linux administration (cron, filesystems, iptables, networking, user/group mgmt etc.), LUKS, LVM, OpenRC init system, POSIX standards, s6 init system, shell scripting + +### Acme.sh + +- **General description:** Certificate renewal tool +- **Tech. description:** Shell-based Automated Certificate Management Environment client +- **Depends on:** - +- **Used by:** nginx, VMMgr +- **Related skills:** shell scripting, SSL/TLS + +### Nginx + +- **General description:** Web server +- **Tech. description:** Lightweight HTTP server +- **Depends on:** - +- **Used by:** All application containers, VMMgr +- **Related skills:** HTTP (proxying, rewriting) + +### LXC + +- **General description:** Container virtualization host +- **Tech. description:** Operating system-level container virtualization host +- **Depends on:** - +- **Used by:** All containers +- **Related skills:** container virtualization fundamentals, linux kernel (cgroups, overlayfs, seccomp), shell scripting + +### Postfix + +- **General description:** Mail server +- **Tech. description:** Outbound mail transfer agent +- **Depends on:** - +- **Used by:** All application containers +- **Related skills:** SMTP + +### VMMgr + +- **General description:** Virtual machine and application manager web interface +- **Tech. description:** In-house Werkzeug-based virtual machine and application manager WSGI application +- **Depends on:** Nginx, LXC, Python 3 +- **Used by:** User +- **Related skills:** JSON, python 3 frameworks and modules (cryptography, jinja2, requests, subprocess, werkzeug), shell scripting, WSGI application development + + +## Runtimes + +Components which are supplied as LXC overlay layers but don't run as standalone containers + +### Java + +- **General description:** Java runtime environment +- **Tech. description:** Java OpenJDK 8 runtime environment +- **Depends on:** - +- **Used by:** ActiveMQ, FrontlineSMS, Tomcat, CrisisCleanup, MifosX, Motech, OpenDataKit, OpenMapKit, Sigmah, Solr +- **Related skills:** - + +### Node.js + +- **General description:** JavaScript runtime environment +- **Tech. description:** Server-side Node.js 8 JavaScript runtime environment +- **Depends on:** - +- **Used by:** CrisisCleanup, GNU Health, Odoo, OpenDataKit Build, OpenMapKit +- **Related skills:** HTTP (proxying), JavaScript (language overview) + +### PHP + +- **General description:** PHP 7 runtime environment +- **Tech. description:** PHP 7 hypertext preprocessor scripting runtime +- **Depends on:** - +- **Used by:** KanBoard, SeedDMS, Ushahidi +- **Related skills:** HTTP (proxying), PHP 7 (language overview), PHP-FPM + +### Python 2 + +- **General description:** Python 2 runtime environment +- **Tech. description:** Python 2 runtime environemnt and standard libraries +- **Depends on:** - +- **Used by:** CKAN, CKAN DataPusher, CTS, OpenMapKit, Sahana Eden +- **Related skills:** linux compilation toolchain (header files, gcc, make etc.), pip, python (language overview) + +### Python 3 + +- **General description:** Python 3 runtime environment +- **Tech. description:** Python 3 runtime environemnt and standard libraries +- **Depends on:** - +- **Used by:** GNU Health, Odoo, Pan.do/ra, SeedDMS, VMMgr (doesn't use container) +- **Related skills:** linux compilation toolchain (header files, gcc, make etc.), pip, python (language overview) + +### Ruby + +- **General description:** Ruby runtime environment +- **Tech. description:** Ruby 2.4 runtime environment and gem package installer +- **Depends on:** - +- **Used by:** CrisisCleanup, OpenDataKit Build +- **Related skills:** linux compilation toolchain (header files, gcc, make etc.) + +### Tomcat + +- **General description:** Lightweight Java application server +- **Tech. description:** Java application JSP and servlet container +- **Depends on:** Java +- **Used by:** MifosX, Motech, OpenDataKit, Sigmah +- **Related skills:** JVM tuning, shell scripting + + +## Components + +Components which are supplied as LXC containers required by other applications but aren't exposed directly to the end user + +### ActiveMQ + +- **General description:** Message broker middleware +- **Tech. description:** Java-based message broker and messaging server +- **Depends on:** Java +- **Used by:** Motech +- **Related skills:** JVM tuning, XML + +### MariaDB + +- **General description:** MySQL database server +- **Tech. description:** MySQL-compatible relational database management system +- **Depends on:** - +- **Used by:** MifosX, Ushahidi +- **Related skills:** SQL (language overview) + +### Postgres + +- **General description:** PostgreSQL database server +- **Tech. description:** PostgreSQL relational database management system +- **Depends on:** - +- **Used by:** CKAN, CrisisCleanup, CTS, GNU Health, KanBoard, Motech, Odoo, OpenDataKit, OpenDataKit Build, OpenMapKit, Pan.do/ra, Sahana Eden, SeedDMS, Sigmah +- **Related skills:** SQL (language overview) + +### RabbitMQ + +- **General description:** Message broker middleware +- **Tech. description:** Erlang-based message broker and messaging server +- **Depends on:** - +- **Used by:** Pan.do/ra +- **Related skills:** - + +### Redis + +- **General description:** Key-value NoSQL database server +- **Tech. description:** In-memory NoSQL key-value data structure object store +- **Depends on:** - +- **Used by:** CKAN +- **Related skills:** - + +### Solr + +- **General description:** Full-text search server +- **Tech. description:** Apache Lucene-based full-text search and indexing platform +- **Depends on:** Java +- **Used by:** CKAN +- **Related skills:** shell scripting, JVM tuning + + +## Applications + +Components which are supplied as LXC containers exposed directly to the end user + +### CKAN + +- **General description:** Data management and data store system +- **Tech. description:** Flask-based data store application +- **Depends on:** CKAN DataPusher, Postgres, Python 2, Redis, Solr +- **Used by:** User +- **Related skills:** PostGIS, python frameworks and modules (flask, paster, setuptools), Solr core configuration + +### CKAN DataPusher + +- **General description:** Data file parser for CKAN +- **Tech. description:** Python-based data file parser service for CKAN +- **Depends on:** Python 2 +- **Used by:** CKAN +- **Related skills:** MIME types identification, WSGI application development + +### CrisisCleanup + +- **General description:** Disaster response and relief coordination +- **Tech. description:** Ruby-on-Rails-based application with Node.js-generated frontend assets +- **Depends on:** LibXML, Node.js, Postgres, Ruby +- **Used by:** User +- **Related skills:** Node.js build systems (npm, yarn), Ruby build systems and frameworks (Bundle, Devise, Gems, Rails, Rake) + +### CTS + +- **General description:** Commodity tracking system +- **Tech. description:** Django-based forms applicaton +- **Depends on:** Postgres, Python 2 +- **Used by:** User +- **Related skills:** python frameworks (Django), WSGI application development + +### FrontlineSMS + +- **General description:** Bulk text messaging +- **Tech. description:** Spring-based application for modem device access +- **Depends on:** Java +- **Used by:** User +- **Related skills:** Java build systems and frameworks (grails, Spring), Jetty, linux modem/tty handling, Xorg (X server) + +### GNU Health + +- **General description:** Hospital information system (ERP) +- **Tech. description:** Tryton-based form application RPC backend with Node.js-based frontend +- **Depends on:** Node.js, Postgres, Python3 +- **Used by:** User +- **Related skills:** Node.js build systems (grunt, npm), python modules (setuptools, virtualenv) + +### KanBoard + +- **General description:** Kanban project management +- **Tech. description:** Symfony-based forms application +- **Depends on:** PHP, Postgres +- **Used by:** User +- **Related skills:** PHP build systems and frameworks (Composer, Symfony) + +### MifosX + +- **General description:** +- **Tech. description:** Spring-based forms application RPC backend with Node.js-packed frontend +- **Depends on:** MariaDB, Tomcat +- **Used by:** User +- **Related skills:** Java frameworks (Spring), Node.js and JavaScript development (Angular, Bower, Grunt) + +### Motech + +- **General description:** +- **Tech. description:** Apache Felix-based forms application +- **Depends on:** ActiveMQ, Postgres, Tomcat +- **Used by:** User +- **Related skills:** Java frameworks (Apache Felix, Spring) + +### Odoo + +- **General description:** +- **Tech. description:** Werkzeug-based forms application RPC backend with Node.js-based frontend +- **Depends on:** Node.js, Postgres, Python 3 +- **Used by:** User +- **Related skills:** WSGI application development + +### OpenDataKit + +- **General description:** +- **Tech. description:** Spring and OpenRosa-based data store application +- **Depends on:** Postgres, Tomcat +- **Used by:** User +- **Related skills:** Java build systems and frameworks (Gradle, Spring) + +### OpenDataKit Build + +- **General description:** +- **Tech. description:** Ruby-based forms application with Node.js-based data converter +- **Depends on:** Node.js, Ruby +- **Used by:** User +- **Related skills:** Node.js build systems (npm), Ruby build systems and frameworks (Bundler, Rake) + +### OpenMapKit + +- **General description:** +- **Tech. description:** Node.js-based forms application with python2 dependencies +- **Depends on:** Node.js, Postgres, Python 2 +- **Used by:** User +- **Related skills:** JavaScript development, Node.js build systems (Yarn) + +### Pan.do/ra + +- **General description:** +- **Tech. description:** Python-based media store with Javascript-based frontend +- **Depends on:** Postgres, Python 3, RabbitMQ +- **Used by:** User +- **Related skills:** ffmpeg, imagemagick, JavaScript development (oxjs) + +### Sahana Eden + +- **General description:** +- **Tech. description:** Web2py-based forms application +- **Depends on:** Postgres, Python 2 +- **Used by:** User +- **Related skills:** PostGIS, python frameworks and modules (requests, selenium, Web2py) + +### SeedDMS + +- **General description:** +- **Tech. description:** PHP-based data store application with Lucene-based fulltext index +- **Depends on:** PHP, Postgres +- **Used by:** User +- **Related skills:** Apache Lucene, ghostscript, LibreOffice (unoconv), imagemagick, MIME types identification + +### Sigmah + +- **General description:** +- **Tech. description:** Apache Commons-based forms application +- **Depends on:** Postgres, Tomcat +- **Used by:** User +- **Related skills:** Java development (hibernate, log4j) + +### Ushahidi + +- **General description:** +- **Tech. description:** Laravel-based RPC backend with Angular-based frontend +- **Depends on:** MariaDB, PHP +- **Used by:** User +- **Related skills:** JavaScript build tools and frameworks (Angular, Babel, WebPck), PHP build tools and frameworks (composer, Laravel, phinx) diff --git a/_doc/index.rst b/_doc/index.rst new file mode 100644 index 0000000..c9c4154 --- /dev/null +++ b/_doc/index.rst @@ -0,0 +1,9 @@ +Welcome to SpotterVM documentation! +=================================== + +.. toctree:: + :caption: Technical documentation + :maxdepth: 3 + + toolchain/index + existing/index diff --git a/_doc/toolchain/abuild.md b/_doc/toolchain/abuild.md new file mode 100644 index 0000000..e74b7a4 --- /dev/null +++ b/_doc/toolchain/abuild.md @@ -0,0 +1,49 @@ +# Alpine build and packaging + +Alpine build system is used for all custom non-LXC packages, such as Acme.sh Let's Encrypt ACME client and VMMgr virtual machine manager. + +## Alpine wiki references + +The usage of Abuild, APK package manager and syntax of `APKBUILD` files is best described on Alpine wiki. + +- [Abuild and Helpers](https://wiki.alpinelinux.org/wiki/Abuild_and_Helpers) +- [Creating an Alpine package](https://wiki.alpinelinux.org/wiki/Creating_an_Alpine_package) +- [APKBUILD Reference](https://wiki.alpinelinux.org/wiki/APKBUILD_Reference) +- [APKBUILD Examples](https://wiki.alpinelinux.org/wiki/APKBUILD_examples) + +## Abuild in a nutshell + +Building with abuild requires `alpine-sdk` package installed, `/etc/abuild.conf` configured and an RSA private key created in `/srv/build/repokey.rsa` and subsequently registered by `abuild-keygen` command. All these are taken care of in `install-toolchain.sh` script as part of [Build environment installation](vm-creation). + +Abuild toolchain is intended to be used in automated builds, therefore it requires some dependencies normally not found in other packaging systems. Abuild expects that `APKBUILD` files are a part of git repository and tries to read current commit hash. Then it tries to automatically download, build (compile), strip binaries, find out dependencies, and generally perform a lot of tasks normally useful when you are compiling from sources. Finally it packages the result to one or more subpackages, according to the build recipe. For purposes of LXC packaging, this is mostly useless, which is the reason why we have a [custom package manager](pkgmgr). It is however perfectly suitable for packages installed directly on the basic VM. + +## APKFILE and build example + +Following is an `APKFILE` example with some commonly used options to skip or bypass the default features of Abuild in case you simply need to package a bunch of existing files without any compilation or other build tasks. + +``` +# Contributor: Disassembler +# Maintainer: Disassembler +pkgname=somepackage +pkgver=0.0.1 +pkgrel=0 +pkgdesc="Some description" +url="https://spotter.vm/" +arch="noarch" +license="GPL" +depends="python3" +options="!check !strip" + +build() { + return 0 +} + +package() { + mkdir -p ${pkgdir} + cp -rp mydir ${pkgdir} +} +``` + +The directive `options="!check !strip"` requests Abuild not to run post-build checks and not to strip binaries. The `build()` function is mandated by the Abuild documentation and simply returns an exit code without doing anything. Finally in `package()` function, the desired existing files are copied to `${pkgdir}` (which is a variable automatically set by Abuild) and packaged. + +Such `APKFILE` recipe is then executed using `abuild` command. Abuild normally uses `fakeroot` to isolate the build environment and discourages using root user for packaging, however our build instance is highly specialized for this purpose, so we package as root anyway. Any user (including root) needs to be a member of `abuild` group in order to perform the task. For our root user, this is again handled in `install-toolchain.sh`. If you do the packaging as root, you need to run `abuild -F` as seen in `build-all.sh`. diff --git a/_doc/toolchain/index.rst b/_doc/toolchain/index.rst new file mode 100644 index 0000000..c12be6e --- /dev/null +++ b/_doc/toolchain/index.rst @@ -0,0 +1,13 @@ +VM building and packaging +========================= + +.. toctree:: + :maxdepth: 2 + + vm-creation + abuild + lxc-overview + lxc-build + lxc-pack + pkgmgr + vmmgr-hooks diff --git a/_doc/toolchain/lxc-build.md b/_doc/toolchain/lxc-build.md new file mode 100644 index 0000000..76aae4a --- /dev/null +++ b/_doc/toolchain/lxc-build.md @@ -0,0 +1,200 @@ +# Building LXC containers + +## Overview + +`lxc-build` utility creates a LXC container based on its build recipe and build context path given in command line parameter. If a filename is given, the build recipe is loaded from the file and the directory in which the file resides is taken as build context, ie. all relative paths are resolved from it. In case a directory path is passed as parameter, the directory is then used as build context and a file called `lxcfile` from the given directory is used as build recipe. + +### Usage + +```bash +lxc-build + where the buildpath can be either specific lxcfile or a directory containing one +``` + +## Directives used in lxcfile + +The *lxcfile* syntax is designed to resemble *Dockerfile* syntax in order to ease the potential transition. Since LXC operates on much lower level of abstraction than Docker, some principles are applied more explicitly and verbosely. Major difference between Docker and *lxc-build* is that every directive in *Dockerfile* creates a new filesystem layer whereas layers in *lxc-build* are managed manually. + +### IMAGE + +- **Usage:** `IMAGE ` +- **Description:** Sets container name. Every *lxcfile* needs to have one, otherwise no LXC config can be written and no `RUN` scripts can be run. LXC configuration file is written to path `/var/lib/lxc//config` +- **Docker equivalent:** `-t` in `docker build` command line parameters +- **Populates LXC field:** `lxc.uts.name` + +### LAYER + +- **Usage:** `LAYER ` +- **Description:** Includes OverlayFS layer. Unlike *Dockerfile*'s `FROM`, in *lxcfile* all layers need to be defined. The `LAYER` directives are given from the lowermost to the uppermost layer, where the lowermost is usually the basic operating system and the uppermost is the working layer in which all subsequent `RUN` commands and other action will take place. +- **Docker equivalent:** `FROM` +- **Populates LXC field:** `lxc.rootfs.path` + +### FIXLAYER + +- **Usage:** `FIXLAYER ` +- **Description:** Runs `` on LXC host and passes all layer paths as parameter to this script. This helps you to resolve the conflicts in cases where you mix multiple OverlayFS layers with overlapping files, ie. package manager cache. The idea is that all layers are read separately by the `` script and the fixed result is written back to the uppermost layer. +- **Docker equivalent:** None +- **Populates LXC field:** None + +### RUN + +- **Usage:** + + ```bash + RUN