mirror of
https://github.com/Start9Labs/documentation.git
synced 2026-03-26 10:21:53 +00:00
restructure docs
This commit is contained in:
Matt Hill
@@ -1,42 +0,0 @@
|
||||
.. _advanced-packaging:
|
||||
|
||||
========
|
||||
Advanced
|
||||
========
|
||||
|
||||
This section included advanced commands for working with packages in StartOS.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<div class="topics-grid grid-container full">
|
||||
|
||||
<div class="grid-x grid-margin-x">
|
||||
|
||||
.. topic-box::
|
||||
:title: Developer Tools
|
||||
:link: dev-tools
|
||||
:icon: scylla-icon scylla-icon--developers-blog
|
||||
:class: large-4
|
||||
:anchor: View
|
||||
|
||||
StartOS developer CLI tools
|
||||
|
||||
.. topic-box::
|
||||
:title: Service Containers
|
||||
:link: dev-tools/service-container
|
||||
:icon: scylla-icon scylla-icon--overview
|
||||
:class: large-4
|
||||
:anchor: View
|
||||
|
||||
How to interact with containers on the StartOS
|
||||
|
||||
.. raw:: html
|
||||
|
||||
</div></div>
|
||||
|
||||
.. This is for the side navigation display
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
:hidden:
|
||||
|
||||
dev-tools/index
|
||||
@@ -4,7 +4,7 @@
|
||||
Service Containers
|
||||
==================
|
||||
|
||||
For simplicity, StartOS is designed to be completely operated via the :ref:`WebUI <web-ui>`, however, your device belongs to you and if you want to "lift the hood" and access the internals of the software, you may do so. This guide will show you how to enter a Service's Docker container in order to directly interface with it and issue commands.
|
||||
For simplicity, StartOS is designed to be completely operated through its GUI, however, your device belongs to you and if you want to "lift the hood" and access the internals of the software, you may do so. This guide will show you how to enter a Service's Docker container in order to directly interface with it and issue commands.
|
||||
|
||||
.. warning:: The following guide is for those that have advanced command line skills, or those who are being guided by a Start9 support technician. Nothing you do inside a container is supported unless under the direction of Start9. Here be dragons!!
|
||||
|
||||
@@ -4,70 +4,13 @@
|
||||
Developer Docs
|
||||
==============
|
||||
|
||||
Welcome to the Service Packaging documentation for StartOS. If you are here, you have heard the call to help empower users with sovereign computing!
|
||||
Welcome to the Service Packaging documentation for StartOS. If you are here, you have heard the call to help empower users with sovereign computing!
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<div class="topics-grid grid-container full">
|
||||
|
||||
<div class="grid-x grid-margin-x">
|
||||
|
||||
.. topic-box::
|
||||
:title: Listing a Service
|
||||
:link: submission
|
||||
:icon: scylla-icon scylla-icon--contact-us
|
||||
:class: large-4
|
||||
:anchor: Submit
|
||||
|
||||
The process for submitting a service to the Community Registry
|
||||
|
||||
.. topic-box::
|
||||
:title: Service Packaging
|
||||
:link: packaging
|
||||
:icon: scylla-icon scylla-icon--resource-center
|
||||
:class: large-4
|
||||
:anchor: Build
|
||||
|
||||
A concise guide to Service Packaging
|
||||
|
||||
.. topic-box::
|
||||
:title: Full Specification
|
||||
:link: specification
|
||||
:icon: scylla-icon scylla-icon--glossary
|
||||
:class: large-4
|
||||
:anchor: Read
|
||||
|
||||
Detailed service packaging specification and advanced features
|
||||
|
||||
.. topic-box::
|
||||
:title: Advanced Guides
|
||||
:link: advanced
|
||||
:icon: scylla-icon scylla-icon--integrations
|
||||
:class: large-4
|
||||
:anchor: Tinker
|
||||
|
||||
Guides for implementing advanced service configurations
|
||||
|
||||
.. topic-box::
|
||||
:title: Documentation
|
||||
:link: documentation
|
||||
:icon: scylla-icon scylla-icon--docs
|
||||
:class: large-4
|
||||
:anchor: Edit
|
||||
|
||||
Contribute to our documentation.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
</div></div>
|
||||
|
||||
.. This is for the side navigation display
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:hidden:
|
||||
|
||||
submission
|
||||
packaging
|
||||
specification/index
|
||||
advanced/index
|
||||
documentation
|
||||
documentation
|
||||
dev-tools/index
|
||||
@@ -8,7 +8,7 @@ Service Packaging
|
||||
:depth: 2
|
||||
:local:
|
||||
|
||||
Welcome! Thank you for your interest in contributing to the growing ecosystem of open software. We call the software applications that run on :ref:`StartOS<start-os>` "services." This distinction is made to differentiate from "applications" (apps), which are generally run on a client, and used to access server-side software (services). To run services on StartOS, a package of file components needs to be composed. This guide will dive into the basic structure of how to compose this package.
|
||||
Welcome! Thank you for your interest in contributing to the growing ecosystem of open software. We call the software applications that run on StartOS services. This distinction is made to differentiate from "applications" (apps), which are generally run on a client, and used to access server-side software (services). To run services on StartOS, a package of file components needs to be composed. This guide will dive into the basic structure of how to compose this package.
|
||||
|
||||
Check out the :ref:`glossary <glossary>` to get acquainted with unfamiliar terms. The bottom of this guide also includes :ref:`support <packaging-support>` links, including a master checklist.
|
||||
|
||||
|
||||
@@ -1,21 +0,0 @@
|
||||
.. _compat:
|
||||
|
||||
============
|
||||
Compat Image
|
||||
============
|
||||
|
||||
With the release of StartOS v0.3.0, system utility Docker images are preloaded for service packager convenience.
|
||||
|
||||
The ``Compat`` image is a backwards compatible Docker image that hosts StartOS features used in the v0.2.x series. It was created as a convenience for service packagers to help migrate their service configurations from 0.2.x to 0.3.0.
|
||||
|
||||
It exposes functionality to make use of:
|
||||
|
||||
- ``ConfigRules`` language
|
||||
- Duplicity backups
|
||||
|
||||
|
||||
.. This is for the side navigation display
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
rules
|
||||
@@ -1,111 +0,0 @@
|
||||
|
||||
.. _config_rules:
|
||||
|
||||
============
|
||||
Config Rules
|
||||
============
|
||||
|
||||
This file defines the configuration rules, or the rule-set that defines dependencies between config variables. In practice, config rules are for auto-configuring self dependencies. Self dependencies are internal dependencies of a service, such as if the setting of one config variable informs the option of another setting. These "dependencies" are configured as rules.
|
||||
|
||||
A rule is a boolean expression that we demand to be true. It is not true if the expression fails the rule parser. Set of predicates. xt
|
||||
|
||||
They follow the `Backus–Naur <https://en.wikipedia.org/wiki/Backus%E2%80%93Naur_form>`_ meta-syntax for writing rules.
|
||||
|
||||
Rules are composed of two main concepts:
|
||||
|
||||
* Variables - accessor into a configuration
|
||||
* Terms - either a variable or type literal (ie. a boolean term is a boolean variable, a boolean expression, or a comparison operation between numbers or strings)
|
||||
|
||||
Variables can be booleans, numbers, or strings, and have a different syntax depending on the type. These type annotations check your config rules against your config spec and throw an error if invalid.
|
||||
|
||||
- ``?`` - Casts to boolean value. If the value is not a boolean, this notes whether or not the value is null.
|
||||
- ``#`` - Treat the value as a number. If it is not a number, the value will be parsed as NaN. String numbers are not currently supported.
|
||||
- ``'`` - Cast the value into a string. Applies to any value except for an object or a list.
|
||||
- ``!`` - Equals not.
|
||||
|
||||
.. note::
|
||||
Config rules are processed in order.
|
||||
|
||||
If application does not satisfy a rule, a set of suggestions should be provided. These suggestions are in the form of the operation to preform:
|
||||
|
||||
- ``Set`` - set the value
|
||||
|
||||
- ``Push`` - add to the value (such as to a list)
|
||||
|
||||
- ``Delete`` - delete the value
|
||||
|
||||
.. code:: typescript
|
||||
|
||||
enum SuggestionVariant = Set | Delete | Push
|
||||
|
||||
interface Set {
|
||||
var: String, // fully qualified path without typecast
|
||||
// one of the following three variants are required
|
||||
to: Option<String> // a string expression, use when tying another config value
|
||||
to-value: Option<String>
|
||||
to-entropy: Option<{
|
||||
charset: String (eg. 'a-z,A-Z,0-9')
|
||||
len: Number
|
||||
}>
|
||||
}
|
||||
|
||||
interface Delete {
|
||||
src: String, // path to key - removes if in a list
|
||||
}
|
||||
|
||||
interface Push {
|
||||
to: String,
|
||||
value: String, // string literal of value to be set
|
||||
}
|
||||
|
||||
SET Examples
|
||||
------------
|
||||
|
||||
.. code:: yaml
|
||||
|
||||
- SET:
|
||||
# the key in config you want to set
|
||||
var: 'users.[first(item => ''item.name = "c-lightning")].password'
|
||||
# the value in config that you will set
|
||||
to-entropy:
|
||||
charset: "a-z,A-Z,0-9"
|
||||
len: 22
|
||||
|
||||
- SET:
|
||||
var: 'users.[first(item => ''item.name = "c-lightning")].fetch-blocks'
|
||||
to-value: true
|
||||
|
||||
|
||||
PUSH Examples
|
||||
-------------
|
||||
|
||||
.. code:: yaml
|
||||
|
||||
- PUSH:
|
||||
to: "users"
|
||||
value:
|
||||
name: c-lightning
|
||||
allowed-calls: []
|
||||
|
||||
- PUSH:
|
||||
to: 'users.[first(item => ''item.name = "c-lightning")].allowed-calls'
|
||||
value: "getnetworkinfo"
|
||||
|
||||
Full example from `c-lightning manifest <https://github.com/Start9Labs/c-lightning-wrapper/blob/master/manifest.yaml>`_:
|
||||
|
||||
.. code:: yaml
|
||||
|
||||
config:
|
||||
- rule: '''users.*.name = "c-lightning"'
|
||||
description: 'Must have an RPC user named "c-lightning"'
|
||||
suggestions:
|
||||
- PUSH:
|
||||
to: "users"
|
||||
value:
|
||||
name: c-lightning
|
||||
allowed-calls: []
|
||||
- SET:
|
||||
var: 'users.[first(item => ''item.name = "c-lightning")].password'
|
||||
to-entropy:
|
||||
charset: "a-z,A-Z,0-9"
|
||||
len: 22
|
||||
@@ -15,8 +15,6 @@ This may sound cool or neat, but it is more than that: *it's novel*. This has ne
|
||||
|
||||
The key to making the system work is a new, domain-specific-language (DSL) and set of standards that are used by developers to define the rules and requirements of their services. Run in the context of StartOS, these rules and requirements appear as simple UI elements, such as inputs, toggles, and drop downs, and they are enforced by validations and clear user instructions. Using this system, what previously required serious time and expertise, can now be done by anyone in a matter of seconds.
|
||||
|
||||
This DSL is utilized in the :ref:`config rules <config_rules>` and :ref:`dependencies <service-dependencies>` key in the service manifest.
|
||||
|
||||
Context
|
||||
-------
|
||||
|
||||
|
||||
@@ -6,98 +6,8 @@ Specification
|
||||
|
||||
The following guides provide an in depth overview of the full capabilities available for packaging a service.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<div class="topics-grid grid-container full">
|
||||
|
||||
<div class="grid-x grid-margin-x">
|
||||
|
||||
.. topic-box::
|
||||
:title: Docker
|
||||
:link: docker
|
||||
:class: large-4
|
||||
:anchor: View
|
||||
|
||||
Learn how to setup the main Docker image for your service.
|
||||
|
||||
.. topic-box::
|
||||
:title: Manifest
|
||||
:link: manifest
|
||||
:class: large-4
|
||||
:anchor: Begin
|
||||
|
||||
Understand the function of a Manifest file and its type.
|
||||
|
||||
.. topic-box::
|
||||
:title: Config Spec
|
||||
:link: config-spec
|
||||
:class: large-4
|
||||
:anchor: Begin
|
||||
|
||||
Learn the purpose and utility of a config specification.
|
||||
|
||||
.. topic-box::
|
||||
:title: JS Procedures
|
||||
:link: js-procedure
|
||||
:class: large-4
|
||||
:anchor: Begin
|
||||
|
||||
Learn how to use this operation configuration library.
|
||||
|
||||
.. topic-box::
|
||||
:title: Properties
|
||||
:link: properties
|
||||
:class: large-4
|
||||
:anchor: View
|
||||
|
||||
Understand the purpose and requirements of service properties.
|
||||
|
||||
.. topic-box::
|
||||
:title: Dependencies
|
||||
:link: dependencies
|
||||
:class: large-4
|
||||
:anchor: View
|
||||
|
||||
Learn how to configure dependency options.
|
||||
|
||||
.. topic-box::
|
||||
:title: Backups
|
||||
:link: advanced
|
||||
:class: large-4
|
||||
:anchor: View
|
||||
|
||||
Learn how to configure backup options.
|
||||
|
||||
.. topic-box::
|
||||
:title: Instructions
|
||||
:link: instructions
|
||||
:class: large-4
|
||||
:anchor: View
|
||||
|
||||
Understand how an instructions file is relevant to a service.
|
||||
|
||||
.. topic-box::
|
||||
:title: Package
|
||||
:link: package
|
||||
:class: large-4
|
||||
:anchor: View
|
||||
|
||||
Learn how to package service components into a single file format.
|
||||
|
||||
.. topic-box::
|
||||
:title: Wrapper
|
||||
:link: wrapper
|
||||
:class: large-4
|
||||
:anchor: View
|
||||
|
||||
Understand the purpose of a wrapper repository.
|
||||
|
||||
.. raw:: html
|
||||
|
||||
</div></div>
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
:maxdepth: 2
|
||||
|
||||
docker
|
||||
manifest
|
||||
@@ -110,5 +20,4 @@ The following guides provide an in depth overview of the full capabilities avail
|
||||
wrapper
|
||||
makefile
|
||||
js-procedure
|
||||
compat/index
|
||||
checklist
|
||||
|
||||
@@ -19,7 +19,7 @@ Each time a service is updated, the Manifest should be updated to include the ne
|
||||
|
||||
There is nothing you need to do as a developer to set up Tor for running a service. This is *completely* handled by StartOS - a Tor address will be automatically generated when the service is installed. Just define an interface with a tor config in the Manifest file. You do, however, need to ensure the service is in fact capable of running over Tor.
|
||||
|
||||
The Manifest is also responsible for outlining service :ref:`dependencies <dependencies-spec>`. By defining rules using the :ref:`StartOS DSL specification <config_rules>`, users can easily and selectively install, uninstall, and update any service without getting stuck in dependency hell. StartOS presents this information in a polished install/uninstall/update wizard, so there's no need for editing configuration files or jumping into the command line. For you as a developer, this simply means populating this key in the manifest!
|
||||
The Manifest is also responsible for outlining service :ref:`dependencies <dependencies-spec>`. By defining rules using the :ref:`StartOS DSL specification <config_spec>`, users can easily and selectively install, uninstall, and update any service without getting stuck in dependency hell. StartOS presents this information in a polished install/uninstall/update wizard, so there's no need for editing configuration files or jumping into the command line. For you as a developer, this simply means populating this key in the manifest!
|
||||
|
||||
Formatting
|
||||
----------
|
||||
|
||||
Reference in New Issue
Block a user