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

lots o types

Browse Source
This commit is contained in:
Lucy Cifferello
2020-10-15 07:43:16 -06:00
parent 33c19dbf07
commit a45dbb76e1
5 changed files with 398 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

209
source/contributing/services/config.rst
View File

@@ -8,6 +8,105 @@ Service Configurations
Config Spec
===========
This file defines the structure of the configuration of a service. Ultimately, these values influence the UI elements for a user to interact with. Specifically, they evaluate to the options available when:
TODO include screenshots
- Prior to service installation when the user needs to be made aware of any necessary dependency configurations
- The user installs a service and the service is in the "Needs Config" state
- Whenever a use edits a service configuration (ie. TODO)
- When config pointers get updated (TODO define)
@aiden are all keys kebab case? (some snake, some camel in code)
TODO commas or no commas
Types
-----
.. code::typescript
interface ConfigSpec {
serviceId: ValueSpecAny
}
pub enum ValueSpecAny {
Boolean(WithDescription<WithDefault<ValueSpecBoolean>>),
Enum(WithDescription<WithDefault<ValueSpecEnum>>),
List(ValueSpecList),
Number(WithDescription<WithDefault<WithNullable<ValueSpecNumber>>>),
Object(WithDescription<WithNullable<ValueSpecObject>>),
String(WithDescription<WithDefault<WithNullable<ValueSpecString>>>),
Union(WithDescription<WithDefault<ValueSpecUnion>>),
Pointer(WithDescription<ValueSpecPointer>),
}
interface ValueSpec {
Boolean: {
type: String (ie. "boolean")
name: String
description: String TODO char length
default: Boolean
},
Enum: {
type: String (ie. "enum")
name: String
description: String TODO char length
default: Enum
values: new Set(String),
},
List: [ValueSpec.Enum | ValueSpec.Object | ValueSpec.Number | ValueSpec.String],
Number: {
type: String (ie. "number")
name: String
description: String TODO char length
default: Boolean
nullable: Boolean
range?: Number TODO f64?,
integral: Boolean,
units?: String,
},
Object: {
type: String (ie. "object")
name: String
description: String TODO char length
nullable: Boolean
null-by-default: Boolean,
spec: ConfigSpec,
},
String: {
type: String (ie. "string")
name: String
description: String TODO char length
nullable: Boolean
pattern?: {
pattern: Regex,
pattern-description: String,
},
},
Union: {
type: String (ie. "union")
name: String
description: String TODO char length
default: Boolean
variants: {
key: ConfigSpec,
},
tag: String,
},
Pointer: {
type: String (ie. "pointer")
name: String
description: String TODO char length
subtype: app
app-id: String
target: AppPointerSpecVariants,
index: String
},
}
Examples:
.. code:: yaml
---
@@ -22,12 +121,122 @@ Config Spec
pattern: '^[^\n"]*$'
patternDescription: "Must not contain newline or quote characters."
.. code:: yaml
bitcoind:
type: union
name: Bitcoin Core
description: |
The Bitcoin Core node to connect to:
- internal: The Bitcoin Core RPC Proxy service installed to your Embassy
- external: An unpruned Bitcoin Core node running on a different device
tag: type
default: internal
variants:
internal:
address:
type: pointer
name: Local Address
description: The LAN IP address of your Bitcoin Core RPC Proxy service
subtype: app
app-id: btc-rpc-proxy
target: lan-address
user:
type: pointer
name: RPC Username
description: The username for the RPC user allocated to c-lightning
subtype: app
app-id: btc-rpc-proxy
target: config
index: 'users.[first(item => ''item.name = "c-lightning")].name'
password:
type: pointer
name: RPC Password
description: The password for the RPC user allocated to c-lightning
subtype: app
app-id: btc-rpc-proxy
target: config
index: 'users.[first(item => ''item.name = "c-lightning")].password'
external:
address:
type: string
name: Public Address
description: The public address of your Bitcoin Core RPC server
nullable: false
user:
type: string
name: RPC Username
description: The username for the RPC user on your Bitcoin Core RPC server
nullable: false
password:
type: string
name: RPC Password
description: The password for the RPC user on your Bitcoin Core RPC server
nullable: false
btc-standup:
quick-connect-url:
type: string
name: Quick Connect URL
description: The Quick Connect URL for your Bitcoin Core RPC server
nullable: false
pattern: 'btcstandup://[^:]*:[^@]*@[a-zA-Z0-9.-]+:[0-9]+(/(\?(label=.+)?)?)?'
patternDescription: Must be a valid Quick Connect URL. For help, check out https://github.com/BlockchainCommons/Gordian/blob/master/Docs/Quick-Connect-API.md
rpc:
type: object
name: RPC Options
description: Options for the HTTP RPC interface
nullable: false
nullByDefault: false
spec:
enabled:
type: boolean
name: Enable
description: Whether to enable the RPC webserver
default: true
user:
type: string
name: RPC Username
description: The username for the RPC user on your c-lightning node
nullable: false
default: lightning
password:
type: string
name: RPC Password
description: The password for the RPC user on your c-lightning node
nullable: false
default:
charset: 'a-z,A-Z,0-9'
len: 22
Config Rules
============
These rules define application level rules. A rule is a boolean expression that we demand to be true. If it is failing, it is not true.
Rules are composed of _ concepts:
* Variables
* Terms
Variables can be: booleans, numbers, strings
- different syntax depending on what you want it to be
- ? casts to boolean value. if not a boolean, whether or not its null
- # treat as a number. If not a number, will parse as NaN. String numbers are not currently supported.
- ‘ cast into a string. Applies to any value except for an object or a list.
Term: token that yields a value
A boolean term is a boolean variable, a boolean expression, or a comparison operation between numbers or strings.
If application does not satisfy a rule, give a set of suggestions, in the form of operation to preform:
- Set
- Push
- Delete
.. code:: yaml
---
- rule: 'rpc.enable? OR !(''advanced.pruning.mode = "manual")'
description: "RPC must be enabled for manual pruning."

