PostgreSQL Container for Docker Cluster

.gitignore

@@ -17,5 +17,10 @@ hypnotoad.pid
 perl5
 perl5/*
 
+#Database Container Storage
+data
+data/*
+~data/.keep
+
 #Local Docker-Compose Configuration
 docker-compose.yml

Dockerfile

@@ -6,7 +6,7 @@ RUN apt-get update &&\
     libsyntax-keyword-try-perl libcapture-tiny-perl libhttp-tinyish-perl libnet-ssleay-perl\
     liburl-encode-perl libextutils-config-perl libextutils-helpers-perl libextutils-installpaths-perl\
     libclone-choose-perl libhash-merge-perl libtest-deep-perl liburi-nested-perl\
-    libsql-abstract-perl liburi-db-perl libdbd-sqlite3-perl
+    libsql-abstract-perl liburi-db-perl libdbd-sqlite3-perl postgresql-server-dev-all
 RUN mkdir -p /usr/share/perldoc-browser/log
 COPY cpanfile cpanfile-cpandoc /usr/share/perldoc-browser/
 RUN cd /usr/share/perldoc-browser/\

docker-compose.yml.example

@@ -1,5 +1,17 @@
 version: '3'
 services:
+  db:
+    container_name: 'perldoc_db'
+    image: postgres:11.13-alpine3.14
+#    restart: always
+    ports:
+      - "5432:5432"
+    volumes:
+      - /absolute/path/to/project/data:/var/lib/postgresql/data:Z
+    environment:
+      - COMPONENT=perldoc_db
+      - POSTGRES_USER=perldoc
+      - POSTGRES_PASSWORD=secret
   web:
     container_name: 'perldoc_web'
     image: perldoc_web

etc/docker/README.pod

@@ -44,6 +44,8 @@ L<Docker Engine Installation|https://docs.docker.com/engine/install/>
 =item * The Docker Service must be running
 
 =item * Build User must have access to the Docker Service (perhaps C<root> access is required)
+ the Build User Account must be part of the C<docker> User Group as described at
+L<Post Installation Steps|https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user>
 
 =item * Current Working Directory must be the Project Root Directory
 
@@ -52,28 +54,40 @@ L<Docker Engine Installation|https://docs.docker.com/engine/install/>
 
 =back
 
-=item Build with Docker
-
-The Container Image for the C<Mojolicious> Web Service was called "I<perldoc_web>" to difference it
-from the Backend Container Image.
-So the command to build the docker image is:
-
-    docker build -t perldoc_web .
-
 =item Build with C<docker-compose>
 
-To build the Container Image with C<docker-compose> a F<docker-compose.yml> file is required.
+To build the Container Images with C<docker-compose> a F<docker-compose.yml> file is required.
 It can be created from the F<docker-compose.yml.example> file by copying it.
-Within the F<docker-compose.yml> file the entry C<services.web.volumes> must be configured to
-contain the absolute path to the Project Root Directory on the system.
+The F<docker-compose.yml> file describes two Services, C<web> and C<db>, which are the
+C<Mojolicious> Web Application as C<web> and the C<PostgreSQL> Database as C<db>.
+Within the F<docker-compose.yml> file the entries C<services.web.volumes> and C<services.db.volumes>
+must be configured to contain the absolute path to the Project Root Directory on the system.
 The F<docker-compose.yml> file contains instructions to expose the C<Mojolicious> Web Service
 on Port C<3000> which seems to be the default behaviour for the Application.
 If the Application was configured to listen on a different port the file entry C<services.web.ports>
 must be adjusted accordingly.
-So the command to build the docker image and launch it is:
+It also exposes the C<PostgreSQL> Database on Port C<5432>.
+So the command to build the docker images and launch them is:
 
     docker-compose up --build
 
+To build only the Web Service image it can be done by naming it explicitly like:
+
+    docker-compose up --build web
+
+=item Build with Docker
+
+The Container Image for the C<Mojolicious> Web Service was called "I<perldoc_web>" to difference it
+from the C<PostgreSQL> Database Backend Container Image which is called "I<perldoc_db>".
+So the commands to build the docker image is:
+
+    docker build -t perldoc_web .
+
+The C<PostgresSQL> Database Image does not need to be built. It will only be downloaded
+as it is from the C<DockerHub>. Therefore it does not have a F<Dockerfile> file.
+Any Download and initial configuration of the Database Image will happen at Start-Up
+with the C<docker-compose> command.
+
 =back
 
 =head1 IMAGE INITIALISATION
@@ -85,7 +99,7 @@ So the command to build the docker image and launch it is:
 As discussed in the task issue L<Docker Deployment Issue|https://github.com/Grinnz/perldoc-browser/issues/26> the
 installation of the I<Perl> Modules for the SQLite Backend from the F<cpanfile> was executed at Image Build Time.
 So on updates of the F<cpanfile> it is recommendable to rebuild the Container Image as described above
-under B<IMAGE BUILD>.
+under L<B<IMAGE BUILD>>.
 
 The used F<cpanfile> can be found in F</usr/share/perldoc-browser/> within the Docker Image.
 Also the C<cpanm> Installation Log is found inside the Image in F</usr/share/perldoc-browser/log/>.
@@ -96,21 +110,74 @@ To inspect the Docker Image run the command:
 
 This will give a C<bash> shell and the file system can be inspected.
 
-Still the Start-Up Script will detect a different backend configuration or the
-C<perldoc-browser.pl install> Command and check whether key dependencies are met and run the
-C<cpanm> Installation accordingly
+Still the Container Start-Up Script F<entrypoint.sh> will detect a different backend configuration
+or the C<perldoc-browser.pl install> Command and check whether the key dependencies are met
+and run the C<cpanm> Installation accordingly
+
+=item starting up the Docker Cluster
+
+The C<PostgreSQL> Database is only within the C<docker-compose> environment known with the hostname C<db>.
+So to use the database hostname C<db> any command must be run within the C<docker-compose> environment.
+To startup the Docker Cluster with the C<docker-compose> environment the following command
+is needed at first:
+
+    docker-compose up -d
+
+It is important to verify that the containers are running correctly with:
+(The Container State must be in C<Up>)
+
+    docker-compose ps
 
 =item populating the search backend
 
 The new built Container Image contains an empty C<perldoc-browser.pl> Installation
 To run correctly the Search Backend needs to be populated.
-So the command to populate the Search Backend is:
 
-   docker run -it -v /absolute/path/to/project:/home/perldoc-browser:Z perldoc_web perldoc-browser.pl index all
+Now the command to populate the Search Backend is:
+
+    docker-compose exec web entrypoint.sh perldoc-browser.pl index all
 
 This will execute command C<perldoc-browser.pl index all> in the project directory.
 The results will be stored persistently in the project directory for further container launches.
 
+=item accessing the C<PostgreSQL> Database
+
+To be able to access the database the Docker Cluster must be launched as described
+in L<B<starting up the Docker Cluster>>.
+
+Next the command C<psql> can be used within the C<PostgreSQL> container.
+The C<PostgreSQL> image is based on I<Alpine Linux>
+So a console access can be obtained with the C<docker-compose> command:
+
+    docker-compose exec db /bin/sh
+
+The default database is called "I<perldoc>" and the database login is also called "I<perldoc>".
+So to login into the database the C<psql> command is:
+
+    psql -h db -U perldoc perldoc
+
+With an initialized database the "I<perldoc>" database should contain 6 tables:
+
+    perldoc=# \dt
+		             List of relations
+     Schema |      Name       | Type  |  Owner
+    --------+-----------------+-------+---------
+     public | faqs            | table | perldoc
+     public | functions       | table | perldoc
+     public | mojo_migrations | table | perldoc
+     public | perldeltas      | table | perldoc
+     public | pods            | table | perldoc
+     public | variables       | table | perldoc
+    (6 rows)
+
+The C<pods> table can contain for 1 I<Perl> Version 1456 entries:
+
+    perldoc=# select count(*) from pods;
+     count
+    -------
+      1456
+    (1 row)
+
 =back
 
 =cut