2023-02-07 pgadmin4 - master branch

.templates/pgadmin4/service.yml

@@ -0,0 +1,12 @@
+pgadmin4:
+  container_name: pgadmin4
+  image: gpongelli/pgadmin4-arm:latest-armv7
+  platform: linux/arm/v7
+# image: gpongelli/pgadmin4-arm:latest-armv8
+  restart: unless-stopped
+  environment:
+  - TZ=${TZ:-Etc/UTC}
+  ports:
+  - "5050:5050"
+  volumes:
+  - ./volumes/pgadmin4:/pgadmin4

.templates/postgres/service.yml

@@ -1,13 +1,14 @@
-  postgres:
-    container_name: postgres
-    image: postgres
-    restart: unless-stopped
-    environment:
-      - POSTGRES_USER=${IOTSTACK_POSTGRES_USER:-postuser}
-      - POSTGRES_PASSWORD=${IOTSTACK_POSTGRES_INITIAL_PASSWORD:-IOtSt4ckpostgresDbPw} # Initial password when creating container, to change later see https://sensorsiot.github.io/IOTstack/Containers/PostgreSQL/
-      - POSTGRES_DB=postdb
-    ports:
-      - "5432:5432"
-    volumes:
-      - ./volumes/postgres/data:/var/lib/postgresql/data
-
+postgres:
+  container_name: postgres
+  image: postgres
+  restart: unless-stopped
+  environment:
+  - TZ=${TZ:-Etc/UTC}
+  - POSTGRES_USER=${POSTGRES_USER:-postuser}
+  - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-IOtSt4ckpostgresDbPw}
+  - POSTGRES_DB=${POSTGRES_DB:-postdb}
+  ports:
+  - "5432:5432"
+  volumes:
+  - ./volumes/postgres/data:/var/lib/postgresql/data
+  - ./volumes/postgres/db_backup:/backup

docs/Containers/PgAdmin4.md

