From 2a8a36058f95ffd46491bb31a25ddf1038494691 Mon Sep 17 00:00:00 2001
From: William Perron <hey@wperron.io>
Date: Wed, 7 Sep 2022 20:07:59 +0000
Subject: [PATCH] improve docs

---
 README.md | 167 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 167 insertions(+)

diff --git a/README.md b/README.md
index 3c30aa8..8f9603d 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,170 @@
 # themis
 
 Discord App to allow EU4 players to take claims on regions and provinces.
+
+## Setup
+
+### Requirements
+
+To develop:
+- [Go](https://go.dev/) version 1.19 or higher installed locally
+- `sqlite3` installed locally (already ships by default on most OSes)
+
+To deploy:
+- Register for a [free account on Fly](https://fly.io)
+- An [AWS account](https://console.aws.amazon.com)
+
+### Steps
+
+To work with the core modules that simply interact with the database, or make
+sure that everything compiles correctly, you can run the following commands:
+
+```bash
+go test ./...
+go build -o ./bin/ ./cmd/...
+```
+
+## Operations
+
+This application is deployed via [Fly](https://fly.io) on a single virtual
+machine instance. It uses an embed SQLite database as its database engine, and
+uses [Litestream](https://litestream.io) to replicate the database to an S3
+bucket.
+
+### Application Configuration
+
+The deployment configurations can be found in the [fly.toml](/fly.toml) file and
+you can find more information on the configuration options [in the official Fly
+documentation](https://fly.io/docs/reference/configuration/).
+
+The virtual image is based off of the [Dockerfile](/Dockerfile) which is a
+multi-stage build that builds the main application binary, downloads Litestream
+and packages everything on top of an Ubuntu 22.04 base.
+
+### Entrypoint
+
+The application is started using a [custom entrypoint shell script](/start.sh)
+that is in charge of first restoring the database file through Litestream and
+then starting the main application as a [child process of Litestream's
+replication process](https://litestream.io/reference/replicate/#arguments).
+
+It's a very simple script but is necessary since the application doesn't have a
+persistent volume to rely on and must rehydrate its database file after every
+deployment.
+
+### Environment Variables
+
+| Env Var                 | Defined At            |
+| ----------------------- | --------------------- |
+| `DISCORD_TOKEN`         | fly secret            |
+| `DISCORD_APP_ID`        | [fly.toml](/fly.toml) |
+| `DISCORD_GUILD_ID`      | [fly.toml](fly.toml)  |
+| `AWS_ACCESS_KEY_ID`     | fly secret            |
+| `AWS_SECRET_ACCESS_KEY` | fly secret            |
+
+## Local Development
+
+### Application Entrypoint
+
+- `./cmd/themis-server` This is the main application entrypoint
+- `./cmd/themis-repl` _coming soon_
+
+### Core Functions
+
+The core database functions can be developed and tested locally easily, just run
+`go test ./...` to test your changes locally.
+
+You can also load a test database easily by using the `init.sql` script. You can
+use the cli sqlite3 client or connect using whatever SQL editor you prefer that
+can open sqlite3 connections.
+
+```bash
+sqlite3 local.db < migrations/init.sql
+sqlite3 local.db
+# interactive SQLite session
+```
+
+### Discord Integration
+
+This is a work in progress, but I am currently using a dedicated Discord server
+with this application already signed into it. You can contact me directly to be
+invited into that server. From there you only need to set the following
+environment variables before launching the `./cmd/themis-server` entrypoint:
+
+```bash
+export DISCORD_APP_ID="1014881815921705030"
+export DISCORD_GUILD_ID="[test server id goes here]"
+```
+
+### Litestream replication
+
+Litestream is _not a necessary component_ to run the `./cmd/themis-server`
+entrypoint and can be safely ignored when developing locally. Still, if you wish
+to try it out, you can find the Litestream commands used in production in the
+[start.sh](/start.sh) script. As per the Litestream docs, it should work fine
+with [Minio](https://min.io/) but I have not tested it yet nor are there any
+scripts provided to run it (yet).
+
+## SQLite
+
+### Importing From CSV
+
+This is a neat feature built-in to SQLite. Using the source file at
+[data/eu4-provinces.csv](/data/eu4-provinces.csv) you can import the data
+directly into a SQLite database using the following command:
+
+```bash
+$ sqlite3
+# ...
+sqlite> .mode csv
+sqlite> .import data/eu4-provinces.csv provinces
+sqlite> .schema provinces
+CREATE TABLE provinces(
+  "ID" TEXT,
+  "Name" TEXT,
+  "Development" TEXT,
+  "BT" TEXT,
+  "BP" TEXT,
+  "BM" TEXT,
+  "Trade good" TEXT,
+  "Trade node" TEXT,
+  "Modifiers" TEXT,
+  "Type" TEXT,
+  "Continent" TEXT,
+  "Superregion" TEXT,
+  "Region" TEXT,
+  "Area" TEXT
+);
+sqlite> select count(1) from provinces;
+3925
+```
+
+### Creating an SQL Dump From Imported Data
+
+The init script at [migrations/init.sql](/migrations/init.sql) was initially
+created after importing the CSV data and running the following commands:
+
+```bash
+# In the same SQlite session as last section
+sqlite> .output dump.sql
+sqlite> .dump
+```
+
+Note: The column names were _edited manually_ to remove capital letters and
+spaces to make it easier to work with.
+
+### Claims Schema
+
+```sql
+CREATE TABLE claim_types (
+    claim_type TEXT PRIMARY KEY
+);
+
+CREATE TABLE claims (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    player TEXT,
+    claim_type TEXT,
+    val TEXT,
+    FOREIGN KEY(claim_type) REFERENCES claim_types(claim_type)
+);
+```