diff --git a/site/03-todo.md b/site/03-todo.md index 1da83c2..838cac5 100644 --- a/site/03-todo.md +++ b/site/03-todo.md @@ -1,6 +1,8 @@ # TODO -- Update all guides in service repos - - Service-specific Guides (link to wrapper repos) +- Update all guides in service repos (link to wrapper repos in service guides) + - Bitcoin + - Lightning + - Matrix - Verify LAN and Tor setup steps on a Mac - Address build errors - Add / verify ALL links in the **UI** go to the right place in docs @@ -25,3 +27,10 @@ - Create badges for device guide topic boxes - There are many issues that should be closed by 0.3 docs release (some issues await new processes in order to test) - Email signup + +# Chris devdocs edits +Dependencies - This should be rolled into the config/manifest sections, unless the newdependencies.yaml file is what's being referred to, in which case it needs to be rewritten anyway - Lucy?? + +this manifest example is out of date, at least for backup and restore: http://127.0.0.1:5500/support/dev-docs/packaging-example/ - assigned to chris + +Screen Shot 2022-02-01 at 2.21.44 PM.png - this is technically just an artifact of compat now. in 030, properties can be any docker action diff --git a/site/source/support/dev-docs/dev-faq/faq-service-packaging.rst b/site/source/support/dev-docs/dev-faq/faq-service-packaging.rst index ed38c20..3212e29 100644 --- a/site/source/support/dev-docs/dev-faq/faq-service-packaging.rst +++ b/site/source/support/dev-docs/dev-faq/faq-service-packaging.rst @@ -37,8 +37,12 @@ How can my service access the data directory of another service? #. Provider service needs to expose datadir to other services on embassy #. Consumer services needs to list the provider service as a dependency AND set a particular config value, stating that it wants data from that particular service - +Check out `LND `_ and `RTL `_ as an example. The guide says that a Makefile is optional, why is this? -------------------------------------------------------- The ``Makefile`` simplifies the development process by putting all your build steps into one place so that you can simply use the ``make`` to build with. A ``Makefile`` is not required however, and you may instead choose to use something like ``nix``, ``bash``, ``perl``, ``python``, or ``ruby`` for your build orchestration. + +Why am I getting the error "No rule to make target yq, needed by manifest.yaml?" +-------------------------------------------------------------------------------- +This is the message you get when you're missing the executable on your ``$PATH``. diff --git a/site/source/support/dev-docs/packaging-example.rst b/site/source/support/dev-docs/packaging-example.rst index 0192690..f4e9681 100644 --- a/site/source/support/dev-docs/packaging-example.rst +++ b/site/source/support/dev-docs/packaging-example.rst @@ -316,7 +316,7 @@ Next, it's time to edit the ``Dockerfile``. This defines how to build the image Docker Entrypoint ================= -#. Okay, let's move on to our ``docker_entrypoint.sh`` file. This is a script that defines what to do when the service starts, and often acts as an init system. It will need to complete any environment setup (such as folder substructure), set any environment variables, and execute the run command. It's also PID 1 in the docker container, so it does all of the signal handling and container exits when it is stopped/exits. If you have built a ``configurator``, this will also need to be called to execute here. Let's take a look at our (extremely basic) Hello World example: +#. Okay, let's move on to our ``docker_entrypoint.sh`` file. This is a script that defines what to do when the service starts, and often acts as an init system. It will need to complete any environment setup (such as folder substructure), set any environment variables, and execute the run command. It's also PID 1 in the docker container, so it does all of the signal handling and container exits when it is stopped/exits. If you have built a "configurator," this will also need to be called to execute here. More on configurators below. Let's take a look at our (extremely basic) Hello World example: .. code:: bash @@ -330,6 +330,17 @@ Docker Entrypoint For a more detailed ``docker_entrypoint.sh``, please check out the `filebrowser-wrapper `_. Additional details on the ``Dockerfile`` and ``docker_entrypoint`` can be found `here `_. +Configurators +............. + +- Broadly, a "configurator" is any code that translates the configuration coming from the OS to a format the service can understand. Technically all services with a config have one of these (so, most services on Embassy). The configurator also writes the stats.yaml file, which is used in properties. + +- Narrowly, a configurator is a piece of code separate from the docker_entrypoint.sh script, that does the same as the task above. If you can configure the service in bash, inside the docker_entrypoint.sh script, then you don't need a separate piece of code called "configurator", as we have in LND, CL, and synapse, for example. You might want to create a separate configurator if configuring your service would be complicated or impossible in bash. In the case of CL and LND (and bitcoind, where the configurator is actually called a "manager"), the configurator actually has a long-running element that runs concurrently with the service itself. + +There's really no reason a service has to be engineered in this manner. It's really up to the package maintainer how they want to accomplish translation of the config and implementing the properties action, which doesn't even require a stats.yaml file as of 0.3. + +You can check out an example configurator in the `BitcoinD Wrapper `_, which in this case is called a manager. + Makefile (Optional) =================== diff --git a/site/source/support/dev-docs/service-packaging/manifest.rst b/site/source/support/dev-docs/service-packaging/manifest.rst index 34418cf..4f37955 100644 --- a/site/source/support/dev-docs/service-packaging/manifest.rst +++ b/site/source/support/dev-docs/service-packaging/manifest.rst @@ -15,7 +15,7 @@ This file describes the service and it's requirements. It is used to: Each time a service is updated, the manifest should be updated to include the new version, release notes, and any pertinent updates to the install, uninstall, or restoration flows. All this information is displayed in the marketplace listing, and the optionally denoted alerts will be displayed when appropriate to provide the user with more information. -For instance, `LND displays alerts `_ around restoration since data will be overwritten. +For instance, `LND displays alerts `_ around restoration since data will be overwritten. There is nothing you need to do as a developer to set up Tor for running a service. This is *completely* handled by EmbassyOS - a Tor address will be automatically generated when the service is installed. Just define the port and which version of Tor the service needs in this manifest file! You do, however, need to ensure the service is in fact capable of running over Tor. diff --git a/site/source/support/user-manual/tuning/service-guides/vaultwarden.rst b/site/source/support/user-manual/tuning/service-guides/vaultwarden.rst index ec33c8b..228cc92 100644 --- a/site/source/support/user-manual/tuning/service-guides/vaultwarden.rst +++ b/site/source/support/user-manual/tuning/service-guides/vaultwarden.rst @@ -4,11 +4,11 @@ Vaultwarden =========== -.. _vaultwarden-setup: - Guides ------ -Check out our `Vaultwarden video `_ for features and setup! +Check out our `Vaultwarden video `_ for basic features and setup! .. youtube:: YcxxVHpm9j0 + +See our full, updated `Vaultwarden Guide `_ for detailed setup and third party integrations.