Package: dapp-manager
Golem dApp Managerdapp-manageris a purposefully minimalistic manager for decentralized applications running on
Golem. It works together with thedapp-runner.
While the responsibility of the latter is to run a single Golem application,dapp-managertakes
care of spawning, interacting with, and stopping the running instances of thedapp-runner.Quick startYagna daemonAs thedapp-manageruses thedapp-runner, which in turn requires a properly configuredyagnadaemon, you'll need to have it set up.For now, please follow the"Requestor development: a quick primer"tutorial and ensure that youryagnais up and running. Only the first part of this
tutorial is required - you don't need to run the blender example.Most importantly, make sure you have set theYAGNA_APPKEYin your environment, e.g. with:exportYAGNA_APPKEY=insert-your-32-char-app-key-hereor, on Windows:setYAGNA_APPKEY=insert-your-32-char-app-key-hereand if you don't know what your app-key is, you can always queryyagnawith:yagnaapp-keylistPython environmentFirst, ensure you have Python 3.8 or later:python3--version[ depending on the platform, it may be justpythoninstead ofpython3]If your Python version is older, consider usingpyenv.Once your python interpreter reports a version 3.8 or later, you can set up your virtual
environment:python3-mvenv~/.envs/dapp-managersource~/.envs/dapp-manager/bin/activateor, if you're on Windows:python-mvenv--clear%HOMEDRIVE%%HOMEPATH%\.envs\dapp-manager
%HOMEDRIVE%%HOMEPATH%\.envs\dapp-manager\Scripts\activate.batDApp managerClone the repositorygitclone--recurse-submoduleshttps://github.com/golemfactory/dapp-manager.gitInstall the dependenciescddapp-manager
pipinstall-Upippoetry
poetryinstallRun an example applicationMake sure youryagnadaemon is running,
you have initialized the payment driver withyagna payment init --sender,
and that you have set theYAGNA_APPKEYenvironment variable.Then run:dapp-managerstart--configsample_config.ymldapp-store/apps/webapp.yamlThe app is started in a backgrounddapp-runnerprocess, and you're returned an application ID in
the form of a hexadecimal string. You can use this ID to query the state and other output streams
usingdapp-manager'sreadcommand, e.g.:dapp-managerread<the-hex-string>statewill display the contents of thestatestream of the running app:{"db":{"0":"pending"}}{"db":{"0":"starting"}}{"db":{"0":"running"}}{"db":{"0":"running"},"http":{"0":"pending"}}{"db":{"0":"running"},"http":{"0":"starting"}}In case something goes amiss,dapp-managerwill output:App <the-hex-string> is not running.Whatever the reason, you can still query the various streams of a terminated dapp by adding the--no-ensure-aliveoption, e.g.:dapp-managerread<the-hex-string>--no-ensure-alivestderrFull usageUsage:dapp-manager[OPTIONS]COMMAND[ARGS]...

Options:--helpShowthismessageandexit.

Commands:autocompleteEnableCLIshellcompletionforthegivenshell.killStopthegivenappforcibly.listListknownappIDs(bothactiveanddead).pruneRemovedatafornon-runningapps.readReadoutputfromthegivenapp.startStartanewappusingtheprovideddescriptorandconfig...stopStopthegivenappgracefully.StartThestartcommand launches a new instance of thedapp-runnerin a background process and
returns the hexadecimal string that is the identifier of the runningdapp-runnerinstance.Usage:dapp-managerstart[OPTIONS]DESCRIPTORS...Startanewappusingtheprovideddescriptorandconfigfiles.

Options:-c,--configPATHPathtothefilecontainingyagna-specificconfig.[required]--helpShowthismessageandexit.Importantly, it requires a config file which contains the parameters used to connect to theyagnadaemon and initialize the requestor engine. We're providing a default, sample configuration assample_config.ymlin the root of thedapp-managerrepository.Of course, it also requires one or more descriptor files that are used by thedapp-runnerto
deploy the specified applications on Golem.Stop / KillThestopandkillcommands terminate the givendapp-runnerinstance, the main difference
being the signal that's sent to do that. Essentially,stopshould be enough and should give thedapp-runnera chance to shut the app down gracefully, correctly terminating the services,
closing the agreements and paying for them.In casestopis stuck for whatever reason, you might want to resort tokillwhich terminates
thedapp-runnerimmediately without allowing for any graceful shutdown.ListThelistcommand shows the identifiers of all the previously-started apps, whether they're still
running or not.Pruneprunecausesdapp-managerto remove the data for those apps that it had previously identified as
defunct. Consequently, those apps will no longer appear on the list.Unless an app has been explicitly stopped with astoporkillcommand, thedapp-managerwill not purge it until it has had a chance to notice the termination, e.g. by issuing areadcommand to the defunct app.ReadThereadcommand outputs the full contents of the specified stream. There are five streams as
specified by the usage below:Usage:dapp-managerread[OPTIONS]APP_ID[state|data|log|stdout|stderr]Readoutputfromthegivenapp.

Options:--ensure-alive/--no-ensure-alive-f,--follow--helpShowthismessageandexit.By default, the stream will only be output if the app is currently running. Otherwise, you'll get
theApp <the-hex-string> is not running.message and no stream.If you wish to query a stream of a terminated app, add the--no-ensure-aliveparameter to the
specificreadcommand.Shell completionThis program supports shell completion for all of its commands, as well as existing dApp IDs (where applicable).To enable completion, use theautocompletecommand with your shell of choice:bash:dapp-managerautocompletebashzsh:dapp-managerautocompletezshfish:dapp-managerautocompletefishThe completion functions are defined indapp_manager/autocomplete/scripts.Should the entrypoint name ever change, those files will need to be updated as well.WARNINGCompletion willNOT WORKwhenautocompleteis invoked withpython -m dapp_manager.
Only the installed entrypoint (i.e.dapp-manager) is supported. To have it available, runpoetry install.