diff --git a/README.org b/README.org index 291a191..7bd2568 100644 --- a/README.org +++ b/README.org @@ -1,8 +1,21 @@ +* Development Notes + +- Currently, only tested on Linux (Debian). Everything should + theoretically also work on Mac but some commands may need updating + and it has not been tested, but multi-platform support, except for + Windows, was kept in mind during development. + * Project Goal To make deploying, managing, and updating self-hosted app instances easy. +* Short Note On Generative AI + +This project does NOT use any code or documentation generated by an +LLM and no code or text generated by an LLM is acceptable as a +contribution. + * Supported Services Currently, only a limited set of external services can be used for @@ -31,15 +44,31 @@ but also so that when developing the Terraform and Docker Compose setup it can be done and tested without needing to deal with the web app as well. -** Setup "Base" CLI Terraform For Deploying Individual Instance -*** Dependencies +** Webapp + +The webapp is used both to provide a more "user-friendly" interface +for setting up and managing instances as well as to provide a +multi-user and multi-instance service. Internally, to manage an +instance, the webapp generates the configs and invokes the same +commands used when running the "base" CLI version by itself. + +* Setup "Base" CLI Terraform For Deploying Individual Instance + +NOTE: some of this may be outdated. It has not been tested on its own +outside of running via the webapp for a bit. It does work when run via +the webapp and all of the services still need to be setup as +detailed (the data can be input via the webapp instead of only via the +config files). + +** Dependencies - [[https://developer.hashicorp.com/terraform/install][terraform]] - [[https://www.docker.com/][docker]] - bash +- GNU Make -*** Services +** Services -**** [[https://www.digitalocean.com/][DigitalOcean]] +*** [[https://www.digitalocean.com/][DigitalOcean]] - Create a DigitalOcean account and sign in to it @@ -51,7 +80,7 @@ app as well. - set the "scope" to "Full Access" - save the generated token for placing in production.tfvars -> do_token -**** [[https://www.cloudflare.com/][Cloudflare]] +*** [[https://www.cloudflare.com/][Cloudflare]] - Create a CloudFlare account and sign into it @@ -73,7 +102,7 @@ app as well. These will be used later on in config/production.tfvars for cloudflare_zone_id and cloudflare_account_id -**** [[https://backblaze.com][Backblaze]] +*** [[https://backblaze.com][Backblaze]] This is used automated for "off-site" backups / snapshots. @@ -100,39 +129,65 @@ This is used automated for "off-site" backups / snapshots. - Click "Create new key" - Copy/save the key for later use in config/apps.config BACKBLAZE_APPLICATION_KEY and the "keyID" for BACKBLAZE_KEY_ID -*** Configuration -**** apps.config +** Configuration +*** apps.config - ~cp config/apps.config.tmpl config/apps.config~ - then edit ~config/apps.config~ and fill in all variables -**** production.tfvars +*** production.tfvars - ~cp config/production.tfvars.tmpl config/production.tfvars~ - then edit ~config/production.tfvars~ and fill in all variables -**** ssh keys +*** ssh keys - ~touch config/ssh-keys~ - if you want to add your ssh key(s) for debugging then paste the pub ID in to the file -**** initializing the "off-site" Restic backups +*** initializing the "off-site" Restic backups - ~make restic-init~ -*** Deploy +** Deploy - ~make apply~ -*** You're done! +** You're done! It will take a few minutes to deploy the server, start it, and pull all the docker images. But after that you should be able to visit your site and the apps running on its subdomains! -** Webapp +* Setup Webapp +** Dependencies + +- [[https://code.call-cc.org/][CHICKEN Scheme 5.3+]] +- docker +- GNU Make + +The webapp is written in Lisp (CHICKEN Scheme) and connects to a +PostgreSQL database. It also depends on being able to run some docker +commands. It has only been tested on Linux. Running the commands on +other platforms may need work. A Makefile command is provided for +running the Postgres database via docker so Postgres is not a listed +as a direct dependency. + +** CHICKEN Scheme Libraries + +These will need to be installed via the ~chicken-install~ command. + +~postgresql sql-null srfi-1 srfi-13 srfi-18 srfi-158 srfi-194 openssl crypto-tools sxml-transforms schematra schematra-body-parser schematra-session uri-common http-client medea intarweb~ + +** html-widgets +This is a CHICKEN Scheme library that also needs to be installed but +it is not available via the ~chicken-install~ repository as I wrote it +for this project and I have not published it externally yet. You can +get the project here: [[https://code.thintz.com/tjhintz/html-widgets][https://code.thintz.com/tjhintz/html-widgets]] +After downloading the project, you can install it by ~cd~ to the +directory it is in and then running ~chicken-install~.