Add docker-compose setup example (superfly#6)

* gitignore text editor backup files

* Move fly.io specific config to subdirectory

* Add Docker/docker-compose config

* Update READMEs/Dockerfile comments explaining the docker setup

* Remove fly proxy config from docker-compose litefs yml files

* Set candidate based on env var for docker setup

---------

Co-authored-by: Darla Shockley <[email protected]>

Author: magdalene

.gitignore

@@ -1 +1,3 @@
 fly.toml
+*~
+*#

Dockerfile

@@ -1,19 +1,28 @@
 # Build our application using a Go builder.
 FROM golang:1.20 AS builder
+
 WORKDIR /src/litefs-example
 COPY . .
 RUN go build -buildvcs=false -ldflags "-s -w -extldflags '-static'" -tags osusergo,netgo -o /usr/local/bin/litefs-example ./cmd/litefs-example
 
 
 # Our final Docker image stage starts here.
 FROM alpine
+ARG LITEFS_CONFIG=litefs.yml
 
 # Copy binaries from the previous build stages.
 COPY --from=flyio/litefs:0.4 /usr/local/bin/litefs /usr/local/bin/litefs
 COPY --from=builder /usr/local/bin/litefs-example /usr/local/bin/litefs-example
 
-# Copy our LiteFS configuration.
-ADD etc/litefs.yml /etc/litefs.yml
+# Copy the possible LiteFS configurations.
+ADD fly-io-config/etc/litefs.yml /tmp/litefs.yml
+ADD docker-config/etc/litefs.static-lease.yml /tmp/litefs.static-lease.yml
+
+# Move the appropriate LiteFS config file to /etc/ (this one will be
+# used by LiteFS). By default this is the config file used on Fly.io,
+# but it's set appropriately to other files for the docker setup in
+# docker-compose.yml
+RUN cp /tmp/$LITEFS_CONFIG /etc/litefs.yml
 
 # Setup our environment to include FUSE & SQLite. We install ca-certificates
 # so we can communicate with the Consul server over HTTPS. cURL is added so

README.md

@@ -1,96 +1,11 @@
 LiteFS Example Application
 ==========================
 
-This repository is an example of a toy application running on LiteFS on Fly.io.
+This repository is an example of a toy application running on LiteFS. You can
+test it out by deploying to Fly.io, or locally with a docker-compose setup.
 
-## Prerequisites
+* [Fly.io instructions](./fly-io-config)
+* [Docker-compose instructions](./docker-config)
 
-First, you'll need to install [`flyctl`][] and then [sign up for a free account][signup].
-
-[`flyctl`]: https://fly.io/docs/hands-on/install-flyctl/
-[signup]: https://fly.io/docs/hands-on/sign-up/
-
-
-## Usage
-
-### Creating the application
-
-First, we'll need to create our application on [Fly.io](https://fly.io). This
-will prompt you for a name or you can autogenerate one for this example.
-Remember this name as we'll need it later.
-
-```sh
-fly launch --region ord --no-deploy
-```
-
-The launch command will create a `fly.toml` file and set the primary region to
-Chicago (`ord`) but will not launch the app.
-
-
-### Creating a volume
-
-Next, we need to set up a persistent volume in our primary region so that our
-data is not lost between restarts.
-
-```sh
-fly volumes create -r ord --size 1 litefs
-```
-
-And add a mount to this volume in your `fly.toml` file:
-
-```toml
-[mounts]
-  source = "litefs"
-  destination = "/var/lib/litefs"
-```
-
-### Setting up Consul
-
-LiteFS uses [Consul](https://consul.io) for its distributed lease. You can find
-instructions for using Fly.io's free multi-tenant Consul in the
-[Lease Management][] section of the Getting Started guide.
-
-[Lease Management]: https://fly.io/docs/litefs/getting-started/#lease-configuration
-
-
-### Launching your app
-
-The next step is to launch & deploy your app with the following command:
-
-```sh
-fly deploy
-```
-
-The application should build and deploy and you should see it up in running
-after a minute or so. You can go to `https://$APPNAME.fly.dev/` and see your
-application running live.
-
-The application is a simple interface for generating fake records. It's just
-for illustrating how LiteFS can easily replicate your data between nodes.
-
-When you click the _"Generate Record"_ button, it will create that row in a
-local SQLite database that is running on a LiteFS file system. Any other node
-running LiteFS will automatically get those updates and apply them to their
-local copy of the database. That lets every node keep an exact copy of the same
-database.
-
-
-### Launching more regions
-
-This example application is configured to run as a primary only in the
-`PRIMARY_REGION` (which is Chicago). It's best practice to run two or more
-instances in the primary region and then you can add instances in additional
-regions to reduce latency for your users.
-
-You can clone the configuration of the machine to other regions by using the
-`fly m clone` command. The `--select` flag lets you choose from a list of
-existing machines to clone.
-
-```sh
-# Make a second instance in your primary region.
-fly m clone --select --region ord
-
-# Make additional instances in regions around the world (London, Sydney, etc).
-fly m clone --select --region lhr
-fly m clone --select --region syd
-```
+**Note: commands should be run from the top-level directory for both Fly.io and
+local docker-compose (not from the location of the README files above).**

docker-compose.yml

@@ -0,0 +1,29 @@
+version: '3'
+services:
+  nginx:
+    build:
+      context: ./docker-config/nginx
+    ports:
+      - "8080:80"
+  primary:
+    build:
+      context: .
+      args:
+        - "LITEFS_CONFIG=litefs.static-lease.yml"
+    ports:
+    - "8081:8081"
+    privileged: true
+    environment:
+      FLY_REGION: primary
+      IS_PRIMARY: "true"
+  replica1:
+    build:
+      context: .
+      args:
+        - "LITEFS_CONFIG=litefs.static-lease.yml"
+    ports:
+    - "8082:8081"
+    privileged: true
+    environment:
+      FLY_REGION: replica1
+      IS_PRIMARY: "false"

docker-config/README.md

@@ -0,0 +1,39 @@
+LiteFS Example Application with Docker
+======================================
+
+## Prerequisites
+
+You need to [install Docker][] (and docker-compose, which is included in all
+recent releases of Docker).
+
+[install Docker]: https://docs.docker.com/engine/install/
+
+## Usage
+
+### Running the app
+
+You can run the application with this command (from the top-level directory
+of the repo):
+
+```bash
+docker-compose up
+```
+
+### Using the app locally
+
+The app is configured with the following containers:
+
+* `primary` - this is the application with LiteFS running as primary
+(all writes happen on this node)
+* `replica1` - this is the application running with LiteFS as a replica
+* `nginx` - nginx configured as a load balancer, and also configured to
+route all `POST` requests to the primary node
+
+Each of these is available to test out locally:
+
+* http://localhost:8080 - the load balancer
+* http://localhost:8081 - the primary
+* http://localhost:8082 - the replica
+
+You can test generating records on each node (it will fail if attempted on
+the replica).

docker-config/etc/litefs.static-lease.yml

@@ -0,0 +1,35 @@
+# note: there should be one template for this, which you can update as necessary.
+# note: had to leave the getting started guide and go to the lease management section bc not using fly
+# note: lease.hostname and lease.advertise-url are not clear
+# note: we should have an example docker-compose setup with everything working both with consul
+# and static leases
+# This directory is where your application will access the database.
+fuse:
+  dir: "/litefs"
+
+# This directory is where LiteFS will store internal data.
+# You must place this directory on a persistent volume.
+data:
+  dir: "/var/lib/litefs"
+
+# The lease section defines how LiteFS creates a cluster and
+# implements leader election. For dynamic clusters, use the
+# "consul". This allows the primary to change automatically when
+# the current primary goes down. For a simpler setup, use
+# "static" which assigns a single node to be the primary and does
+# not failover.
+lease:
+  # Required. Must be either "consul" or "static".
+  type: "static"
+
+  # Required. The URL for this node's LiteFS API.
+  # Should match HTTP port.
+  advertise-url: "http://primary:20202"
+
+  # Specifies whether the node can become the primary. If using
+  # "static" leasing, this should be set to true on the primary
+  # and false on the replicas.
+  candidate: $IS_PRIMARY
+
+exec:
+  - cmd: "litefs-example -addr :8081 -dsn /litefs/db"

docker-config/nginx/Dockerfile

@@ -0,0 +1,5 @@
+FROM nginx:alpine
+
+COPY ./nginx.conf /etc/nginx/nginx.conf
+EXPOSE 80
+CMD ["nginx", "-g", "daemon off;"]

docker-config/nginx/nginx.conf

@@ -0,0 +1,20 @@
+http {
+    upstream primary {
+        server primary:8081;
+    }
+    upstream all {
+        server primary:8081;
+        server replica1:8081;
+    }
+    server {
+        listen 80;
+        location / {
+            if ($request_method ~ "(PUT|POST|PATCH|DELETE)") {
+                proxy_pass http://primary;
+            }
+            proxy_pass http://all;
+        }
+    }
+}
+
+events { }

fly-io-config/README.md

@@ -0,0 +1,94 @@
+LiteFS Example Application on Fly.io
+====================================
+
+## Prerequisites
+
+First, you'll need to install [`flyctl`][] and then [sign up for a free account][signup].
+
+[`flyctl`]: https://fly.io/docs/hands-on/install-flyctl/
+[signup]: https://fly.io/docs/hands-on/sign-up/
+
+
+## Usage
+
+### Creating the application
+
+First, we'll need to create our application on [Fly.io](https://fly.io). This
+will prompt you for a name or you can autogenerate one for this example.
+Remember this name as we'll need it later.
+
+```sh
+fly launch --region ord --no-deploy
+```
+
+The launch command will create a `fly.toml` file and set the primary region to
+Chicago (`ord`) but will not launch the app.
+
+
+### Creating a volume
+
+Next, we need to set up a persistent volume in our primary region so that our
+data is not lost between restarts.
+
+```sh
+fly volumes create -r ord --size 1 litefs
+```
+
+And add a mount to this volume in your `fly.toml` file:
+
+```toml
+[mounts]
+  source = "litefs"
+  destination = "/var/lib/litefs"
+```
+
+### Setting up Consul
+
+LiteFS uses [Consul](https://consul.io) for its distributed lease. You can find
+instructions for using Fly.io's free multi-tenant Consul in the
+[Lease Management][] section of the Getting Started guide.
+
+[Lease Management]: https://fly.io/docs/litefs/getting-started/#lease-configuration
+
+
+### Launching your app
+
+The next step is to launch & deploy your app with the following command:
+
+```sh
+fly deploy
+```
+
+The application should build and deploy and you should see it up in running
+after a minute or so. You can go to `https://$APPNAME.fly.dev/` and see your
+application running live.
+
+The application is a simple interface for generating fake records. It's just
+for illustrating how LiteFS can easily replicate your data between nodes.
+
+When you click the _"Generate Record"_ button, it will create that row in a
+local SQLite database that is running on a LiteFS file system. Any other node
+running LiteFS will automatically get those updates and apply them to their
+local copy of the database. That lets every node keep an exact copy of the same
+database.
+
+
+### Launching more regions
+
+This example application is configured to run as a primary only in the
+`PRIMARY_REGION` (which is Chicago). It's best practice to run two or more
+instances in the primary region and then you can add instances in additional
+regions to reduce latency for your users.
+
+You can clone the configuration of the machine to other regions by using the
+`fly m clone` command. The `--select` flag lets you choose from a list of
+existing machines to clone.
+
+```sh
+# Make a second instance in your primary region.
+fly m clone --select --region ord
+
+# Make additional instances in regions around the world (London, Sydney, etc).
+fly m clone --select --region lhr
+fly m clone --select --region syd
+```