Start9/documentation
2
0
Fork 0
mirror of https://github.com/Start9Labs/documentation.git synced 2026-03-26 10:21:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

Formatting edits for new theme

Browse Source
This commit is contained in:
kn0wmad
2021-12-13 16:44:33 -07:00
committed by Lucy Cifferello
parent 60bda1bad8
commit a7a9f45d36
54 changed files with 480 additions and 165 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
source/dev-docs/packaging-example.rst
View File

@@ -1,18 +1,18 @@
.. _packaging-example:
*************************
=========================
Service Packaging Example
*************************
=========================
A rough walkthrough of how to package a service using our example `hello-world-wrapper <https://github.com/Start9Labs/hello-world-wrapper>`_.
Welcome! The following guide will provide the prerequisites, introduce a brief overview of the packaging process, use an example demonstrating how to package a service, and finally describe the submission process. This essentially describes how you can take an existing app (or one you have written yourself), and wrap it up such that it can be added to an EmbassyOS Marketplace!
Pre-requisites
==============
--------------
EmbassyOS (EOS)
---------------
...............
It is **HIGHLY RECOMMENDED** to have a copy of EmbassyOS for testing your packaged service.
@@ -22,7 +22,7 @@ There are 3 options for this:
#. :ref:`Purchse <purchasing>` a device or copy of the OS
Development Environment
-----------------------
.......................
Once you have EOS installed, you'll want to set up your development system with the necessary software.
@@ -38,10 +38,10 @@ The following are recommended:
#. rust-musl-cross (***PLACEHOLDER FOR NEW MUSL-CROSS REPO***) (For cross compiling Rust to Alpine, not needed otherwise)
Overview
========
--------
Components
----------
..........
Simply, the package is made up of the following parts:
1. Image - Each service is running in a Docker image. Best results will come from an arm based linux; [Alpine](https://www.alpinelinux.org/) is highly recommended.
@@ -54,7 +54,7 @@ Simply, the package is made up of the following parts:
Check :ref:`here <service_package_overview>` for a detailed overview of package components.
Service Wrapper Repo and Submodules
-----------------------------------
...................................
See :ref:`here <service_wrapper>` for how to structure your service wrapper's git repository.
@@ -67,12 +67,12 @@ Simply run:
git submodule add <link_to_source_project>
Example - Hello World
=====================
---------------------
Okay, let's actually package a service! For this example, we're going to use an example service `Hello World <https://github.com/Start9Labs/hello-world>`_. This repository can also be used as a template to quickly get started with your service. This will give a good overview of service packaging, but obviously your app will be different. This will assume a Linux development environment with all the recommended dependencies listed above. To get started quickly, we'll use Start9's wrapper template.
Clone the Template Repo and Edit the Manifest
---------------------------------------------
.............................................
1. Clone and rename the repo (or alternatively, use the template generation button found on the github `repo <https://github.com/Start9Labs/hello-world-wrapper>`_)
@@ -86,7 +86,7 @@ Clone the Template Repo and Edit the Manifest
3. Edit the ``manifest`` file. This must be in ``.json``, ``.toml``, or ``.yaml`` format and in ``kebab-case`` style. You can see descriptions of each key (and some notes) in our 'Hello World' example ``manifest.yaml`` below:
Manifest example
----------------
................
.. code-block:: yaml
@@ -247,7 +247,7 @@ Note the ``dependencies`` and ``volumes`` sections, which may access another ser
For details on all the different possible dependency, type, and subtype definitions available for the ``manifest`` file, please see :ref:`here <service_manifest>`.
Edit the Dockerfile and Entrypoint
----------------------------------
..................................
Next, it's time to edit the ``Dockerfile``. This defines how to build the image for the package by declaring the environment, building stages, and mounting the package to the volume specified in the ``manifest``.
@@ -318,7 +318,7 @@ Next, it's time to edit the ``Dockerfile``. This defines how to build the image
For a more detailed ``docker_entrypoint.sh``, please check out the `filebrowser-wrapper <https://github.com/Start9Labs/filebrowser-wrapper/blob/master/docker_entrypoint.sh>`_. Additional details on the ``Dockerfile`` and ``docker_entrypoint`` can be found `here <https://docs.start9.com/contributing/services/docker.html>`_.
Makefile (Optional)
-------------------
...................
Here, we will create a ``Makefile``, which is optional, but recommended as it outlines the build and streamlines additional developer contributions. Alternatively, you could use any other build orchestration tool, such as ``nix``, ``bash``, ``python``, ``perl``, ``ruby``, etc instead of ``make``.
@@ -370,7 +370,7 @@ Our example ``Makefile`` is agin fairly simple for Hello World. Let's take a lo
For more details on creating a ``Makefile`` for your project, please check :ref:`here <service_makefile>`.
Service Config Specification and Rules
--------------------------------------
......................................
Most self-hosted packages require a configuration. With EmbassyOS, these config options are provided to the user in a friendly GUI, and invalid configs are not permitted. This allows the user to manage their software without a lot of technical skill, and minimal risk of borking their software. Two files are created in this process:
@@ -482,14 +482,14 @@ In our example, there is *no need* for a ``config_rules`` file. This is because
Here we see that a Maximum Channel Size **MUST** be one of 3 possible options in order to be a valid config.
Properties
----------
..........
Next we need to create the Properties section for our package, to display any relevant info. The result of this step is a ``stats.yaml`` file, which is only populated at runtime. These commands will be issued in the ``docker_entrypoint`` file (or ``configurator``, if you are using one).
***STATS.YAML IS APPARENTLY BEING DEPRECATED, THIS SECTION NEEDS COMMENT***
Instructions
------------
............
Instructions are the basic directions or any particular details that you would like to convey to the user to help get them on their way. Each wrapper repo should contain a ``docs`` directory which can include anything you'd like, but specifically if you include an ``instructions.md`` file, formatted in Markdown language, it will be displayed simply for the user as shown below.
@@ -498,12 +498,12 @@ Instructions are the basic directions or any particular details that you would l
You can find the ``instructions.md`` file for Embassy Pages `here <https://github.com/Start9Labs/embassy-pages-wrapper/tree/master/docs>`_ if you are interested.
Backups
-------
.......
Everything in the root folder of the mounted system directory will be stored in an EOS backup. If you want to ignore any particular files for backup, you can create a ``.backupignore`` file and add the relative paths of any directories you would like ignored.
Submission Process
------------------
..................
When you have built and tested your project for EmbassyOS, please send Start9 a submission with the project repository to dev@start9labs.com. After being reviewed for security and compatibility, the service will be deployed to the marketplace and available for all EmbassyOS users to download.