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,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