From ddc33e849f29c4563cd62769e801315e1e54bf02 Mon Sep 17 00:00:00 2001 From: Griffin Smith Date: Sat, 29 Jan 2022 12:44:26 -0500 Subject: [PATCH] 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 Autosubmit: grfn Tested-by: BuildkiteCI --- users/grfn/bbbg/README.org | 125 ++++++++++++++++++++++++++++++ users/grfn/bbbg/src/bbbg/core.clj | 13 +++- 2 files changed, 137 insertions(+), 1 deletion(-) create mode 100644 users/grfn/bbbg/README.org diff --git a/users/grfn/bbbg/README.org b/users/grfn/bbbg/README.org new file mode 100644 index 000000000..e762aa019 --- /dev/null +++ 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) +# +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 diff --git a/users/grfn/bbbg/src/bbbg/core.clj b/users/grfn/bbbg/src/bbbg/core.clj index 70c7da50d..632774d5c 100644 --- 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))) + )