feat(grfn/bbbg): Add info on running the app

Add a README.org with info on installing dependencies and running the app outside Emacs, and add a comment at the end of core.clj with info on running the app inside Emacs with CIDER. Change-Id: Ie7e73f71a98425092782facd80ceec2a8995bb0d Reviewed-on: https://cl.tvl.fyi/c/depot/+/5115 Reviewed-by: grfn <grfn@gws.fyi> Autosubmit: grfn <grfn@gws.fyi> Tested-by: BuildkiteCI
2022-01-29 12:44:26 -05:00 · 2022-01-29 12:44:26 -05:00 · ddc33e849f
commit ddc33e849f
parent a12ffa41de
2 changed files with 137 additions and 1 deletions
--- a/users/grfn/bbbg/README.org
+++ b/users/grfn/bbbg/README.org
@ -0,0 +1,125 @@
+#+TITLE: Brooklyn-Based Board Gaming Signup Sheet
+
+ This directory contains a small web application that acts as a signup sheet and
+ attendee tracking system for [[https://www.meetup.com/brooklyn-based-board-gaming/][my local board gaming meetup]].
+
+* Development
+
+** Installing dependencies
+
+*** With Nix + Docker ("blessed way")
+
+Prerequisites:
+
+- [[https://nixos.org/][Nix]]
+- [[https://github.com/nix-community/lorri][lorri]]
+- [[https://www.docker.com/][Docker]]
+
+From this directory in a full checkout of depot, run the following commands to
+install all development dependencies:
+
+#+begin_src shell-session
+$ pwd
+/path/to/depot/users/grfn/bbbg
+$ direnv allow
+$ lorri watch --once # Wait for a single nix shell build
+#+end_src
+
+Then, to run a docker container with the development database:
+
+#+begin_src shell-session
+$ pwd
+/path/to/depot/users/grfn/bbbg
+$ arion up -d
+#+end_src
+
+*** Choose-your-own-adventure
+
+Note that the *authoritative* source for dev dependencies is the ~shell.nix~
+file in this directory - those may diverge from what's written here, and if so
+follow those versions rather than these.
+
+- Install the [[https://clojure.org/guides/getting_started][clojure command-line tools]], with openjdk 11
+- Install and run a postgresql 12 database, with:
+  - A user with superuser priveleges, the username ~bbbg~ and the password ~password~
+  - A database called ~bbbg~ owned by that user.
+- Export the following environment variables in a context visible by whatever
+  method you use to run the application:
+  - ~PGHOST=localhost~
+  - ~PGUSER=bbbg~
+  - ~PGDATABASE=bbbg~
+  - ~PGPASSWORD=bbbg~
+
+** Running the application
+
+Before running the app, you'll need an oauth2 client-id and client secret for a
+Discord app. The application can either load those from a [[https://www.passwordstore.org/][pass]] password store,
+or read them from plaintext files in a directory. In either case, they should be
+accessible at the paths ~bbbg/discord-client-id~ and
+~bbbg/discord-client-secret~ respectively.
+
+*** From the command line
+
+#+begin_src shell-session
+$ clj -A:dev
+Clojure 1.11.0-alpha3
+user=> (require 'bbbg.core)
+nil
+user=> ;; Optionally, if you're using a directory with plaintext files for the discord client ID and client secret:
+user=> (bbbg.util.dev-secrets/set-backend! [:dir "/path/to/that/directory"])
+user=> (bbbg.core/run-dev)
+#<SystemMap>
+user=> (bbbg.db/migrate! (:db bbbg.core/system))
+11:57:26.536 [main] INFO  migratus.core - Starting migrations {  }
+11:57:26.538 [main] INFO  com.zaxxer.hikari.HikariDataSource - HikariPool-1 - Starting... {  }
+11:57:26.883 [main] INFO  com.zaxxer.hikari.pool.HikariPool - HikariPool-1 - Added connection com.impossibl.postgres.jdbc.PGDirectConnection@3cae770e {  }
+11:57:26.884 [main] INFO  com.zaxxer.hikari.HikariDataSource - HikariPool-1 - Start completed. {  }
+11:57:26.923 [main] INFO  migratus.core - Ending migrations {  }
+nil
+#+end_src
+
+This will run a web server for the application listening at http://localhost:8888
+
+*** In Emacs, with [[https://docs.cider.mx/cider/index.html][CIDER]] + [[https://github.com/wbolster/emacs-direnv][direnv]]
+
+Open ~//users/grfn/bbbg/src/bbbg/core.clj~ in a buffer, then follow the
+instructions at the end of the file
+
+* Deployment
+
+** With nix+terraform
+
+Deployment configuration is located in the ~tf.nix~ file, which is currently
+tightly coupled to my own infrastructure and AWS account but could
+hypothetically be adjusted to be general-purpose.
+
+To deploy a new version of the application, after following "installing
+dependencies" above, run the following command in a context with ec2 credentials
+available:
+
+#+begin_src shell
+$ terraform apply
+#+end_src
+
+The current deploy configuration includes:
+
+- An ec2 instance running nixos, with a postgresql database and the bbbg
+  application running as a service, behind nginx with an auto-renewing
+  letsencrypt cert
+- The DNS A record for ~bbbg.gws.fyi~ pointing at that ec2 instance, in the
+  cloudflare zone for ~gws.fyi~
+
+** Otherwise
+
+¯\_(ツ)_/¯
+
+You'll need:
+
+- An uberjar for bbbg; the canonical way of building that is ~nix-build
+  /path/to/depot -A users.grfn.bbbg.server-jar~ but I'm not sure how that works
+  outside of nix
+- A postgresql database
+- Environment variables telling the app how to connect to that database. See
+  ~config.systemd.services.bbbg-server.environment~ in  ~module.nix~ for which
+  env vars are currently being exported by the NixOS module that runs the
+  production version of the app
--- a/users/grfn/bbbg/src/bbbg/core.clj
+++ b/users/grfn/bbbg/src/bbbg/core.clj
@ -54,5 +54,16 @@
   (constantly (component/start (make-system (env->config))))))

 (comment
-  (run-dev)
+  ;; To run the application:
+  ;; 1. `M-x cider-jack-in`
+  ;; 2. `M-x cider-load-buffer` in this buffer
+  ;; 3. (optionally) configure the secrets backend in `bbbg.util.dev-secrets`
+  ;; 4. Put your cursor after the following form and run `M-x cider-eval-last-sexp`
+  ;;
+  ;; A web server will be listening on http://localhost:8888
+
+  (do
+    (run-dev)
+    (bbbg.db/migrate! (:db system)))
+
  )