From e2ac294482c127cf987740cc5a3b02cfbedd3473 Mon Sep 17 00:00:00 2001 From: "Karl O. Pinc" Date: Tue, 21 Jan 2025 14:30:44 -0600 Subject: [PATCH] Improve documentation --- make_files/make_cluster.mk | 51 +++++++++++++++++++++++++++++++------- 1 file changed, 42 insertions(+), 9 deletions(-) diff --git a/make_files/make_cluster.mk b/make_files/make_cluster.mk index c18187a..ce84a9d 100644 --- a/make_files/make_cluster.mk +++ b/make_files/make_cluster.mk @@ -81,19 +81,40 @@ ## ## If you are not on Azure and have a PostgreSQL installation: ## -## 1) If you already have a Postgres role that can login, create -## roles, and create databases then that role should be used as -## the administrative user. If this role is your personal role, -## after step 2, execute "GRANT admin TO YourRole;" and skip step -## 3. Otherwise, first create an administrative user (while -## logged in to Unix as root) with "create-adminuser". +## 1) Create the cluster with the "init-cluster" target. +## Caution: The version of PG is hardcoded and will need +## adjustment. Further, this uses the pg_createcluster command, +## which is available only on Debian derivatives. See the target, +## below, for instructions. ## -## 2) Use the administrative user to create the "group" roles -## ("create-groups"). +## At this point, adjust the configuration of your new cluster. +## CAUTION: The default is to allow local users to connect to +## their own databases without a password, this is not desirable. +## (Be sure the Unix "postgres" user can still login without a +## password.) Adjustment may be manual, or via ansible, puppet, +## etc. +## +## 2) If you already have a Postgres role that can login and create +## roles, a role like the Postgres bootstrap superuser that will +## never be deleted, then use that user to create the "group" +## roles with the "create-groups" target. ## ## Hint: Use TARGET_DB=postgres for this, since your new database ## won't yet exist. ## +## If you don't have such a role, you'll need to use the default +## superuser. First, you'll need to: +## +## make db/creategroups.sql +## +## Then, invoke "make" as a regular Unix user with: +## +## sudo -u postgres make TARGET_DB=postgres create-groups +## +## Or alternately, as a the Unix root user with: +## +## su postgres -c 'make TARGET_DB=postgres create-groups' +## ## 3) Use the SokweDB tools to create a (personal) SokweDB ## administrative user. Use this user from this point forward ## when performing administrative tasks. A personal development @@ -105,6 +126,18 @@ ## ## Tip: If using psql, use the "\password" command to set passwords. ## +## CAUTION: Use a role that will always exist, not a role +## belonging to a person but a role such as the default Postgres +## superuser, as the "administrative user" whenever creating an +## administrative user. (You must use the default Postgres +## superuser when you do not have a Postgres role that can login +## and create groups.) If you do not use a role that always +## exists, then the created role will lose its administrative +## privilege when the creating role is dropped. Use the Unix +## privilege escalation techniques described in step 2, above, to +## execute the SOKWEDB command line tool in an environment that +## gives the tool access to the Postgres superuser. +## ## 4) Create the databases ("init-database"). SokweDB is expecting ## databases named "sokwedb", "sokwedb_test", and "sokwedb_dev". ## @@ -118,7 +151,7 @@ ## ## After cluster initialization create at least one login for an ## individual using the administrative user. Give the logins -## elevated priviliges with the INHERIT, CREATEUSER, and CREATEDB +## elevated privileges with the INHERIT, CREATEUSER, and CREATEDB ## attributes, and all available Postgres "pre-defined roles" ## (https://www.postgresql.org/docs/current/predefined-roles.html), ## and by putting them into the admin group. It is easiest to do all -- 2.34.1