diff --git a/DOCKER.md b/DOCKER.md new file mode 100644 index 0000000..a546e97 --- /dev/null +++ b/DOCKER.md @@ -0,0 +1,83 @@ +# Docker + + +## Prerequisites + +The only prerequisites are: +1. This repo, and +2. Docker + +Building the docker image pulls in all the dev dependencies to build loop within the image itself. Having a `go` development environment is not required. + + +## Building the Docker Image + +The docker image can be built using this command within the `loop` directory: +``` +docker build --tag loop . +``` +This command pulls down a `go` build container, builds `loop` and `loopd` executables, then publishes those binaries to a fresh, smaller image, and marks that image with the tag 'loop'. + + +## Running the Docker Image + +The docker image contains: +* The binary `loopd`, at `/go/bin/loopd` +* The binary `loop`, at `/go/bin/loop` + +Docker is very flexible so you can use that information however you choose. This guide isn't meant to be prescriptive. + + +### Example: Running loopd + +One way of running `loopd` is +``` +docker run --rm -it --name loopd -v $HOME/.lnd:/root/.lnd -v $HOME/.loop:/root/.loop loop:latest loopd --network=testnet --lnd.host :10009 +``` + +Things to note from this docker command: +* You can stop the server with Control-C, and it'll clean up the associated stopped container automatically. +* The name of the running container is 'loopd' (which you may need to know to run the `loop` command). +* The '.lnd' directory in your home directory is mapped into the container, and `loopd` will look for your tls.cert and macaroon in the default locations. If this isn't appropriate for your case you can map whatever directories you choose and override where `loopd` looks for them using additional command-line parameters. +* The '.loop' directory in your home directory is mapped into the container, and `loopd` will use that directory to store some state. +* You probably need to specify your LND server host and port explicitly, since by default `loopd` looks for it on localhost and there is no LND server on localhost within the container. +* No ports are mapped, so it's not possible to connect to the running `loopd` from outside the container. (This is deliberate. You can map ports 8081 and 11010 to connect from outside the container if you choose.) + + +### Example: Running loop + +If you're using the example above to run `loopd`, you can then run the `loop` command inside that running container to execute loops. One way would be: +``` +docker exec -it loopd loop out --channel --amt +``` + +Things to note about this docker command: +* `docker exec` runs a command on an already-running container. In this case `docker exec loopd` says effectively 'run the rest of this command-line as a command on the already-running container 'loopd'. +* The `-it` flags tell docker to run the command interatively and act like it's using a terminal. This helps with commands that do more than just write to stdout. +* The remainder `loop out --channel --amt ` is the actual loop command you want to run. All the regular `loop` documentation applies to this bit. + + +### A Handy Script + +If you're using the example above to run `loopd`, creating a script can simplify running `loop`. + +Create a file with the following contents: +``` +#!/usr/bin/env bash +TERMINAL_FLAGS= +if [ -t 1 ] ; then + TERMINAL_FLAGS="-it" +fi + +docker exec $TERMINAL_FLAGS loopd loop "${@}" +``` +Call this script 'loop', put it somewhere in your $PATH, and make it executable. Then you can just run commands like: +``` +loop out --channel --amt +``` +without having to remember (or use) the docker part explicitly. + + +## Caveats + +Running `loopd` the way shown above won't restart `loopd` if it is stopped or if the computer is restarted. You may want to investigate running the 'loop' container at startup, or when your LND server starts. (For example, `docker` has restart options, or grouping of containers via `docker-compose`.) \ No newline at end of file diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..238443e --- /dev/null +++ b/Dockerfile @@ -0,0 +1,33 @@ +FROM golang:1.12-alpine as builder + +# Copy in the local repository to build from. +COPY . /go/src/github.com/lightningnetwork/loop + +# Force Go to use the cgo based DNS resolver. This is required to ensure DNS +# queries required to connect to linked containers succeed. +ENV GODEBUG netdns=cgo + +# Explicitly turn on the use of modules (until this becomes the default). +ENV GO111MODULE on + +# Install dependencies and install/build lnd. +RUN apk add --no-cache --update alpine-sdk \ + git \ + make \ +&& cd /go/src/github.com/lightningnetwork/loop/cmd \ +&& go install ./... + +# Start a new, final image to reduce size. +FROM alpine as final + +# Expose lnd ports (server, rpc). +EXPOSE 8081 11010 + +# Copy the binaries and entrypoint from the builder image. +COPY --from=builder /go/bin/loopd /bin/ +COPY --from=builder /go/bin/loop /bin/ + +# Add bash. +RUN apk add --no-cache \ + bash \ + ca-certificates