@@ -0,0 +1,77 @@
+# pgAdmin4
+
+## References
+
+- [Docker Hub](https://hub.docker.com/r/gpongelli/pgadmin4-arm)
+- [GitHub](https://github.com/gpongelli/pgadmin4-docker-arm/)
+- [pgAdmin4 home page](https://www.pgadmin.org)
+
+## About
+
+pgAdmin4 is a graphical user interface to PostgreSQL.
+
+## Configuration
+
+### Runtime image
+
+The service definition includes the following lines:
+
+``` yaml
+  image: gpongelli/pgadmin4-arm:latest-armv7
+  platform: linux/arm/v7
+# image: gpongelli/pgadmin4-arm:latest-armv8
+```
+
+The ARMv7 image is enabled by default. This will run on both 32-bit (ARMv7) and 64-bit (ARMv8) systems. The `platform` clause silences warnings from docker-compose that arise when you try to run an ARMv7 image on ARMv8 architecture.
+
+If you are running on a full 64-bit system, you should edit your service definition so that it looks like this:
+
+``` yaml
+# image: gpongelli/pgadmin4-arm:latest-armv7
+# platform: linux/arm/v7
+  image: gpongelli/pgadmin4-arm:latest-armv8
+```
+
+### Container Time Zone
+
+The service definition includes the `TZ` environment variable. It defaults to `Etc/UTC`. You can either edit the environment variable directly in your compose file, or provide your own substitute by editing `~/IOTstack/.env`. Example:
+
+``` console
+$ cat ~/IOTstack/.env
+TZ=Australia/Sydney
+```
+
+## First run
+
+These instructions assume you have selected the `postgresql` container from the IOTstack menu, and that that container is running.
+
+Complete the following steps:
+
+1. Use your web browser to connect to pgAdmin4 on port `5050`. For example:
+
+	* `http://raspberrypi.local:5050`
+
+	The pgAdmin4 service takes a while to start so please be patient if you have only just launched the container. Once your browser is able to connect to pgAdmin4 successfully, the home screeen will be displayed, overlaid with a prompt to enter a master password:
+
+	![](images/pgadmin4-initial.jpeg)
+
+2. Enter a master password.
+3. Click "OK" to set the master password. The dialog will disappear leaving the home screen.
+4. Click "Add New Server". This displays the server registration sheet:
+
+	![](images/pgadmin4-general.jpeg)
+
+5. Give the server a name. The name is not important. It just needs to be meaningful to you.
+6. Click the "Connection" tab:
+
+	![](images/pgadmin4-connection.jpeg)
+
+7. Enter the name of the PostgreSQL container (ie "postgres").
+8. The default port is 5432. This is the **internal** port number the PostgreSQL container is listening on. It is unlikely that you will need to change this.
+9. In the "Maintenance database" field, enter the *value* of the `POSTGRES_DB` environment variable as it applies to the PostgreSQL container.
+10. In the "Username" field, enter the *value* of the `POSTGRES_USER` environment variable as it applies to the PostgreSQL container.
+11. In the "Password" field, enter the *value* of the `POSTGRES_PASSWORD` environment variable as it applies to the PostgreSQL container.
+12. Enable the "Save password" switch if you think that is appropriate.
+13. Click the "Save" button.
+
+Keep in mind that the values of the environment variables you set in steps 9, 10 and 11 only apply the first time you launch the PostgreSQL container. If you change any of these in PostgreSQL, you will have to make matching changes in pgAdmin4.

docs/Containers/PostgreSQL.md

@@ -1,5 +1,7 @@
 # PostgreSQL
+
 ## References
+
 - [Docker image](https://hub.docker.com/_/postgres)
 - [Postgre SQL Homepage](https://www.postgresql.org/)
 - [Postgre SQL docs](https://www.postgresql.org/docs/current/index.html)
@@ -12,25 +14,78 @@ The database is available on port `5432`
 
 ## Configuration
 
-Optional variables to define in `~/IOTstack/.env`:
+The service definition includes the following environment variables:
+
+* `TZ` your timezone. Defaults to `Etc/UTC`
+* `POSTGRES_USER`. Initial username. Defaults to `postuser`.
+* <a name="postgrespw"></a>`POSTGRES_PASSWORD`. Initial password associated with initial username. Defaults to `IOtSt4ckpostgresDbPw` (`postpassword` for old menu).
+* `POSTGRES_DB`. Initial database. Defaults to `postdb`.
+
+You can either edit the environment variables directly or provide your own substitutes by editing `~/IOTstack/.env`. Example:
+
+``` console
+$ cat ~/IOTstack/.env
+TZ=Australia/Sydney
+POSTGRES_PASSWORD=oneTwoThree
+```
+
+When the container is brought up:
+
+* `TZ` will have the value `Australia/Sydney` (from `.env`)
+* `POSTGRES_PASSWORD` will have the value `oneTwoThree` (from `.env`)
+* `POSTGRES_USER` will have the value `postuser` (the default); and
+* `POSTGRES_DB` will have the value `postdb` (the default).
 
-* `IOTSTACK_postgres_PASSWORD` database password, defaults to
-  *IOtSt4ckpostgresDbPw*.
-* `IOTSTACK_postgres_user` database user, defaults to *postuser*.
+The `TZ` variable takes effect every time the container is brought up. The other environment variables only work the first time the container is brought up.
 
-It is highly recommended to change the password. (For old-menu the database
-credentials can be found in the file `./volumes/postgres/postgres.env`.)
+It is highly recommended to select your own password before you launch the container for the first time. See also [Getting a clean slate](#cleanSlate).
 
 ## Management
 
-You can interact with the postgress in the container with the command:
+You can interact with the PostgreSQL Relational Database Management System running in the container via its `psql` command. You can invoke `psql` like this:
+
 ``` console
-$ docker exec -it postgres psql -d postdb -U postuser
+$ docker exec -it postgres bash -c 'PGPASSWORD=$POSTGRES_PASSWORD psql $POSTGRES_DB $POSTGRES_USER'
 ```
 
-Once you have logged in you can reset the password for postuser replacing
-`<<password>>` with your new password:
+> Because of the single quotes (<kbd>'</kbd>) surrounding everything after the `-c`, expansion of the environment variables is deferred until the command is executed *inside* the container.
+
+You can use any of the following methods to exit `psql`:
+
+* Type "\q" and press <kbd>return</kbd>
+* Type "exit" and press <kbd>return</kbd>
+* Press <kbd>control</kbd>+<kbd>D</kbd>
+
+### password change
+
+Once you have logged into `psql` you can reset the password like this:
+
 ``` sql
-ALTER USER postuser WITH PASSWORD '<<password>>';
+# ALTER USER «user» WITH PASSWORD '«password»';
 ```
 
+Replace:
+
+* `«user»` with the username (eg the default username is `postuser`)
+* `«password»` with your new password.
+
+Notes:
+
+* Changing the password via the `ALTER` command does **not** update the value of the [`POSTGRES_PASSWORD`](#postgrespw) environment variable. You need to do that by hand.
+* Whenever you make a change to a running container's environment variables, the changes will not take effect until you re-create the container by running:
+
+	``` console
+	$ cd ~/IOTstack
+	$ docker-compose up -d postgresql
+	```
+
+## Getting a clean slate {cleanSlate}
+
+If you need to start over, proceed like this:
+
+``` console
+$ cd ~/IOTstack
+$ docker-compose rm --force --stop -v postgres
+$ sudo rm -rf ./volumes/postgres
+$ docker-compose up -d postgres
+```