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
This commit is contained in:
Griffin Smith 2022-01-29 12:44:26 -05:00 committed by clbot
parent a12ffa41de
commit ddc33e849f
2 changed files with 137 additions and 1 deletions

125
users/grfn/bbbg/README.org Normal file
View file

@ -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

View file

@ -54,5 +54,16 @@
(constantly (component/start (make-system (env->config))))))
(comment
;; 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)))
)