Skip to content

Docker Deployment #36

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 20 commits into from
Apr 13, 2021
Merged
Show file tree
Hide file tree
Changes from 18 commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -6,3 +6,17 @@ html/*
perldoc-browser.conf
perldoc-browser.sqlite*
hypnotoad.pid

#Project Files
.gitignore
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this is right, .gitignore is maintained in the repository so should not be ignored by git.

.project

#Container Runtime Content
.bash_history
.cpanm
.cpanm/*
perl5
perl5/*

#Local Docker-Compose Configuration
docker-compose.yml
26 changes: 26 additions & 0 deletions Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
FROM debian:buster
RUN apt-get update &&\
apt-get -y install apt-utils gcc make openssl &&\
apt-get -y install cpanminus perl-modules perl-doc liblocal-lib-perl &&\
apt-get -y install libdbi-perl libfile-pushd-perl libipc-run3-perl libmodule-runtime-perl libsort-versions-perl libdevel-patchperl-perl libmodule-build-tiny-perl libmodule-pluggable-perl\
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
RUN mkdir -p /usr/share/perldoc-browser/log
COPY cpanfile cpanfile-cpandoc /usr/share/perldoc-browser/
RUN cd /usr/share/perldoc-browser/\
&& date +"%s" > log/cpanm_install_$(date +"%F").log\
; cpanm -vn --installdeps --with-feature=sqlite . 2>&1 >> log/cpanm_install_$(date +"%F").log\
; date +"%s" >> log/cpanm_install_$(date +"%F").log
COPY etc/docker/entrypoint.sh /usr/local/bin/
RUN chmod a+x /usr/local/bin/entrypoint.sh\
&& ln -s /usr/local/bin/entrypoint.sh /entrypoint.sh # backwards compat
RUN groupadd web &&\
useradd per1_web -g web -md /home/perldoc-browser -s /sbin/nologin &&\
chmod a+rx /home/perldoc-browser
VOLUME /home/perldoc-browser
USER per1_web
WORKDIR /home/perldoc-browser
ENTRYPOINT ["entrypoint.sh"]
CMD ["perldoc-browser.pl", "prefork"]
12 changes: 12 additions & 0 deletions docker-compose.yml.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
version: '3'
services:
web:
container_name: 'perldoc_web'
image: perldoc_web
build: .
ports:
- "3000:3000"
volumes:
- /absolute/path/to/project:/home/perldoc-browser:Z
environment:
- COMPONENT=perldoc_web
98 changes: 98 additions & 0 deletions etc/docker/README
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
NAME
Perldoc Browser - Docker Deployment

DESCRIPTION
The Objective of the "Docker Deployment" is to be able to run the
"perldoc-browser.pl" Command in a seperate Docker Container. It can be
useful to run "Test::Mojo" Test Suites.

REQUIREMENTS
To build and run the Docker Container the Minimum Requirement is to have
the "Docker" Service installed. Additionally the "docker-compose"
Command can provide a nice enhancement to ease the Operation of the
Docker Container.

INSTALLATION
docker-compose
To run the Docker Container with the "docker-compose" Command the
"docker-compose" Package should be installed first. The
"docker-compose" Package is provided by most Linux Distributions.

Docker Engine
Next the "Docker" Service has to be installed locally. if you want
to use "docker-compose" it is recommended to do this step first
because the "docker-compose" installation can break your Docker
Engine installation. To install the Docker Engine it is recommended
to follow the guides of the Official Documentation Docker Engine
Installation <https://docs.docker.com/engine/install/>

IMAGE BUILD
Preconditions

* The Docker Service must be running

* Build User must have access to the Docker Service (perhaps "root"
access is required)

* Current Working Directory must be the Project Root Directory

* The "docker-compose" Build requires a docker-compose.yml file
which can be created from the docker-compose.yml.example file

Build with Docker
The Container Image for the "Mojolicious" Web Service was called
"*perldoc_web*" to difference it from the Backend Container Image.
So the command to build the docker image is:

docker build -t perldoc_web .

Build with "docker-compose"
To build the Container Image with "docker-compose" a
docker-compose.yml file is required. It can be created from the
docker-compose.yml.example file by copying it. Within the
docker-compose.yml file the entry "services.web.volumes" must be
configured to contain the absolute path to the Project Root
Directory on the system. The docker-compose.yml file contains
instructions to expose the "Mojolicious" Web Service on Port 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 "services.web.ports" must be adjusted accordingly. So the
command to build the docker image and launch it is:

docker-compose up --build

IMAGE INITIALISATION
"cpanm" Installation
As discussed in the task issue Docker Deployment Issue
<https://github.com/Grinnz/perldoc-browser/issues/26> the
installation of the *Perl* Modules for the SQLite Backend from the
cpanfile was executed at Image Build Time. So on updates of the
cpanfile it is recommendable to rebuild the Container Image as
described above under IMAGE BUILD.

The used cpanfile can be found in /usr/share/perldoc-browser/ within
the Docker Image. Also the "cpanm" Installation Log is found inside
the Image in /usr/share/perldoc-browser/log/.

To inspect the Docker Image run the command:

docker run -it -v /absolute/path/to/project:/home/perldoc-browser:Z perldoc_web bash

This will give a "bash" shell and the file system can be inspected.

Still the Start-Up Script will detect a different backend
configuration or the "perldoc-browser.pl install" Command and check
whether key dependencies are met and run the "cpanm" Installation
accordingly

populating the search backend
The new built Container Image contains an empty "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

This will execute command "perldoc-browser.pl index all" in the
project directory. The results will be stored persistently in the
project directory for further container launches.

93 changes: 93 additions & 0 deletions etc/docker/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# NAME

Perldoc Browser - Docker Deployment

# DESCRIPTION

The Objective of the `Docker Deployment` is to be able to run the `perldoc-browser.pl` Command in
a seperate Docker Container.
It can be useful to run `Test::Mojo` Test Suites.

# REQUIREMENTS

To build and run the Docker Container the Minimum Requirement is to have the `Docker` Service installed.
Additionally the `docker-compose` Command can provide a nice enhancement to ease the Operation
of the Docker Container.

# INSTALLATION

- docker-compose

To run the Docker Container with the `docker-compose` Command the `docker-compose` Package should
be installed first. The `docker-compose` Package is provided by most Linux Distributions.

- Docker Engine

Next the `Docker` Service has to be installed locally.
if you want to use `docker-compose` it is recommended to do this step first because
the `docker-compose` installation can break your Docker Engine installation.
To install the Docker Engine it is recommended to follow the guides of the Official Documentation
[Docker Engine Installation](https://docs.docker.com/engine/install/)

# IMAGE BUILD

- Preconditions
- The Docker Service must be running
- Build User must have access to the Docker Service (perhaps `root` access is required)
- Current Working Directory must be the Project Root Directory
- The `docker-compose` Build requires a `docker-compose.yml` file which can be created
from the `docker-compose.yml.example` file
- Build with Docker

The Container Image for the `Mojolicious` Web Service was called "_perldoc\_web_" to difference it
from the Backend Container Image.
So the command to build the docker image is:

docker build -t perldoc_web .

- Build with `docker-compose`

To build the Container Image with `docker-compose` a `docker-compose.yml` file is required.
It can be created from the `docker-compose.yml.example` file by copying it.
Within the `docker-compose.yml` file the entry `services.web.volumes` must be configured to
contain the absolute path to the Project Root Directory on the system.
The `docker-compose.yml` file contains instructions to expose the `Mojolicious` Web Service
on Port `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 `services.web.ports`
must be adjusted accordingly.
So the command to build the docker image and launch it is:

docker-compose up --build

# IMAGE INITIALISATION

- `cpanm` Installation

As discussed in the task issue [Docker Deployment Issue](https://github.com/Grinnz/perldoc-browser/issues/26) the
installation of the _Perl_ Modules for the SQLite Backend from the `cpanfile` was executed at Image Build Time.
So on updates of the `cpanfile` it is recommendable to rebuild the Container Image as described above
under **IMAGE BUILD**.

The used `cpanfile` can be found in `/usr/share/perldoc-browser/` within the Docker Image.
Also the `cpanm` Installation Log is found inside the Image in `/usr/share/perldoc-browser/log/`.

To inspect the Docker Image run the command:

docker run -it -v /absolute/path/to/project:/home/perldoc-browser:Z perldoc_web bash

This will give a `bash` shell and the file system can be inspected.

Still the Start-Up Script will detect a different backend configuration or the
`perldoc-browser.pl install` Command and check whether key dependencies are met and run the
`cpanm` Installation accordingly

- populating the search backend

The new built Container Image contains an empty `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

This will execute command `perldoc-browser.pl index all` in the project directory.
The results will be stored persistently in the project directory for further container launches.
116 changes: 116 additions & 0 deletions etc/docker/README.pod
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
=head1 NAME

Perldoc Browser - Docker Deployment

=head1 DESCRIPTION

The Objective of the C<Docker Deployment> is to be able to run the C<perldoc-browser.pl> Command in
a seperate Docker Container.
It can be useful to run C<Test::Mojo> Test Suites.

=head1 REQUIREMENTS

To build and run the Docker Container the Minimum Requirement is to have the C<Docker> Service installed.
Additionally the C<docker-compose> Command can provide a nice enhancement to ease the Operation
of the Docker Container.

=head1 INSTALLATION

=over

=item docker-compose

To run the Docker Container with the C<docker-compose> Command the C<docker-compose> Package should
be installed first. The C<docker-compose> Package is provided by most Linux Distributions.

=item Docker Engine

Next the C<Docker> Service has to be installed locally.
if you want to use C<docker-compose> it is recommended to do this step first because
the C<docker-compose> installation can break your Docker Engine installation.
To install the Docker Engine it is recommended to follow the guides of the Official Documentation
L<Docker Engine Installation|https://docs.docker.com/engine/install/>

=back

=head1 IMAGE BUILD

=over 4

=item Preconditions

=over 2

=item * The Docker Service must be running

=item * Build User must have access to the Docker Service (perhaps C<root> access is required)

=item * Current Working Directory must be the Project Root Directory

=item * The C<docker-compose> Build requires a F<docker-compose.yml> file which can be created
from the F<docker-compose.yml.example> file

=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.
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 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:

docker-compose up --build

=back

=head1 IMAGE INITIALISATION

=over

=item C<cpanm> Installation

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>.

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/>.

To inspect the Docker Image run the command:

docker run -it -v /absolute/path/to/project:/home/perldoc-browser:Z perldoc_web bash

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

=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

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.

=back

=cut
Loading