26
source/contributing/services/docker.rst
View File

@@ -1,13 +1,29 @@
.. _service_docker:
******************
Service DockerFile
Service Dockerfile
******************
``docker_entrypoint.sh``
Dockerfile
==========
A bash script that completes any environment setup (eg. creating folder substructure), sets any environment variables, and executes the run command.
This file defines how to build the image for the service. It declares the environment and building stages for the service.
The Dockerfile is responsible for mounting the service application to whatever volume the manifest specifies, typically ``/root``.
```Dockerfile```
Since the build requires specific arm runtime environments, these base images can be imported into the Dockerfile as a starting point so the base system does not need to be completely redefined. This enables importing a specific build environment version that encapsulates any necessary libraries for running the service build, eg. golang, rust.
Declares the environment and building stages for the project.
For instance:
``FROM alpine:3.12``
``FROM arm32v7/alpine``
``arm32v7/golang:alpine``
Entry-point
===========
File specified as: ``docker_entrypoint.sh``
This file defines what to do when the service application starts.
It consists of a bash script that completes any environment setup (eg. creating folder substructure), sets any environment variables, and executes the run command. The only required feature of this file is to execute the run commands on EmbassyOS.

11
source/contributing/services/index.rst
View File

@@ -1,10 +1,10 @@
.. _service_sdk:
*********************************
Services Software Development Kit
*********************************
***************************************
Services Software Development Kit Guide
***************************************
This guide serves as an introduction to the concepts and the technical details for developing a service for the Embassy.
The `File Browser wrapper repository <https://github.com/Start9Labs/filebrowser-wrapper>`_ should be used as an example.
.. toctree::
@@ -14,4 +14,5 @@ The `File Browser wrapper repository <https://github.com/Start9Labs/filebrowser-
config
manifest
docker
wrapper
wrapper
overview

210
source/contributing/services/manifest.rst
View File

@@ -4,77 +4,169 @@
Service Manifest
****************
Types:
This file describes the service and it's requirements. Important to note is the dependencies key, which contains rules for optional or required other services that are depended on to successfully run the service at hand.
Formatting:
- Serialization language:``.yaml``
- Case style: ``kebab-case``
Below are the types and sub-type definitions, with necessary elaborations:
Manifest
.. code:: rust
.. code:: yaml
# manifest version compatibility ie. v0 (this is currently the only option)
compat: v0
# service id, used for uniqueness and BE identification ie. bitcoind
id: String
version: semver::Version
# semantic version for the release
version: String
# display name of service
title: String
description: Description
# an object containing a short and long description of the service. TODO character lengths
description:
short: String
long: String
# a link to the release tag notes in GitHub, or a short description TODO character length
release_notes: String
has_instructions: bool
os_version_required: semver::VersionReq
os_version_recommended: semver::VersionReq
ports: Vec<PortMapping>
image: ImageConfig
mount: PathBuf
assets: Vec<Asset>
hidden_service_version: HiddenServiceVersion
# denoting the existence of instructions.md
has_instructions: Boolean
# required version of EmbassyOS to run service
os_version_required: VersionReq
# recommended version of EmbassyOS to run service
os_version_recommended: VersionReq
# a list of objects of ports to run the service on localhost and tor
ports:
- internal: String
tor: String
# currently only tar is supported
image:
type: String
# path to mount the image on the volume, ie: /root/bitcoind
mount: String
# a list of objecting containing the source and destination directories of persistent assets, either that should be copied over during build, or to persist when service started, and if the volume directory should be overwritten when the release is copied over
# src: path to file within the assets directory that is in the build directory
# dst: path within volume to place it
assets:
- src: String TODO confirm type
dst: String TODO confirm type
overwrite: Boolean
# version of tor support, eg. v1, v2, v3
hidden_service_version: String
# A map of dependent services, see below for more details
dependencies: Dependencies
extra: LinearMap<String, serde_yaml::Value>
Version
.. code:: rust
.. code:: yaml
@aiden define type if more than string
VersionReq
.. code:: rust
.. code:: yaml
ImageConfig
pub enum ImageConfig {
Tar,
}
@aiden define type if more than string
#[derive(Debug, Clone, serde::Deserialize, serde::Serialize)]
pub struct Asset {
pub src: PathBuf,
pub dst: PathBuf,
pub overwrite: bool,
}
Dependencies
------------
pub struct Description {
pub short: String,
pub long: String,
}
.. code:: typescript
pub struct PortMapping {
pub internal: u16,
pub tor: u16,
}
interface Dependencies [{
serviceId: DepInfo
}]
pub enum HiddenServiceVersion {
V1,
V2,
V3,
}
interface DepInfo {
version: String -- TODO correct for VersionReq?,
optional?: String,
description?: String,
config: [
entry: {
rule: ConfigRule,
description: String,
},
suggestions: [{
condition?: ConfigRule,
variant: SuggestionVariant,
}],
],
}
pub struct Dependencies(pub LinearMap<String, DepInfo>);
interface SuggestionVariant {
SET: {
var: String,
to: SetVariant,
},
DELETE: {
src: String,
},
PUSH: {
to: String,
value: Value, @aiden define Value
},
}
#[derive(Clone, Debug, serde::Deserialize, serde::Serialize)]
pub struct DepInfo {
pub version: VersionReq,
pub optional: Option<String>,
pub description: Option<String>,
#[serde(default)]
pub config: Vec<ConfigRuleEntryWithSuggestions>,
}
interface SetVariant {
to: string,
to-value: Value,
to-entropy: {
charset: String // 'a-z,A-Z,0-9'
len: number
},
}
----
Example ``manifest.yaml``:
Examples:
.. code:: yaml
compat: v0
id: c-lightning
version: "0.1.0"
title: c-lightning
description:
short: "The Lightning Node implementation by Blockstream"
long: "A lightweight, highly customizable and standard compliant implementation of the Lightning Network protocol."
release-notes: https://github.com/ElementsProject/lightning/releases/tag/v0.1.0
ports:
- internal: 8080
tor: 8080
image:
type: tar
mount: /root/.lightning
has-instructions: true
os-version-required: ">=0.2.5"
os-version-recommended: ">=0.2.5"
assets: []
hidden-service-version: v3
dependencies:
btc-rpc-proxy:
version: "^0.1.0"
optional: Can configure an external bitcoin node.
description: Required for fetching validated blocks.
config:
- rule: '''users.*.name = "c-lightning"'
description: 'Must have an RPC user named "c-lightning"'
suggestions:
- PUSH:
to: 'users'
value:
name: c-lightning
- rule: 'users.[first(item => ''item.name = "c-lightning")].password?'
description: 'RPC user "c-lightning" must have a password'
suggestions:
- SET:
var: 'users.[first(item => ''item.name = "c-lightning")].password'
to-entropy:
charset: 'a-z,A-Z,0-9'
len: 22
- rule: 'users.[first(item => ''item.name = "c-lightning")].fetch-blocks?'
description: 'RPC user "c-lightning" must have "Fetch Blocks" enabled'
suggestions:
- SET:
var: 'users.[first(item => ''item.name = "c-lightning")].fetch-blocks'
to-value: true
.. code:: yaml
@@ -89,10 +181,10 @@ Example ``manifest.yaml``:
Features
- Adds instructions defined by EmbassyOS 0.2.4 instructions feature
ports:
- internal: 59001
tor: 59001
- internal: 80
tor: 80
- internal: 59001
tor: 59001
- internal: 80
tor: 80
image:
type: tar
mount: /root
@@ -100,10 +192,10 @@ Example ``manifest.yaml``:
os-version-required: ">=0.2.4"
os-version-recommended: ">=0.2.4"
assets:
- src: httpd.conf
dst: "."
overwrite: true
- src: www
dst: "."
overwrite: true
- src: httpd.conf
dst: "."
overwrite: true
- src: www
dst: "."
overwrite: true
hidden-service-version: v3

14
source/contributing/services/wrapper.rst
View File

@@ -4,6 +4,8 @@
Service Wrapper
***************
Everything you need to build a service.
Each service is bound with a wrapper repository. The purpose of this repo is:
- Denote any dependencies required to run and build the project.
@@ -22,11 +24,11 @@ The project structure should be used as a model:
.. code-block:: bash
├── Dockerfile
├── Makefile
├── Makefile (optional)
├── README.md
├── assets
│ ├── httpd.conf
│ └── httpd.conf.template
│ ├── httpd.conf (optional)
│ └── httpd.conf.template (optional)
├── config_rules.yaml
├── config_spec.yaml
├── <submodule_project_dir>
@@ -45,3 +47,9 @@ Run ``git submodule add <link_to_source_project>``
For reference: `git-submodules <https://www.git-scm.com/book/en/v2/Git-Tools-Submodules>`_
Assets
======
Whenever a service is stopped, any file that is not contained within in the ``/assets`` directory will be cleared from memory. Any unsaved changes will be reverted. This folder acts as a persistance storage container.
In this folder belongs any assets that are unique configurations to your service. For instance, bitcoind's ``.conf`` file is saved here.