2019 11 28 cli native image doc (#903)

* Add documentation about how the cli can be built with a native image

* Finish rest of documentation on building command line client for bitcoin-s

* Add missing akka actor on walletServer classpath, add plugins to be able to build the walletServer as a standalone jar

* Add server.md

* Rename walletServer -> appServer

* Address code review, add missing main class in server project

* Address code review

app/cli/cli.sbt

@@ -4,11 +4,14 @@ libraryDependencies ++= Deps.cli(scalaVersion.value)
 
 graalVMNativeImageOptions ++= Seq(
   "-H:EnableURLProtocols=http",
+
+  "-H:+ReportExceptionStackTraces",
   // builds a stand-alone image or reports a failure
   "--no-fallback",
   // without this, we get complaints about Function3
   // I'm not sure why, though...
   "--initialize-at-build-time=scala.Function3",
+  "--report-unsupported-elements-at-runtime",
   "--verbose"
 )
 

app/server/server.sbt

@@ -5,3 +5,20 @@ name := "bitcoin-s-server"
 Compile / fork := true
 
 libraryDependencies ++= Deps.server(scalaVersion.value)
+
+mainClass := Some("org.bitcoins.server.Main")
+
+graalVMNativeImageOptions ++= Seq(
+  "-H:EnableURLProtocols=http",
+
+  "-H:+ReportExceptionStackTraces",
+  // builds a stand-alone image or reports a failure
+  "--no-fallback",
+  // without this, we get complaints about Function3
+  // I'm not sure why, though...
+  "--initialize-at-build-time=scala.Function3",
+  "--report-unsupported-elements-at-runtime",
+  "--verbose"
+)
+
+enablePlugins(JavaAppPackaging, GraalVMNativeImagePlugin)

build.sbt

@@ -56,8 +56,8 @@ lazy val `bitcoin-s` = project
     picklers,
     wallet,
     walletTest,
-    walletServer,
-    walletServerTest,
+    appServer,
+    appServerTest,
     testkit,
     zmq
   )
@@ -197,7 +197,7 @@ lazy val coreTest = project
     testkit
   )
 
-lazy val walletServer = project
+lazy val appServer = project
   .in(file("app/server"))
   .settings(CommonSettings.prodSettings: _*)
   .dependsOn(
@@ -208,12 +208,12 @@ lazy val walletServer = project
     bitcoindRpc
   )
 
-lazy val walletServerTest = project
+lazy val appServerTest = project
   .in(file("app/server-test"))
   .settings(CommonSettings.testSettings)
   .settings(libraryDependencies ++= Deps.walletServerTest)
   .dependsOn(
-    walletServer,
+    appServer,
     testkit
   )
 
@@ -349,7 +349,7 @@ lazy val testkit = project
   .settings(CommonSettings.prodSettings: _*)
   .dependsOn(
     core % testAndCompile,
-    walletServer,
+    appServer,
     chain,
     bitcoindRpc,
     eclairRpc,

docs/applications/cli.md

@@ -0,0 +1,63 @@
+---
+id: cli
+title: bitcoin-s cli
+---
+
+
+## Bitcoin-s command line interface
+
+The [cli](../../app/cli/) project is meant to be a bitcoin-s command line interface (cli). It uses [graalvm native image](https://www.graalvm.org/docs/reference-manual/native-image/) to
+create a native executable that circumvents the jvm for fast start up time.
+
+### Building the command line interface
+
+#### Installing graalvm native image
+First to build the command line interface you need to have the graal jdk installed. This can be installed on [graalvm's github](https://github.com/graalvm/graalvm-ce-builds/releases/).
+
+Make sure you install the [prerequisites](https://www.graalvm.org/docs/reference-manual/native-image/#prerequisites) for installing the `native-image` executable.
+
+
+If you do not have the `native-image` executable installed, you need to install it with
+
+```bashrc
+./graalvm-ce-java8-19.3.0/bin/gu install native-image
+```
+
+Once you have the graalvm installed you should be able to verify you have the `native-image` exeuctable installed by running
+
+```bashrc
+$ native-image --help
+```
+
+If your command did not work, make sure you can find the `native-image` executable on your `PATH`.
+
+#### Building the native image
+
+Now that you have graalvm native image installed, you should be able to build the cli with. It is important to note that
+this only works with Scala `2.12.x`. I'm unsure of why the native image build fails with Scala `2.13.x`
+
+```bashrc
+$ sbt ++2.12.10 cli/graalvm-native-image:packageBin
+```
+
+After running that command you should find the executable here:
+
+```bash
+bitcoin-s/app/cli/target/graalvm-native-image
+```
+
+#### Executing commands
+You can ask the client for help with
+
+```bash
+ ./app/cli/target/graalvm-native-image/bitcoin-s-cli --help
+Usage: bitcoin-s-cli [options] [<cmd>]
+
+  -n, --network <value>  Select the active network.
+  --debug                Print debugging information
+  -h, --help             Display this help message and exit
+  <cmd>                  The command and arguments to be executed. Try bitcoin-s-cli help for a list of all commands
+```
+
+
+Now you are are ready to start the server that the cli sends commands to. Take a look at our [server](server.md) documentation on how to build and start the server.

docs/applications/server.md

@@ -0,0 +1,35 @@
+id: server
+title: bitcoin-s application server
+---
+
+
+### App server
+
+The [server](../../app/server) project is the aggregation of these three sub projects
+
+1. [Wallet](wallet.md)
+2. [Chain](chain.md)
+3. [Node](node.md)
+
+The server project provides a away to access information from these three projects via a JSON RPC.
+
+### Building the server
+
+You can build the server with the [sbt native packager](https://github.com/sbt/sbt-native-packager).
+The native packager offers [numerous ways to package the project](https://github.com/sbt/sbt-native-packager#examples).
+
+In this example we are going to use `stage` which will produce bash scripts we can easily execute. You can stage the server with the following command
+
+```bash
+ $ sbt appServer/universal:stage
+```
+
+This will produce a script to execute bitcoin-s which you can start with
+
+```bash
+$ ./app/server/target/universal/stage/bin/bitcoin-s-server
+```
+
+For more information on configuring the server please see our [configuration](configuration.md) document
+
+For more information on how to use our built in `cli` to interact with the server please see [cli.md](cli.md)

project/Deps.scala

@@ -195,6 +195,7 @@ object Deps {
     if (scalaVersion.startsWith("2.11")) Compile.oldMicroPickle
     else Compile.newMicroPickle,
     Compile.logback,
+    Compile.akkaActor,
     Compile.akkaHttp
   )