From 5c78009d142339e218304a98279c54fbdc03ddbf Mon Sep 17 00:00:00 2001
From: Justin Wind <justin.wind+git@gmail.com>
Date: Sat, 12 Oct 2024 13:45:54 -0700
Subject: [PATCH] add more setup documentation
---
README.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 97 insertions(+)
diff --git a/README.md b/README.md
index b565597..e9db9d3 100644
--- a/README.md
+++ b/README.md
@@ -19,6 +19,103 @@ Each ```profile``` may also be associated with a customizable list of additional
An example of the user-interface when granting consent to a client application:
+## Up And Running
+
+Customize configuration within `config/${NODE_ENV}.js`. All envs inherit settings from `default.js` if not specified. Environment is selected using the `NODE_ENV` environment variable value, defaulting to `development` if unset.
+
+Database table initialization and schema version migrations are automated. Configure SQLite with a database file, or point PostgreSQL to a created database.
+
+Users currently need to be created via the cli, using the `bin/authAddUser.js` script.
+
+The bundled logger spews JSON to stdout.
+
+### Quickstart Example
+
+One way of deploying this server is behind nginx, with the pm2 package to manage the server process, and a local postgres database. Some details on this are presented here as a rough guide to any parts of this stack which may be unfamiliar.
+
+- Have NodeJS 20-ish available.
+- Have PostgreSQL available.
+- Clone the server repository.
+ ```git clone https://git.squeep.com/squeep-indie-auther```
+- Install the production dependencies.
+ ```cd squeep-indie-auther```
+ ```NODE_ENV=production npm i```
+- Create a ```config/production.js``` configuration file. See ```config/default.js``` for available settings.
+ > <pre>
+ > 'use strict';
+ > // Minimum required configuration settings
+ > module.exports = {
+ > encryptionSecret: 'this is a secret passphrase, it is pretty important to be unguessable',
+ > dingus: {
+ > selfBaseUrl: 'https://ia.squeep.com/', // it needs to know how to refer to itself
+ > },
+ > db: {
+ > connectionString: 'postgresql://indieauther:mypassword@localhost/indieauther',
+ > },
+ > chores: { // These are optional, but recommended
+ > scopeCleanupMs: 86400000, // remove unused scopes daily
+ > tokenCleanupMs: 864000000, // remove invalid tokens daily
+ > publishTicketsMs: 86400000, // retry queuing redeemed tickets daily
+ > },
+ > };
+ > </pre>
+- Prepare PostgreSQL with a user and database, using e.g. ```psql```.
+ > <pre>
+ > CREATE ROLE indieauther WITH CREATEDB LOGIN PASSWORD 'mypassword';
+ > GRANT indieauther TO postgres;
+ > CREATE DATABASE indieauther OWNER=indieauther;
+ > GRANT ALL PRIVILEGES ON DATABASE indieauther TO indieauther;
+ > \c indieauther
+ > CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
+ > </pre>
+- Install a process manager, system-wide.
+ ```npm i -g pm2```
+- Configure the process manager to keep the server logs from growing unbounded.
+ ```pm2 install pm2-logrotate```
+ ```pm2 set pm2-logrotate:rotateInterval '0 0 1 * *'``` (rotate monthly)
+ ```pm2 set pm2-logrotate:compress true```
+ ```pm2 startup``` (arrange to start process monitor on system boot)
+- Launch the server, running one process per available CPU, and persist it through reboots.
+ ```NODE_ENV=production pm2 start server.js --name indieauther -i max```
+ ```pm2 save```
+- Create a user.
+ ```NODE_ENV=production node bin/authUserAdd.js myusername```
+- Optional: Copy or link the static files to somewhere nginx will serve them from. This will vary greatly depending on your setup.
+ ```cp -rp static /home/indieauther/ia.squeep.com/html/static```
+- Expose the server through nginx.
+ > <pre>
+ > server {
+ > listen 443 ssl http2;
+ > ssl_certificate /etc/ssl/nginx/server-chain.pem;
+ > ssl_certificate_key /etc/ssl/nginx/server.key;
+ > server_name ia.squeep.com;
+ > root /home/indieauther/ia.squeep.com/html
+ > try_files $uri $uri/ @indieauther;
+ >
+ > location @indieauther {
+ > proxy_pass http://indieauther$uri;
+ > proxy_set_header Host $host;
+ > proxy_set_header X-Forwarded-For $remote_addr;
+ > proxy_set_header X-Forwarded-Proto $scheme;
+ > proxy_http_version 1.1;
+ > }
+ >
+ > location = / {
+ > proxy_pass http://indieauther$is_args$args;
+ > proxy_set_header Host $host;
+ > proxy_set_header X-Forwarded-For $remote_addr;
+ > proxy_set_header X-Forwarded-Proto $scheme;
+ > proxy_http_version 1.1;
+ > }
+ > }
+ > </pre>
+ ```nginx -s reload```
+- The IndieAuth IdP server should now be available!
+
+## Caveats
+
+While this service supports multiple users, currently these users must all be trusted due to profile registration being unconstrained. A future version may restrict profile assignment to a privileged user tier.
+
## Resource Service Integration
Other services (resources) may make calls to validate token grants by configuring a pre-shared secret, and authenticating to this server using [an HMAC-style bearer token scheme](https://git.squeep.com/?p=squeep-resource-authentication-module;a=blob_plain;f=README.md;hb=HEAD).
--
2.49.0